View source for Spawnscript

[[Category:Level]]
'''spawnscript''' is a level spawn-entry event hook. It executes when its specific spawn entry creates an entity, after OpenBOR has applied the entry's spawn properties and executed the entity's applicable [[Onspawnscript|onspawnscript]].

Unlike <code>onspawnscript</code>, which belongs to a model, <code>spawnscript</code> belongs to an individual entry in a level. Separate instances of the same model can therefore receive different roles, objectives, relationships, controller data, or custom behavior without creating additional models. This makes <code>spawnscript</code> especially useful for encounter construction and other sequence-heavy level design.

== Usage ==

Add <code>spawnscript</code> to a level spawn entry and provide the path to the script file. The command must appear before the entry's <code>at</code> command:

<syntaxhighlight lang="text">
spawn dock_thug
coords 520 230 0
spawnscript data/scripts/spawns/dock_flanker.c
at 400
</syntaxhighlight>

The referenced script uses a <code>main()</code> entry point. OpenBOR populates the event variables immediately before calling it.

<syntaxhighlight lang="c" line>
void main()
{
    void self = getlocalvar("self");
    float spawn_x = getlocalvar("spawnx");
    float spawn_z = getlocalvar("spawnz");
    float spawn_y = getlocalvar("spawny");
    int spawn_at = getlocalvar("spawnat");

    // Configure this specific spawn instance here.
}
</syntaxhighlight>

Each spawn entry owns its own <code>spawnscript</code>. Reusing the same script file across several entries provides common behavior, while assigning different files allows each entry to perform unique setup.

== Inline Script ==

Spawn entries also support inline script blocks. Place the block before <code>at</code>, just like an external <code>spawnscript</code> file:

<syntaxhighlight lang="text">
spawn dock_thug
coords 520 230 0

@script
void main()
{
    void self = getlocalvar("self");

    setentityvar(self, "encounter_role", "dock_flanker");
    setentityvar(self, "encounter_wave", 2);
}
@end_script

at 400
</syntaxhighlight>

Inline form is convenient for concise entry-specific setup. External files are generally easier to reuse when several entries share behavior or the setup requires multiple functions.

== Execution ==

The relevant spawn sequence is:

# A level spawn entry reaches its configured <code>at</code> condition.
# OpenBOR creates the entity and applies the entry's model, alias, palette, health, coordinates, item, weapon, parent, and other configured spawn properties.
# The applicable global model <code>onspawnscript</code> executes when present.
# The entity model's [[Onspawnscript|onspawnscript]] executes when present.
# The level entry's <code>spawnscript</code> executes when present.
# OpenBOR returns the completed entity to normal level processing.

The entity is fully available through <code>self</code> when <code>spawnscript</code> runs. Entry-specific setup can therefore inspect or modify the entity, establish references to other objects, initialize custom variables, select an animation or action, create supporting objects, or communicate with encounter controllers.

Since <code>onspawnscript</code> executes first, <code>spawnscript</code> can build on or specialize the model's normal initialization. This ordering supports a useful division of responsibility: let the model establish what every instance needs, then let the level entry establish what this particular instance should do.

== Event Data ==

{| class="wikitable sortable"
! Variable
! Type
! Description
|-
| <code>self</code>
| Object pointer
| Entity created by the spawn entry.
|-
| <code>spawnx</code>
| Decimal
| X coordinate supplied by the spawn entry.
|-
| <code>spawnz</code>
| Decimal
| Z coordinate supplied by the spawn entry.
|-
| <code>spawny</code>
| Decimal
| Y coordinate supplied by the spawn entry. This is the third value of <code>coords</code> and represents vertical altitude.
|-
| <code>spawnat</code>
| Integer
| Trigger value supplied by the spawn entry's <code>at</code> command.
|}

The coordinate variables describe the level entry's configured spawn point. They do not dynamically follow later movement or changes made to the entity's position. Read the applicable entity properties from <code>self</code> when the current position is required.

== Spawnscript and Onspawnscript ==

The two hooks execute in the same creation sequence but serve different scopes.

