Countdowns and finishing | Split/Second Modding

A countdown is one of the timers a race runs: the one on the grid before the green light and, depending on the mode, several more the HUD shows while the race runs. A player's race ends by one of the mode's rules. Three events cover these: countdown, timer and player_finished.

The grid countdown#

The grid countdown is the 3-2-1 before the start, race state 5. The countdown event runs on each whole second with count and the exact seconds left. A race's own figure can be longer than three (a dev-boot race counts 5, 4, 3, 2, 1). The green light is not a count of 0 but race_start, the transition to race state 6. This countdown is useful for a custom start display.

Mode timers#

The mode timers are the countdowns that belong to the mode. They are carried per car, and the HUD reads the local player's. The timer event reports the local player's copy of each when its whole second changes, starts or stops, with kind, the whole seconds counting down, the exact figure and running.

Type	Field	Description
string	`countdown`	The mode timer: an initial countdown that victims and wrecks add to, the Survival-style clock. `player.countdown` is its seconds left.
string	`elimination`	The seconds to the next elimination, with the car marked for it: `player.elimination_in`, `player.elimination_marked`, `player.eliminated`.
string	`event_end`	The event-end countdown of the modes with lives: `player.lives`, `player.event_end_in`.
string	`race_end`	Online only: the race-end countdown once the first car has finished, `player.race_end_in`.

The matching player fields exist only while the mode runs that timer and read nil otherwise. None of the mode timers run in a dev-boot race, as its mode params are not loaded, so a mod that uses them needs a race started from the front end (see How to: Testing a mod).

Finishing#

Each frame the game applies the mode's end rules to every car: laps complete, mode countdown done, eliminated, marked for elimination, a timer, a finish quota, a victim count, rank first or last. The first rule that holds ends that player's race, and the player_finished event runs on that frame with the position at that moment, race_time, lap and laps, score, best_lap and a reason derived from the records the rules look at.

Type	Field	Description
string	`laps`	The lap counter reached the race's number of laps.
string	`race_over`	The car did nothing itself and the race ended for everyone: a quit, or, for an AI, the local player's own end on this frame or earlier. An Elimination's finish-quota rule ends every AI the moment the human is out and leaves their eliminated flags set as well, so this reason is decided by the local player's own end rather than by the AI's flags.
string	`eliminated`	The Lives or Elimination record marks the player eliminated.
string	`countdown`	The mode timer ran out.
string	`ended`	None of the above: another rule, a timer or a quota.

A tick later the player's state moves to finished and player_state reports it. race_finish is a different thing: the local player's own race state machine moving from racing to finished, which happens once per race and says nothing about the AIs. A dev-boot race has every end rule off, so nobody finishes there and the event never runs.

The race_time, lap_time and best_lap figures come from the Laps records the mode's params define. In a Race and in Detonator those are the race clock and the laps; the other modes set the component up differently and their figures have not been mapped (?), so they should be read as Race and Detonator figures until they are.

ss.on("player_finished", function(ev)
  ss.log("player %d finished P%d after %.2f s: %s", ev.player, ev.position, ev.race_time, ev.reason)
end)