View source for Player Die Scripts

[[Category:Player]]
[[Category:Script]]
[[Category:Script Events]]

'''Die scripts''' are global player events that execute when OpenBOR processes a native player death and life loss. Numbered scripts provide slot-specific behavior, while <code>dieall.c</code> provides one shared listener for every player.

The numbered series consists of:

* <code>data/scripts/die1.c</code>
* <code>data/scripts/die2.c</code>
* <code>data/scripts/die3.c</code>
* <code>data/scripts/die4.c</code>

The shared listener is:

* <code>data/scripts/dieall.c</code>

OpenBOR distinguishes an entity entering a dead state, a player losing a life, and an entity being killed or removed from play. The Die series represents the player-life event. This makes it useful for life-loss penalties, cooperative defeat handling, continue systems, player-specific statistics, encounter adjustment, audiovisual feedback, and any other system that should respond when a player leaves active play through the native death routine.

== Usage ==

Create any desired Die-script files in <code>data/scripts</code>. OpenBOR loads them automatically, so no model, level, or project command is required.

<code>die#.c</code> is documentation shorthand in which <code>#</code> represents the player number. Literal filenames use <code>1</code> through <code>4</code>.

{| class="wikitable"
! File
! Scope
! Player identification
|-
| <code>data/scripts/die1.c</code>
| Player 1
| Filename - index <code>0</code>
|-
| <code>data/scripts/die2.c</code>
| Player 2
| Filename - index <code>1</code>
|-
| <code>data/scripts/die3.c</code>
| Player 3
| Filename - index <code>2</code>
|-
| <code>data/scripts/die4.c</code>
| Player 4
| Filename - index <code>3</code>
|-
| <code>data/scripts/dieall.c</code>
| Every player
| Local variable <code>playerindex</code>
|}

Projects may use only the numbered files, only <code>dieall.c</code>, or both layers together.

== Die Event ==

The Die series executes when OpenBOR's native player-death routine processes a player leaving active play. Common causes include completing a normal defeat sequence, falling into a pit, moving beyond the permitted off-screen boundary, or another condition routed through native player death handling.

This event is not a general entity-death listener. It does not execute merely because an entity enters a dead state or because <code>killentity()</code> removes an entity through an unrelated path. The event belongs specifically to player-slot life processing.

Each native player death runs the applicable Die-script chain once. If the player has another life, OpenBOR later creates the replacement player entity and executes the [[Respawn Scripts|Respawn series]]. If no lives remain, the Respawn series does not follow.

== Execution Order ==

OpenBOR performs the relevant player-death sequence in this order:

# OpenBOR identifies the dying entity's player slot.
# The player's life count is reduced when native life deduction is active.
# The corresponding numbered script, <code>die1.c</code> through <code>die4.c</code>, executes when present.
# <code>dieall.c</code> executes when present and receives <code>playerindex</code>.
# OpenBOR clears the player slot's entity reference and stores health and magic values for a possible respawn.
# OpenBOR removes the old entity or leaves an inert corpse according to the model's death configuration.
# If no lives remain, OpenBOR performs the applicable continue or game-over preparation and ends the death routine.
# If lives remain, OpenBOR creates the replacement player entity and executes the numbered and shared Respawn scripts.
# Native post-respawn enemy-drop, rumble, and timer-reset behavior continues as configured.

The player's remaining-life value is already current when either Die-script layer begins. The dying entity is also still assigned to the player slot and can be retrieved through the player property API during the event.

The numbered script always executes before <code>dieall.c</code>. Shared logic can consequently consume state established by the slot-specific script during the same death event.

== Numbered Die Scripts ==

Numbered Die scripts are tied to the player slot identified by their filename. They receive no automatic event variables because the player identity is already fixed by that filename.

<syntaxhighlight lang="c" line>
void main()
{
    // die3.c always represents Player 3, player index 2.
    setglobalvar("player_three_defeated", 1);
    setglobalvar("party_state_changed", 1);
}
</syntaxhighlight>

Slot-specific files are convenient for asymmetric penalties, unique defeat effects, fixed cooperative roles, individual statistics, or other behavior tied to one player position.

== Dieall ==

<code>dieall.c</code> is the shared listener for every player slot. OpenBOR supplies one automatic local variable:

{| class="wikitable"
! Variable
! Type
! Description
|-
| <code>playerindex</code>
| Integer
| Zero-based index of the player whose native death routine is being processed. Values range from <code>0</code> through <code>3</code> for Players 1 through 4.
|}

<syntaxhighlight lang="c" line>
void main()
{
    int remaining_lives = getplayerproperty(playerindex, "lives");

    setglobalvar("last_defeated_playerindex", playerindex);
    setglobalvar("last_defeat_remaining_lives", remaining_lives);
}
</syntaxhighlight>

The zero-based index matches OpenBOR's player property and scripting conventions:

{| class="wikitable"
! <code>playerindex</code>
! Player label
! Corresponding numbered script
|-
| <code>0</code>
| Player 1
| <code>die1.c</code>
|-
| <code>1</code>
| Player 2
| <code>die2.c</code>
|-
| <code>2</code>
| Player 3
| <code>die3.c</code>
|-
| <code>3</code>
| Player 4
| <code>die4.c</code>
|}

<code>dieall.c</code> does not receive an automatic entity reference. The dying entity remains available from the player slot until both Die-script layers finish:

<syntaxhighlight lang="c" line>
void main()
{
    void dying_entity = getplayerproperty(playerindex, "entity");

    if (dying_entity)
    {
        setglobalvar("defeat_effect_playerindex", playerindex);
    }
}
</syntaxhighlight>