{| class="wikitable"
! Property
! spawnscript
! onspawnscript
|-
| Owner
| Individual level spawn entry
| Model
|-
| Coverage
| Only the entry containing the script
| Applicable instances of the model
|-
| Setup location
| Level definition, before <code>at</code>
| Model definition
|-
| Execution order
| After <code>onspawnscript</code>
| Before <code>spawnscript</code>
|-
| Event data
| Created entity, entry coordinates, and <code>at</code> value
| Created entity
|-
| Typical responsibility
| Encounter-specific role and level context
| Universal model initialization
|}

Neither hook replaces the other. Models can use <code>onspawnscript</code> for reliable baseline setup while levels use <code>spawnscript</code> to turn individual instances into guards, flankers, escorts, leaders, targets, hazards, controllers, or any other role required by the encounter.

== Example: Assign an Encounter Role ==

The following compact script marks the spawned entity as a flanker and preserves its entry coordinates as a formation anchor:

<syntaxhighlight lang="c" line>
void main()
{
    void self = getlocalvar("self");

    setentityvar(self, "encounter_role", "flanker");
    setentityvar(self, "encounter_wave", 2);

    setentityvar(
        self,
        "formation_anchor_x",
        getlocalvar("spawnx")
    );

    setentityvar(
        self,
        "formation_anchor_z",
        getlocalvar("spawnz")
    );
}
</syntaxhighlight>

The model's update, think, animation, or key scripts can consume these values later. Another entry using the same model can assign a different role and parameters, allowing one model to participate in several coordinated behaviors within the same encounter.

== Example: Register With a Wave Controller ==

Spawn scripts can also publish entry-specific information for a shared controller:

<syntaxhighlight lang="c" line>
void main()
{
    void self = getlocalvar("self");
    int wave_count = getglobalvar("dock_wave_2_count");

    setentityvar(self, "wave_id", 2);
    setentityvar(self, "spawn_trigger", getlocalvar("spawnat"));

    setglobalvar("dock_wave_2_count", wave_count + 1);
    setglobalvar("dock_wave_2_last_member", self);
}
</syntaxhighlight>

This small handshake is enough for other scripts to track arrivals, wait for a group to be defeated, release reinforcements, update an objective, or coordinate a multi-part encounter. The controller design remains creator-defined; <code>spawnscript</code> supplies a precise event for registering each member as it enters play.

== Other Uses ==

Quick applications include:

* '''Encounter roles''' - Mark identical model instances as leaders, guards, flankers, escorts, reinforcements, targets, or support units.
* '''Formation data''' - Preserve spawn coordinates as patrol anchors, defensive positions, retreat points, or movement boundaries.
* '''Wave management''' - Register members with shared controllers, update counters, identify groups, or release later sequences.
* '''Entry-specific behavior''' - Select custom AI modes, aggression rules, dialogue, objectives, relationships, or reactions for one appearance of a model.
* '''Randomization''' - Choose equipment, palettes, resources, movement patterns, or encounter roles when the entity enters play.
* '''Object relationships''' - Connect the new entity to leaders, escorts, targets, hazards, switches, or other level objects.
* '''Presentation''' - Trigger entry effects, labels, sounds, camera responses, or custom introductions associated with a specific spawn.
* '''Debugging and analytics''' - Record which entry created an entity, its configured coordinates, and the point in the level where it appeared.

== Related Scripts ==

{| class="wikitable"
! Script
! Relationship
|-
| [[Onspawnscript|onspawnscript]]
| Model hook that executes before <code>spawnscript</code> and provides universal initialization for applicable model instances.
|-
| '''spawnscript'''
| Level entry hook that specializes the newly created entity for one particular spawn.
|-
| [[Levelscript|levelscript]]
| Executes once when the level begins and can prepare shared encounter state before spawn entries activate.
|-
| [[Updateentityscript|updateentityscript]]
| Recurring model hook that can consume roles and parameters assigned by <code>spawnscript</code>.
|-
| [[Thinkscript|thinkscript]]
| Model decision hook that can use entry-specific state when selecting behavior.
|}

== See Also ==

* [[Level]]
* [[Onspawnscript]]
* [[Levelscript]]
* [[Updateentityscript]]
* [[Thinkscript]]
* [[Script Overview]]
[[Category:OpenBOR Index]]
[[Category:Script Events]]