Positions and scores

A position is a player's place in the field, 1-based, as player.position reads it. The position event runs when it changes. Where the number comes from depends on the race.

Where position comes from#

The game ranks the players with up to six criteria the mode's params fill in, and keeps the result in a per-player record with a valid flag. With no criteria configured, the game's own rank collapses to the player index with the flag still set, so the flag on its own is not enough. The API uses the game's rank only when the flag is set and a criterion is configured, which player.ranked reports.

Otherwise the position is derived the way the HUD's own fallback sorts the field: players whose state has reached finished come first, in the order they got there (player.finish_order), then the rest by progress, descending. Two cars within a thousandth of a lap of each other keep their previous order, a few metres of hysteresis so that cars that are neck and neck do not swap places every frame.

position events run only from the green light on (race states 6, 7 and 8); while the field forms in the intro the order means nothing. A dev-boot race loads no mode params, so every position there is derived. A race started from the front end carries the mode's own ranking rules. The position is useful for a HUD and for reacting to overtakes.

Scores#

player.score is the game's scoring record, which the scoring component fills in once the mode's params have enabled it. Race mode awards no score, so a plain race reads 0 for everyone. The modes that score (Survival, Air Strike, Air Revenge, Detonator) fill it in, and the score event runs on any change with the new value and the delta.

Progress#

Progress is a car's distance along the AI route, the one value every car has exactly, in every mode. player.lap is the lap counter the HUD shows (-1 before the line is first crossed), player.lap_distance the metres along the route on the current lap, player.lap_length the lap's length, and player.lap_fraction their ratio. player.progress is the lap plus the fraction, a single number that orders the field. It is what the derived position sorts by and what the checkpoints are cut from.

ss.on("position", function(ev)
  if ev.is_local then
    local me = ss.player
    ss.log("P%d (was %d), %s, %.2f laps in", ev.position, ev.from,
      me.ranked and "ranked by the game" or "derived from progress", me.progress)
  end
end)