Score Scripts

Score scripts are automatic player-slot event hooks that execute whenever OpenBOR processes a score adjustment through its native score routine. Four optional files are available, one for each player slot:

• data/scripts/score1.c
• data/scripts/score2.c
• data/scripts/score3.c
• data/scripts/score4.c

Each script receives the signed 64-bit adjustment submitted to the score routine. Positive values add points, while negative values deduct them. This makes score scripts useful for custom feedback, milestones, achievements, penalties, secondary reward systems, cooperative scoring, statistics, and any other mechanic that should react immediately to native score changes.

OpenBOR's accumulated player score supports values from 0 through 18446744073709551615. This provides enough range for extreme scoring systems, large multipliers, dense projectile bonuses, and other designs without requiring creators to split a score into manually carried pieces.

Score scripts are adjustment events rather than general observers of the score property. Writing a player's score directly through script does not execute them.

Usage

Create the desired numbered script in data/scripts. OpenBOR loads it automatically, so no model, level, or project command is required.

score#.c is documentation shorthand in which # represents the player number. The literal filenames use 1 through 4.

File	Player	Player index
data/scripts/score1.c	Player 1	0
data/scripts/score2.c	Player 2	1
data/scripts/score3.c	Player 3	2
data/scripts/score4.c	Player 4	3

The basic structure is:

void main()
{
    long score = getlocalvar("score");

    // React to the score adjustment here.
}

The filename identifies the player slot. OpenBOR does not supply player or self automatically.

Execution

The immediate score-adjustment sequence is:

1. OpenBOR receives a player slot and a signed amount to apply.
2. OpenBOR calculates applicable extra-life thresholds.
3. Positive amounts add to the player's score and saturate at 18446744073709551615. Negative amounts deduct from the score and saturate at 0.
4. Applicable extra lives are awarded.
5. OpenBOR stores the updated score total.
6. The corresponding numbered score script executes with local variable score.

The player's updated score and any extra lives from the adjustment are already available when the script executes. Native processing for that individual score adjustment is otherwise complete. Negative adjustments do not remove lives that were already awarded.

Score scripts execute once for each call to the native score routine, not once per update and not once for an accumulated group of adjustments. Stage-completion counting may therefore produce a sequence of small events as bonuses are transferred into the player's total.

OpenBOR may also submit an amount of zero to the score routine. Scripts can test whether score is positive, negative, or zero before producing the applicable response.

Event Data

Variable	Type	Description
score	Signed 64-bit integer (VT_INTEGER64)	Adjustment submitted to the native score routine for the player slot associated with the script file. Positive values add points, and negative values deduct points.

score is the requested adjustment, not the player's new total. It is also not necessarily the actual change in the stored total. An addition that reaches the unsigned maximum or a deduction that reaches zero still supplies its original signed amount to the event.

Changing the local score variable does not alter the adjustment or the stored player score because the event executes after native score processing. The event supplies the adjustment rather than the running total. Systems may accumulate the signed 64-bit changes in a global variable to build an independent tally, as shown below.

Score Range

OpenBOR separates the signed values used to adjust score from the unsigned value used to store the player's total.

Value	Type	Minimum	Maximum
Player score total	Unsigned 64-bit integer	0	18446744073709551615
Model and level score value	Signed 64-bit integer	-9223372036854775808	9223372036854775807
score#.c event value	Signed 64-bit integer (VT_INTEGER64)	-9223372036854775808	9223372036854775807

The player's maximum total is also known as UINT64_MAX, or 2⁶⁴ - 1. Score adjustment uses saturation at both ends. Positive adjustments that would exceed the maximum store UINT64_MAX, while negative adjustments that would pass below zero store 0.

Player totals, saved scores, and high-score entries preserve the unsigned 64-bit range. Model and level score commands accept signed 64-bit values, allowing creators to assign either rewards or penalties without replacing the native score system.

The scoreformat setting continues to pad short values to nine digits. Nine digits are a minimum display width rather than a limit, so larger totals remain visible in full.

What Triggers the Event

Native score adjustments include values generated by normal engine systems such as:

• Damage and hit scoring.
• Defeating entities with a configured score value.
• Collecting items with a configured score value.
• Damaging obstacles.
• Reaching an end-level entity with a score value.
• Clear, life, and rush bonuses awarded during stage completion.

The precise adjustment depends on the applicable model, attack, level, and project configuration. Each native adjustment runs the numbered script for the affected player. Negative model or level score values can turn applicable defeats, pickups, obstacles, or exits into score penalties.

Several operations can change a player's stored total without representing a new score adjustment. Direct score-property writes, loading saved data, and internal score resets do not pass through the native score routine and therefore do not execute score#.c. This separation prevents initialization, restoration, or scripted replacement of a total from being mistaken for gameplay scoring.

Example: Reward and Penalty Feedback

The following data/scripts/score1.c records Player 1's latest adjustment and selects separate feedback for rewards and penalties. An update, draw, or HUD script can consume the stored values and provide the desired presentation.

void main()
{
    long adjustment = getlocalvar("score");

    if (adjustment != 0)
    {
        setglobalvar("p1_last_score_adjustment", adjustment);

        if (adjustment >= 1000)
        {
            setglobalvar("p1_score_flash", 2);
        }
        else if (adjustment > 0)
        {
            setglobalvar("p1_score_flash", 1);
        }
        else
        {
            setglobalvar("p1_score_flash", -1);
        }
    }
}

The same pattern can be used in the other numbered files. The filename supplies the player identity. Keeping visual or timed behavior in an update or draw script allows the score event to remain focused on recording the adjustment and starting the response.

Example: Shared Team Score

Individual score scripts may contribute to a common system. This compact score2.c example applies Player 2's rewards and penalties to a shared team tally. It assumes team_score was initialized to 0 by a level-start or other setup script.

void main()
{
    long adjustment = getlocalvar("score");
    long team_score = getglobalvar("team_score");

    if (adjustment != 0)
    {
        setglobalvar("team_score", team_score + adjustment);
    }
}

Equivalent handlers in score1.c, score3.c, and score4.c create a cooperative total without replacing each player's native score. The same arrangement can power team milestones, shared resources, competitive comparisons, or multiplayer challenge rules.

Other Uses

Quick applications include:

• Presentation - Select sounds, flashes, text, particles, or camera effects according to the adjustment's sign and size.
• Milestones - Detect score thresholds and trigger ranks, unlocks, achievements, or rewards.
• Penalties - React to point loss from dangerous items, protected targets, mistakes, or other negative-score interactions.
• Secondary resources - Convert native score changes into meter, currency, experience, continues, or another custom value.
• Cooperative systems - Combine adjustments from several player slots into a shared objective or team score.
• Competitive systems - Track momentum, compare recent gains, or announce changes in player standing.
• Challenge logic - Count qualifying changes, enforce score goals, or record progress for bonus conditions.
• Statistics - Record adjustment frequency, largest gains or losses, stage totals, or player-specific performance data.

The numbered file identifies the player, and score provides the signed adjustment, but the event supplies no dedicated source identifier. Systems that need to distinguish hits, defeats, pickups, bonuses, or penalties can combine the event with state recorded by the relevant attack, model, item, spawn, or level scripts.

See Also

• Score
• Player
• Model score
• Level score
• Script Overview