Types

The reference tables name a type for every field, parameter and return value. The Lua types are the language's own; the remaining types belong to the API and are defined here, each with a link to the page that documents it in detail.

Lua values#

number#

A number is a double-precision floating point value, the only numeric type Lua has. Where a unit applies, the tables name it instead: seconds, metres or degrees.

integer#

An integer is a number that is always whole: a count, an index, a frame number or a memory value. Lua has no separate integer type, so raw[k] and the integer types of ss.mem still return plain numbers.

string#

A string is a Lua string. The names the API returns (a state, a mode, a kind, a prop's name) are lower-case identifiers unless a table says otherwise. The names the API takes (an event, a signal, an input control) are compared exactly.

boolean#

A boolean is true or false. A flag field reads as a boolean and a write to one takes a boolean; the bool type of ss.mem and the raw input slots also accept a number.

table#

A table is a plain Lua table. A list, such as the result of ss.vehicles.all() or ss.props.near(), is 1-based and intended for ipairs; a record, such as ss.race.track, a player's snapshot or an opts table, is keyed by name. The tables the API returns are copies: changing one changes nothing in the game.

function#

A function is a Lua function: a handler, a timer callback, the body of a routine or an iterator returned by each().

Methods#

A method is a function called on an object with a colon, which passes the object as the first argument: car:impulse(v) is car.impulse(car, v). The instance methods of the vehicle, player, prop and actor classes are called this way. Attempting to call a method statically, without an object, results in an error.

nil#

nil is the absence of a value. The API returns nil for an object that does not exist (ss.vehicle outside a race, ss.props[9999]), for a missing params name and for an unmapped memory read. Assigning nil to a held input control releases it.

any#

any stands for a value of whatever type is found at the given address or path. It is what ss.mem and ss.params.get return.

Vectors#

vec3#

A vec3 is a plain vector of three components, x, y and z, created by ss.vec3(x, y, z) or returned by an operator or by :copy(). It has the methods and operators listed under ss.vec3 and no connection to the game.

vector#

A vector is a live vector returned by an object's field, such as car.position, prop.velocity or car.rotation. It reads the game on every access and writes through on assignment, either one component at a time (car.position.y = 5) or as a whole (car.position = other.position). It has the same methods and operators as a vec3; the operators return plain copies, and :copy() returns a vec3 that no longer writes through. A rotation vector names its components pitch, yaw and roll as well as x, y and z.

vector-like#

A vector-like value is anything accepted where a vector is expected, in an assignment or as a parameter: three numbers, a vec3 or a live vector, a table { x =, y =, z = }, a table { pitch =, yaw =, roll = } or a table { 1, 2, 3 }.

Colours#

color#

A color is a table { r, g, b[, a] } with each component in the range 0 to 255, or a number of the form 0xRRGGBB. A colour left out is white and an alpha left out is fully opaque. Colours are used by ss.draw, where the alpha of an image's tint is the image's opacity. ss.ui.text_colored is the exception: it takes four components in the range 0 to 1, as ImGui does.

Handles#

handler#

A handler is the id returned by ss.on, ss.every and ss.after, for passing to ss.off. It is opaque and should be kept in a local.

routine#

A routine is the object returned by ss.routine, with the fields running, done, error, waiting and name and the method :stop(). See Routines.

event#

An event is the table a handler receives, ev, carrying the fields of that event. The Events page lists the fields of each event; ss.wait_event resumes a routine with the same table.

Objects#

Each of the following is a live object: a proxy whose reads go to the game and whose writes go back to it, with a valid field that becomes false once the race that held the object has ended.

player#

A player is one of the race's entries, human or AI: position in the field, lap, progress, score, timers and the finish. Players are read-only. See ss.players.

vehicle#

A vehicle is a car of the race: transform, velocity, impulses and its input. See ss.vehicles.

prop#

A prop is a movable object of the level, such as a bollard, a barrel or a multi-part breakable. See ss.props.

powerplay#

A powerplay is one of the level's Power Plays, such as a fuel truck or a route change. See ss.powerplays.

actor#

An actor is a Nemesis actor: a truck, a car or a helicopter built by the game at race start. See ss.nemesis.

input#

An input is a car's controls object, car.input: the four physics controls, the buttons and the raw input record, with the methods :press and :clear. See vehicle.input.

controls#

controls is another name for the input object; some tables use one name and some the other.

Units#

seconds#

seconds is a number of seconds: timers, waits, race and lap times, and ev.dt. Timers and waits count the frame tick's real elapsed time in every app state; race and lap times are read from the game's own race clock.

metres#

metres is a number of metres on the world axes. Every position and distance is in metres, velocities are in metres per second, and a lap's lap_distance and lap_length are metres along the route.

degrees#

degrees is a number of degrees. Every angle is in degrees: a rotation's pitch, yaw and roll, and the components of an angular velocity, which are degrees per second about the world axes. How they are applied is described under Coordinates and angles.

mass and impulse#

A body's mass is in kilograms. An impulse passed to :impulse(vec) is in newton-seconds, so the velocity changes by vec / mass; an angular impulse passed to :angular_impulse(vec) is in newton-metre-seconds.