Dcurrent at 19:56, 20 August 2026

2026-08-20T19:56:12Z

← Older revision		Revision as of 14:56, 20 August 2026
Line 176:		Line 176:
	* [[Onspawnscript]]		* [[Onspawnscript]]
	* [[Script Overview]]		* [[Script Overview]]
			[[Category:Openbor]]

Dcurrent: Created page with "Category:Level Category:Script '''levelscript''' is a level-start event hook. OpenBOR provides two forms: the automatic project-wide `data/scripts/level.c` script and a `levelscript` declared by an individual level. Both execute once after the level is loaded and active players are spawned, but before normal level updates begin. This timing makes level scripts ideal for establishing the initial state of a stage. Common uses include resetti..."

2026-08-20T19:55:48Z

Created page with "Category:Level Category:Script '''levelscript''' is a level-start event hook. OpenBOR provides two forms: the automatic project-wide <code>data/scripts/level.c</code> script and a <code>levelscript</code> declared by an individual level. Both execute once after the level is loaded and active players are spawned, but before normal level updates begin. This timing makes level scripts ideal for establishing the initial state of a stage. Common uses include resetti..."

New page

[[Category:Level]]
[[Category:Script]]

'''levelscript''' is a level-start event hook. OpenBOR provides two forms: the automatic project-wide <code>data/scripts/level.c</code> script and a <code>levelscript</code> declared by an individual level. Both execute once after the level is loaded and active players are spawned, but before normal level updates begin.

This timing makes level scripts ideal for establishing the initial state of a stage. Common uses include resetting counters, preparing objectives, configuring shared systems, setting level-specific rules, initializing player state, and spawning controller entities.

== Forms ==

{| class="wikitable"
! Form
! Scope
! Setup
! Execution order
|-
| Global level script
| Every level in the project
| Create <code>data/scripts/level.c</code>
| First
|-
| Level-specific script
| Level containing the command
| Add <code>levelscript</code> to the level definition
| Second
|}

Both forms use a <code>main()</code> entry point and receive no automatic event variables.

== Global Level Script ==

OpenBOR automatically loads <code>data/scripts/level.c</code> when the file is present. No command is required in a level definition.

<syntaxhighlight lang="c" line>
void main()
{
// Perform project-wide level initialization here.
}
</syntaxhighlight>

The global script executes at the start of every level. Use it for initialization that should be consistent throughout the project, such as clearing stage statistics, preparing common HUD logic, resetting shared objectives, or activating a universal level controller.

== Level-Specific Script ==

Add <code>levelscript</code> to a level definition and provide the path to the script file:

<syntaxhighlight lang="text">
levelscript data/scripts/levels/storm_docks_start.c
</syntaxhighlight>

The referenced script uses the same entry point as the global form:

<syntaxhighlight lang="c" line>
void main()
{
// Perform initialization for this level here.
}
</syntaxhighlight>

The level-specific script executes only when OpenBOR starts the level containing the command. It is well suited to objectives, environmental rules, encounter controllers, scripted introductions, alternate HUD modes, or other setup unique to that level.

Only one <code>levelscript</code> command is available to a level. Multiple initialization tasks may be organized into functions and called from the script's <code>main()</code> when needed.

== Execution ==

The relevant level-start sequence is:

# OpenBOR loads and configures the level.
# OpenBOR resets the new level's immediate runtime state.
# Active players with remaining lives are spawned.
# <code>data/scripts/level.c</code> executes when present.
# The level-specific <code>levelscript</code> executes when declared.
# OpenBOR enters the normal update loop.

Level data and active player entities are therefore available to both scripts. Ordinary level progression and the first normal update cycle have not yet begun.

The level-specific script executes after the global script, so it can build on or override state established by <code>level.c</code>. This ordering supports a useful division of responsibility: define project defaults globally, then specialize them for the current level.

Level scripts are start events, not recurring updates. Logic that must run continuously belongs in an update script, an entity script, or another appropriate event hook.

== Example: Shared and Level-Specific Setup ==

The following <code>data/scripts/level.c</code> resets several values used throughout a project whenever a level begins:

<syntaxhighlight lang="c" line>
void main()
{
setglobalvar("stage_hit_count", 0);
setglobalvar("stage_damage_total", 0);
setglobalvar("stage_objective_complete", 0);
}
</syntaxhighlight>

An individual level can then define its own objective and environmental profile:

<syntaxhighlight lang="text">
levelscript data/scripts/levels/storm_docks_start.c
</syntaxhighlight>

<syntaxhighlight lang="c" line>
void main()
{
setglobalvar("stage_objective", "protect_convoy");
setglobalvar("stage_weather", "storm");
setglobalvar("stage_reinforcement_limit", 3);
}
</syntaxhighlight>

Recurring scripts, HUD logic, spawn scripts, and model scripts may read these values later. The example is intentionally compact - the same arrangement can initialize far more elaborate objective managers, branching encounters, weather controllers, scoring rules, or cinematic systems.

== Example: Preparing Active Players ==

Active player entities already exist when the event runs. This allows a global level script to mark or configure them before the first ordinary update:

<syntaxhighlight lang="c" line>
void main()
{
int player;
int player_count = openborvariant("maxplayers");

for (player = 0; player < player_count; player++)
{
void entity = getplayerproperty(player, "entity");

if (entity)
{
setentityvar(entity, "stage_ready", 1);
}
}
}
</syntaxhighlight>

Other systems can consume <code>stage_ready</code> to begin entrance behavior, apply level-specific equipment, initialize challenge conditions, or coordinate multiplayer presentation. Keeping the start hook focused on setup allows the ongoing behavior to remain in the scripts designed to update it.

== Other Uses ==

Quick applications include:

* '''Objective setup''' - Establish targets, timers, counters, failure conditions, escort data, or challenge rules.
* '''System reset''' - Clear per-stage statistics, temporary resources, encounter flags, or branching state.
* '''Player preparation''' - Apply stage-specific status, equipment, positioning rules, interface modes, or cooperative roles.
* '''Environment control''' - Initialize weather, lighting, palette, camera, audio, or hazard controllers.
* '''Encounter management''' - Spawn or configure invisible controller entities that coordinate complex sequences.
* '''Presentation''' - Prepare introductions, title cards, dialogue systems, custom HUD elements, or cinematic logic.
* '''Project defaults''' - Use <code>level.c</code> to establish a common baseline, then let individual levels replace only the values they need.

== Related Scripts ==

{| class="wikitable"
! Script
! Relationship
|-
| <code>data/scripts/level.c</code>
| Global start hook that executes first for every level.
|-
| '''levelscript'''
| Level-specific start hook that executes after the global hook.
|-
| [[Update Script|update and updated scripts]]
| Recurring global or level hooks used during normal gameplay updates.
|-
| [[Spawnscript|spawnscript]]
| Executes for an individual spawn entry when that entry creates an entity.
|-
| [[Onspawnscript|onspawnscript]]
| Executes from the spawned entity's model after the entity enters play.
|-
| [[Endlevelscript|endlevelscript]]
| Executes when the level finishes, before fade-out and level unloading.
|}

== See Also ==

* [[Level]]
* [[Endlevelscript]]
* [[Spawnscript]]
* [[Onspawnscript]]
* [[Script Overview]]

Level Scripts - Revision history

Dcurrent at 19:56, 20 August 2026