Spawnscript

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.

Unlike onspawnscript, which belongs to a model, spawnscript 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 spawnscript especially useful for encounter construction and other sequence-heavy level design.

Usage

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

spawn dock_thug
coords 520 230 0
spawnscript data/scripts/spawns/dock_flanker.c
at 400

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

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.
}

Each spawn entry owns its own spawnscript. 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 at, just like an external spawnscript file:

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

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 at 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 onspawnscript executes when present.
The entity model's onspawnscript executes when present.
The level entry's spawnscript executes when present.
OpenBOR returns the completed entity to normal level processing.

The entity is fully available through self when spawnscript 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 onspawnscript executes first, spawnscript 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

Variable	Type	Description
`self`	Object pointer	Entity created by the spawn entry.
`spawnx`	Decimal	X coordinate supplied by the spawn entry.
`spawnz`	Decimal	Z coordinate supplied by the spawn entry.
`spawny`	Decimal	Y coordinate supplied by the spawn entry. This is the third value of `coords` and represents vertical altitude.
`spawnat`	Integer	Trigger value supplied by the spawn entry's `at` 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 self when the current position is required.

Spawnscript and Onspawnscript

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

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 `at`	Model definition
Execution order	After `onspawnscript`	Before `spawnscript`
Event data	Created entity, entry coordinates, and `at` value	Created entity
Typical responsibility	Encounter-specific role and level context	Universal model initialization

Neither hook replaces the other. Models can use onspawnscript for reliable baseline setup while levels use spawnscript 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:

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")
    );
}

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:

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);
}

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; spawnscript 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

Script	Relationship
onspawnscript	Model hook that executes before `spawnscript` and provides universal initialization for applicable model instances.
spawnscript	Level entry hook that specializes the newly created entity for one particular spawn.
levelscript	Executes once when the level begins and can prepare shared encounter state before spawn entries activate.
updateentityscript	Recurring model hook that can consume roles and parameters assigned by `spawnscript`.
thinkscript	Model decision hook that can use entry-specific state when selecting behavior.