Game and race states | Split/Second Modding

The term game state describes one of four state machines a script can observe: the game's coarse app state, the race state machine inside a race, the per-car vehicle state and the per-player state. Each has an event that runs on a change and a field that reads the current value, and the names used here are the names the events use.

App states#

The app state is the coarse state of the game as a whole. ss.game.state reads it, and the state event runs with from and to on each change.

Type	Field	Description
string	`boot`	Start-up, before the front end. `main.lua` runs here.
string	`frontend`	The menus.
string	`loading`	A level loading, into or out of a race.
string	`race`	In a race, from the intro scene to the results. The race state machine runs inside this state.

A state handler that sees ev.to == "race" runs at the start of the intro, before the countdown. The cars exist from then on (ss.vehicle is set from the intro and nil before it). Leaving the race state is what raises race_end. This state is useful for setting up a race before it begins and for tearing down afterwards.

Race states#

The race state is the state of the numbered state machine the game runs inside a race. ss.race.state and ss.race.state_id read the current state by name and by number (none and -1 outside a race), and the race_state event runs on each change with id, name, from_id and from.

Type	Field	Description
integer	`1 init`	Provisional: taken from the state functions' return values, not yet seen in a run.
integer	`2 net_sync`	Provisional. Online only.
integer	`3 intro`	Seen. The intro scene; in a dev-boot race it waits for a button.
integer	`4 pre_race`	Provisional.
integer	`5 countdown`	Seen. The grid countdown. `countdown` runs on each whole second.
integer	`6 racing`	Seen. The green light. Entering this state raises `race_start`.
integer	`7 finished`	Seen. The local player's race is over; the others may still be driving. The transition from 6 to 7 raises `race_finish`.
integer	`8 results`	Seen. The results screen. Entering this state raises `race_results`.
integer	`9 reset`	Provisional. A restart.
integer	`10 exit`	Provisional. Leaving the race.

The named events cover the transitions a mod usually wants: race_start is state 6, race_finish is the transition from 6 to 7, race_results is state 8, and race_end is the app state leaving the race, whatever the race state was (a quit from the pause menu, a restart). A dev-boot race shows states 3, 5 and 6 and stays in 6, since nothing ends there; a race from the front end goes on to 7 and 8. The race state is useful for knowing which part of a race a handler runs in.

Vehicle states#

The vehicle state is the state of one car. car.state and player.vehicle_state read it, and the vehicle_state event runs on a change with the name and the id.

Type	Field	Description
integer	`driving`	0. On the road under its own control.
integer	`crashing`	1. The wreck has started.
integer	`wrecked`	2. Out, waiting to be put back. A car the game is only placing back on the track, without a crash, goes straight here from `driving`.
integer	`respawning`	3. The game is placing the car back on the route.
integer	`finished`	4. The race is over for this car.
integer	`idle`	5. Not driving, such as the local car in a dev-boot race before the pad is touched.

wreck runs when a car moves from outside states 1 to 3 into them, the same transition the game's own wreck statistic counts, and respawn runs when it moves back out. car.wrecked is true while the car is in that family. The names are provisional (the game's remote-player code calls them rider states); the ids are the game's. The vehicle state is useful for telling whether a car is drivable at the moment.

Player states#

The player state is the state of a player as distinct from the car: waiting before the green light, racing from it, and finished once one of the mode's end rules has applied to the player and a tick has passed. player.state reads it and player_state reports the change. Countdowns and finishing covers what moves a player to finished, and the player_finished event that runs a tick before it.