ss.race | Split/Second Modding

The race class represents the running race: its mode, its track, its state machine, its clock and its players. It is a single live object, ss.race, which exists at all times: reading a field reads the game at that moment. Outside a race its fields read their "none" values rather than nil, except where the table says otherwise.

Fields#

Type	Field	Read-only?	Description
string	`mode`	Yes	The mode's name: `Race`, `Elimination`, `Detonator`, `Survival`, `Air Strike` or `Air Revenge`. nil in the front end, and nil in a dev-boot race, which never sets it.
integer	`mode_index`	Yes	The mode's index, 0 to 5 in the order above. 6 in the front end and in a dev-boot race. See Modes.
table	`track`	Yes	The level container that is open and the subtrack within it, as `{ level =, subtrack = }`, read off the asset paths. nil before the first race of the session.
string	`state`	Yes	The current state of the race state machine, by name. `none` outside a race. The states are listed under Race states.
integer	`state_id`	Yes	The id of the current race state, 1 to 10. -1 outside a race.
seconds	`time`	Yes	The race clock. 0 outside a race.
integer	`local_player`	Yes	The index of the local player, the one `ss.player` and `ss.vehicle` stand for.
table of player	`players`	Yes	The player class, `ss.players`.
integer	`splits`	No	The number of checkpoints per lap, 4 by default. Accepts 1 to 64. The setting is shared by every mod, so a mod that changes it should read the `splits` field of the `checkpoint` event rather than assume its own number. See Checkpoints and lap times.
table	`nemesis_slots`	No	The Nemesis template files the next race builds its actors from, or nil for whatever the mode file says. See ss.nemesis.

Modes#

The mode index comes from the race setup the front end fills in when a mode is chosen. A dev-boot race skips that setup, so there mode is nil and mode_index reads 6 even though a mode file is loaded. The race_start event carries the same two values.

Type	Field	Description
integer	`0`	`Race`
integer	`1`	`Elimination`
integer	`2`	`Detonator`
integer	`3`	`Survival`
integer	`4`	`Air Strike`
integer	`5`	`Air Revenge`
integer	`6`	No mode: the front end, or a dev-boot race.

Example#

ss.race.splits = 8                            -- eight splits a lap for every mod's checkpoint events

ss.on("race_start", function()
	local t = ss.race.track
	ss.log("%s on %s/%s, state %s (%d)", tostring(ss.race.mode),
		t and t.level or "?", t and t.subtrack or "?", ss.race.state, ss.race.state_id)
end)

ss.every(10, function()
	if ss.race.state == "racing" then
		ss.log("%.1f s in, local player is P%d", ss.race.time, ss.player.position)
	end
end)