Reference
ss.players
Players are the entries of a race, human and AI alike. A player is a live
object whose fields read the game's own records for that entry at the moment they are read. Nothing on a
player is writable: the car a player drives is the writable half, reached through the vehicle
field. Players only exist within a race. If you're looking for the car itself (position, velocity, controls),
check out the vehicle class instead.
Constants#
The player class defines global constants for quick access to certain features.
| Constant | Type | Value |
|---|---|---|
ss.player |
player | The local player. Outside a race, this constant is nil. |
Static members#
These elements are static to the class itself and can be accessed like so:
local players = ss.players.all()Static functions#
| Function | Return Values | Description |
|---|---|---|
ss.players[integer index] |
player player | Returns the player at the given index. Player indices are 0-based and are the indices the race events carry. Returns nil if there is no such player. |
ss.players.count |
integer count | The number of players in the race. 0 outside a race. |
ss.players.all() |
table of player players | Returns a table of references to all players currently in the race. |
ss.players.each() |
function iterator | Returns an iterator over all players currently in the race, for use in a for loop. |
Instance members#
Instance members must be accessed through a reference to a specific player object.
local me = ss.player
ss.log(me.position, me.lap, me.progress)WARNING: Attempting to call instance members statically will result in an error!
Most of a player's values are component outputs the API polls once a frame, exposed as read-only fields.
power is the exception: it can be set.
Instance Methods#
| Function | Return Values | Description |
|---|---|---|
mem(
integer offset,
string type
) |
any value | Returns a value of the player's game logic object at a specific memory address-offset. See ss.mem for the types. |
mem(
integer offset,
string type,
any value
) |
nil | Sets a value of the player's game logic object at a specific memory address-offset. |
memdump(
integer lowerBound,
integer upperBound
) |
nil | Logs the current state of the object's memory addresses in the given range, for debugging. |
Instance Fields#
| Type | Field | Read-only? | Description |
|---|---|---|---|
| boolean | valid |
Yes | Validates that the player object exists. A player kept across the end of a race becomes invalid and reads nil for every other field. |
| integer | index |
Yes | The player's index, 0-based. |
| boolean | is_local |
Yes | Whether the player is the local one. |
| string | name |
Yes | The driver's name as the game shows it, such as TAYLOR. The local player of a single-player race reads PLAYER. |
| string | vehicle_name |
Yes | The name of the player's car model, the same as vehicle.name. |
| boolean | is_ai |
Yes | Whether an AI driver drives the car. |
| integer | grid |
Yes | The player's place on the starting grid, 1 at the front. |
| integer | position |
Yes | The player's place in the field, 1-based. The game's own rank when the mode ranks the field (see ranked), otherwise derived the way the HUD's fallback sorts the field. See Positions and scores. |
| boolean | ranked |
Yes | Whether position is the game's own rank rather than the derived order. |
| integer | finish_order |
Yes | The order in which the player's state reached finished. 0 while the player is racing. |
| integer | score |
Yes | The player's score. Race mode awards none, so a plain race reads 0 for every player. |
| number | power |
No | The player's power bar as a percentage, 0 to 100. The three segments of the bar fill at the mode's own thresholds. Setting this field fills or drains the bar; the value is kept within the range. |
| string | state |
Yes | The player's state: waiting, racing or finished. See Player states. |
| integer | lap |
Yes | The lap counter the HUD shows. -1 until the line is first crossed. |
| integer | laps |
Yes | The number of laps in the race. |
| number | progress |
Yes | The lap plus the fraction of the current one. 1.5 is halfway round the second lap. |
| number | lap_fraction |
Yes | The fraction of the current lap completed, 0 to 1. |
| metres | lap_distance |
Yes | The distance along the route on the current lap. |
| metres | lap_length |
Yes | The length of a lap along the route. |
| boolean | ended |
Yes | Whether the race has ended for the player, through one of the mode's end rules. |
| string | vehicle_state |
Yes | The state of the player's car: driving, crashing, wrecked, respawning, finished or idle. |
| boolean | wrecked |
Yes | Whether the car's state is crashing, wrecked or respawning. |
| integer | checkpoint |
Yes | The last split reached on the current lap. 0 until the first. See Checkpoints and lap times. |
| seconds | lap_time |
Yes | The running lap time. Resets on the line. |
| seconds | race_time |
Yes | The race clock for the player, as the HUD timer shows it. |
| seconds | last_lap |
Yes | The time of the last completed lap. |
| seconds | best_lap |
Yes | The time of the best lap. |
| seconds | countdown |
Yes | The seconds left on the mode timer, Survival's clock. nil unless the mode runs it. |
| seconds | elimination_in |
Yes | The seconds to the next elimination. nil unless the mode runs eliminations. |
| boolean | elimination_marked |
Yes | Whether the player is marked for the next elimination. nil unless the mode runs eliminations. |
| integer | lives |
Yes | The lives left. nil unless the mode counts them. |
| boolean | eliminated |
Yes | Whether the player has been eliminated. nil unless the mode eliminates. |
| seconds | event_end_in |
Yes | The seconds left on the event-end countdown. nil unless the mode runs it. |
| seconds | race_end_in |
Yes | The seconds left on the online race-end countdown, once the first car has finished. nil otherwise. |
| vehicle | vehicle |
Yes | The car the player drives, ss.vehicles[index]. vehicle.race is the way back. |
| table | snapshot |
Yes | A plain table of all the fields above, taken with one call. |
| integer | address |
Yes | The address of the player's game logic object, for ss.mem. |
| integer | setup_address |
Yes | The address of the player's entry in the race setup, which holds the names and the grid place. |
The timer fields exist only while the mode runs that timer and read nil otherwise. A plain race, and any dev-boot race, reads nil for all of them. Countdowns and finishing describes which mode runs which.
name, vehicle_name, is_ai, grid and power are
read from the game at the moment of the read and are not part of snapshot.
TIP: Every field read is one call into the hook.
snapshot returns all of the fields above as a plain table from a single call, which is the cheaper way to read many fields of many players every frame.
The player groups are emptied before the race_end event fires, so a handler of that event already
sees no players. Players should be fetched from ss.players at the start of each race rather than
kept from the previous one.
Example#
ss.every(1, function()
if ss.race.state ~= "racing" then return end
for p in ss.players.each() do
local s = p.snapshot -- one call, every field
ss.log("P%d player %d: lap %d/%d, %.0f m, %s%s", s.position, s.index, s.lap, s.laps,
s.lap_distance, s.vehicle_state, s.is_local and " (you)" or "")
end
end)
ss.on("lap_time", function(ev)
local p = ss.players[ev.player]
if p and p.is_local then
ss.log("lap %d in %.3f s, best %.3f s", ev.lap, ev.time, p.best_lap)
end
end)