Coordinates and angles

The term coordinate space describes the frame in which the game's positions, rotations and velocities are expressed. The world is right-handed: X increases to the right, Y increases upwards and Z increases forwards, and all distances are in metres. Everything the API measures uses this frame unless a field says otherwise.

The world and the car#

A car's own frame is built the same way, as the game's respawn builds it, and a car exposes its three axes as unit vectors in world coordinates: car.forward, car.up and car.right. Props and Nemesis actors have the same three. car.position is the origin of the car's physics body. These axes are useful for placing things relative to a car.

local car = ss.vehicle
local ahead = car.position + car.forward * 40       -- a point 40 m ahead of the nose
local lifted = car.position + ss.vec3(0, 3, 0)      -- 3 m up on the world's axis
local side = car.right:dot(other.position - car.position)   -- how far to the right the other car is

Angles#

A rotation reads and writes as three angles in degrees: pitch, yaw and roll (x, y and z are the same fields, in that order).

The angles are applied yaw first, then pitch, then roll. At a pitch of ±90 the heading is ambiguous, and the yaw and roll that read back are one of the equivalent pairs, so a rotation written near the vertical does not necessarily read back as the same numbers.

Angular velocity is expressed in degrees per second about the world axes, following the right-hand rule: car.angular_velocity.y = 90 is a quarter turn per second to the left seen from above, and 180 a half turn. The physics works in radians underneath; the API converts in both directions.

Velocity and impulses#

velocity is the physics body's linear velocity in metres per second on the world axes. speed is its length, and speed_kmh is the same in kilometres per hour. Writing velocity goes through the game's own setter and the car drives on from the new value.

An impulse is an action, so it is a method. obj:impulse(vec) applies vec in newton-seconds at the centre of mass, changing the velocity by vec / obj.mass, so car:impulse(car.up * car.mass * 5) is a 5 m/s kick upwards whatever the car weighs. obj:impulse(vec, point) applies the impulse at a world point, which also spins the body by (point - centre) × vec. obj:angular_impulse(vec) (in newton-metre-seconds) spins the body alone. Cars and props have all three.

Moving a car#

Writing position or rotation on a car does not write numbers into the physics directly. It goes through the game's own respawn: the physics state is reset (wheels, contacts, impulses, timers), the body is placed at the new transform, and the car is given the speed it had along its new forward axis with no spin. A moving car keeps moving, an idle car stays put, and a read straight after the write returns the new values.

Two things the game's respawn does are left out on purpose. The game drops the car onto the ground and tilts it to the surface; the API places the car exactly where asked. A car placed in the air therefore falls, and it's recommended to give a point on or just above the road. Lap progress follows on its own: the route tracker looks for the route link near the car's last one and searches the whole route if it must, and a jump of more than three quarters of a lap along the route counts as a line crossing (forward reads one lap less, backward one lap more), so moves within that range read as driving.