Score Scripts

Score scripts are automatic event hooks that execute whenever OpenBOR processes a score adjustment through its native score routine. Two forms are available: numbered scripts for individual player slots and scoreall.c for shared project-wide handling.

Numbered scripts correspond to individual players:

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

The shared script receives adjustments for every player:

• data/scripts/scoreall.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 score-script files in data/scripts. OpenBOR loads them 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	Scope	Player identification
data/scripts/score1.c	Player 1	Filename - index 0
data/scripts/score2.c	Player 2	Filename - index 1
data/scripts/score3.c	Player 3	Filename - index 2
data/scripts/score4.c	Player 4	Filename - index 3
data/scripts/scoreall.c	Every player	Local variable player

Numbered Score Scripts

The numbered scripts receive the score adjustment. Their filename identifies the player slot.

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

    // React to the score adjustment here.
}

OpenBOR does not supply player or self automatically to a numbered score script.

Scoreall

data/scripts/scoreall.c is a shared listener for every player slot. It receives the zero-based player index in addition to the score adjustment.

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

    // React to any player's score adjustment here.
}

scoreall.c allows common project-wide behavior can be written once instead of duplicated across four files.

No self variable is supplied because the event belongs to a player slot rather than an entity.

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, when present.
7. scoreall.c executes with local variables player and score, when present.

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

The numbered script always executes before scoreall.c. Changes made by the numbered script are therefore visible to the shared script later in the same event sequence. scoreall.c does not depend on the numbered file being present and still executes when no corresponding score#.c exists.

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	Available in	Description
score	Signed 64-bit integer (VT_INTEGER64)	Numbered scripts and scoreall.c	Adjustment submitted to the native score routine. Positive values add points, and negative values deduct points.
player	Integer (VT_INTEGER)	scoreall.c only	Zero-based index of the player receiving the score adjustment.

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-script 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 when present, followed by scoreall.c when present. 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 numbered score scripts or scoreall.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

scoreall.c is especially useful for common systems. This compact example applies every player'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()
{
    int player = getlocalvar("player");
    long adjustment = getlocalvar("score");
    long team_score = getglobalvar("team_score");

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

The shared handler creates a cooperative tally without replacing any 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.
• Common handling - Use scoreall.c for project-wide scoring logic without maintaining four copies of the same script.
• 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 filename identifies the player for score#.c, while local variable player identifies the player for scoreall.c. Local variable score provides the signed adjustment, but neither form supplies a 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
• Key scripts
• Script Overview