Creators can use <code>dying_entity</code> immediately with entity properties, visual effects, audio ownership, bindings, or other systems that operate on an active entity reference. OpenBOR clears the player slot's reference after <code>dieall.c</code> returns.

== Life Count Timing ==

Native life deduction occurs before the Die scripts. Reading the player's <code>lives</code> property therefore returns the remaining count rather than the count that existed before death.

OpenBOR decides between exhausted-life handling and respawn only after both Die-script layers finish. Creators may therefore modify the remaining life count during the event to implement shared-life pools, revive tokens, insurance systems, checkpoint allowances, or other custom continuation rules.

<syntaxhighlight lang="c" line>
void main()
{
    int remaining_lives = getplayerproperty(playerindex, "lives");
    int revive_tokens = getglobalvar("revive_tokens");

    if (remaining_lives <= 0 && revive_tokens > 0)
    {
        changeplayerproperty(playerindex, "lives", 1);
        setglobalvar("revive_tokens", revive_tokens - 1);
        setglobalvar("revive_token_used", playerindex);
    }
}
</syntaxhighlight>

The numbered script can apply slot-specific life rules first. <code>dieall.c</code> then receives the same event and can reconcile the resulting life count before OpenBOR chooses its next branch.

<syntaxhighlight lang="c" line>
void main()
{
    int remaining_lives = getplayerproperty(playerindex, "lives");

    if (remaining_lives <= 0)
    {
        setglobalvar("player_out_playerindex", playerindex);
        setglobalvar("check_continue_state", 1);
    }
    else
    {
        setglobalvar("prepare_respawn_playerindex", playerindex);
    }
}
</syntaxhighlight>

This timing allows one listener to distinguish a death that will proceed to respawn from a death that exhausts the player's current life supply. Native options that prevent life consumption naturally leave the life count unchanged.

== Combining Numbered and Shared Logic ==

Both layers may participate in the same death event. Their fixed execution order supports a useful division of responsibility:

* Numbered <code>die#.c</code> performs slot-specific defeat handling.
* Shared <code>dieall.c</code> performs project-wide reconciliation after that handling.

For example, numbered scripts might apply different penalties to asymmetric cooperative roles while <code>dieall.c</code> updates a shared defeat counter, checks the remaining-life state, changes encounter intensity, and prepares common audiovisual feedback.

== Die, Death, and Kill Hooks ==

{| class="wikitable"
! Hook
! Scope
! Event represented
! Entity availability
|-
| [[Ondeathscript]]
| Model
| Entity enters native death processing
| <code>self</code> is the dying entity
|-
| Numbered <code>die#.c</code>
| One player slot
| Native player life-loss routine
| Player slot still references the dying entity
|-
| <code>dieall.c</code>
| Every player slot
| Shared native player life-loss listener
| Retrieve the dying entity using <code>playerindex</code>
|-
| [[Onkillscript]]
| Model
| Entity is being removed from play
| <code>self</code> is available immediately before removal
|-
| [[Respawn Scripts]]
| Player
| Replacement player entity has been created after life loss
| Player slot references the new entity
|}

These hooks represent different transitions and may all participate in one defeat sequence. Their separation allows entity-specific death behavior, player-life systems, removal cleanup, and replacement-player setup to remain independent.

== Choosing a Die Script ==

{| class="wikitable"
! Need
! Recommended hook
|-
| Behavior unique to one fixed player slot
| Corresponding <code>die#.c</code>
|-
| The same life-loss behavior for every player
| <code>dieall.c</code>
|-
| Fixed slot handling followed by common party reconciliation
| Numbered <code>die#.c</code> and <code>dieall.c</code> together
|-
| Behavior for any entity entering death processing
| [[Ondeathscript]]
|-
| Cleanup immediately before an entity is removed from play
| [[Onkillscript]]
|-
| Setup for the newly created replacement player
| [[Respawn Scripts]]
|}

== Other Uses ==

Quick applications include:

* '''Life-loss penalties''' - Remove resources, reset streaks, alter score systems, or apply player-specific consequences.
* '''Cooperative defeat handling''' - Update shared lives, revival opportunities, team resources, rescue systems, or remaining-party rules.
* '''Encounter adjustment''' - Reduce or increase pressure, redirect opponents, change hazards, or suspend objectives when a player falls.
* '''Defeat presentation''' - Trigger sounds, screen effects, announcements, portraits, controller feedback, or spectator transitions.
* '''Continue systems''' - Detect exhausted lives, prepare custom continue state, or coordinate project-specific game-over flow.
* '''Statistics and achievements''' - Record defeat counts, remaining lives, player order, survival milestones, or challenge failures.
* '''Role management''' - Release responsibilities, transfer shared ownership, select a new leader, or update cooperative formations.
* '''Development tools''' - Log player-death order, verify remaining-life values, inspect the dying entity, or test corpse and respawn configurations.

== Related Scripts ==

{| class="wikitable"
! Script
! Relationship
|-
| [[Respawn Scripts]]
| Execute after the replacement player entity is created when lives remain. The numbered script runs before <code>respawnall.c</code>.
|-
| [[Join Scripts]]
| Execute when a player completes an in-progress join rather than returning from death.
|-
| [[Ondeathscript]]
| Model-level hook for entity death processing.
|-
| [[Onkillscript]]
| Model-level hook that executes immediately before entity removal.
|-
| [[Onspawnscript]]
| Model-level creation hook that may execute for the replacement player entity before the Respawn series.
|}

== See Also ==

* [[Respawn Scripts]]
* [[Join Scripts]]
* [[Ondeathscript]]
* [[Onkillscript]]
* [[Onspawnscript]]
* [[Player Properties]]
* [[Death]]
* [[Script Overview]]