Reference
ss.vehicles
Vehicles are the cars of a race, one per player, AI cars included. A vehicle is a live object: reading a field reads the physics body at that moment, and assigning a field writes it back to the game. Vehicles only exist within a race. If you're looking for the player driving a vehicle (position in the field, lap, score), check out the player class instead.
Constants#
The vehicle class defines global constants for quick access to certain features.
| Constant | Type | Value |
|---|---|---|
ss.vehicle |
vehicle | The local player's car. Outside a race, this constant is nil. |
Static members#
These elements are static to the class itself and can be accessed like so:
local cars = ss.vehicles.all()Static functions#
| Function | Return Values | Description |
|---|---|---|
ss.vehicles[integer index] |
vehicle vehicle | Returns the car of 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.vehicles.count |
integer count | The number of cars in the race. 0 outside a race. |
ss.vehicles.all() |
table of vehicle vehicles | Returns a table of references to all cars currently in the race. |
ss.vehicles.each() |
function iterator | Returns an iterator over all cars currently in the race, for use in a for loop. |
Instance members#
Instance members must be accessed through a reference to a specific vehicle object.
local car = ss.vehicle
car.position.y = car.position.y + 3
car:impulse(car.up * car.mass * 5)
Assigning a field writes it to the game. A vector field can be assigned one component at a time
(car.position.y = 5) or as a whole, with anything vector-like
(car.position = { x = 10, y = 0.5, z = -40 }). Assigning a read-only field, or any field of a
vehicle that is no longer valid, results in an error.
Instance Methods#
| Function | Return Values | Description |
|---|---|---|
impulse(vec3 impulse) |
nil | Applies an impulse, in newton-seconds, at the car's centre of mass. The velocity changes by impulse / mass. |
impulse(
vec3 impulse,
vec3 point
) |
nil | Applies an impulse, in newton-seconds, at a point in world coordinates. The offset from the centre of mass crossed with the impulse also spins the car. |
angular_impulse(vec3 impulse) |
nil | Applies an angular impulse, in newton-metre-seconds, to the car's spin alone. |
wreck() |
boolean wrecked | Wrecks the car. It crashes on its next physics step and the game takes over from there: the tumble, the wreck camera for the local player, then the respawn back on the track. Returns false if the car is already crashing. See Wrecking a car. |
wreck(vec3 point) |
boolean wrecked | Wrecks the car as if it had been hit from a point in world coordinates. Where the point lies around the car decides how it tumbles. |
respot() |
nil | Puts the car back on the track, facing the right way, without a crash. This is the game's own manual respot, the same as car.input:press("respot"). |
mem(
integer offset,
string type
) |
any value | Returns a value of the car's physics struct 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 car's physics struct at a specific memory address-offset. |
memdump(
integer lowerBound,
integer upperBound
) |
nil | Logs the current state of the car's memory addresses in the given range, one dword per line with its float reading, for debugging. |
Instance Fields#
| Type | Field | Read-only? | Description |
|---|---|---|---|
| boolean | valid |
Yes | Validates that the vehicle object exists. A vehicle kept across the end of a race becomes invalid: its fields read nil and assigning them results in an error. |
| integer | player |
Yes | The index of the player driving the car, 0-based. |
| boolean | is_local |
Yes | Whether the car is the local player's. |
| vector | position |
No | The car's position in metres (the origin of its physics body). Setting this field moves the car through the game's own respawn; see Moving a car. |
| vector | rotation |
No | The car's rotation in degrees, as pitch, yaw and roll (x, y and z name the same components). See Coordinates and angles. |
| vector | velocity |
No | The physics body's linear velocity in metres per second, on the world axes. Setting this field, or one component of it, goes through the game's own setter and the car drives on from the new velocity. |
| vector | angular_velocity |
No | The physics body's angular velocity in degrees per second about the world axes, following the right-hand rule. y = 90 is a quarter turn per second to the left, seen from above. |
| number | mass |
Yes | The physics body's mass in kilograms. |
| vector | forward |
Yes | The car's forward axis in the world, as a unit vector. |
| vector | up |
Yes | The car's up axis in the world, as a unit vector. |
| vector | right |
Yes | The car's right axis in the world, as a unit vector. |
| number | speed |
Yes | The length of the car's velocity, in metres per second. |
| number | speed_kmh |
Yes | The length of the car's velocity, in kilometres per hour. |
| string | name |
Yes | The name of the car's model as the game's files know it, such as Truck_01 or Supercar_05. |
| boolean | airborne |
Yes | Whether none of the car's wheels touch the ground. |
| integer | wheels_on_ground |
Yes | The number of wheels touching the ground, 0 to 4. |
| string | state |
Yes | The car's vehicle state: driving, crashing, wrecked, respawning, finished or idle. |
| boolean | wrecked |
Yes | Whether the car's state is crashing, wrecked or respawning. |
| player | race |
Yes | The player driving the car: position in the field, lap, progress, lap time and the rest. player.vehicle is the way back. |
| controls | input |
No | The driver's controls as the physics receives them, and the rest of the input record. See vehicle.input. |
| integer | address |
Yes | The address of the car's physics struct, for ss.mem. |
Instance Memory Offsets#
These offsets can be manipulated by the instance's mem method. They are relative to address, the car's VehiclePhysics struct.
| Field | Fieldtype | Description |
|---|---|---|
0x584 |
pointer |
The Havok rigid body. The body's motion is at +0xd0 from there, with the mass inverse at +0xcc, the linear velocity at +0xd0 and the angular velocity at +0xe0 of the motion. |
0x67c |
integer |
The state of the crash in progress. 29 while the car is not crashing. |
0x175c |
3 × float |
Position. Use field position |
0x177c |
3 × float |
The rotation's right axis. Use field right |
0x178c |
3 × float |
The rotation's up axis. Use field up |
0x179c |
3 × float |
The rotation's forward axis. Use field forward |
0x17bc |
3 × float |
Velocity, as cached after the last physics step. Use field velocity |
0x17cc |
3 × float |
Angular velocity, as last set. |
0x17fc |
float |
The length of the cached velocity. Use field speed |
0x1758 |
byte |
A pool flag set at spawn. |
0x1759 |
byte |
A pool flag set at spawn. |
0x1869 |
byte |
A pool flag set at spawn. |
0x1865 |
byte |
A wreck has been asked for. Cleared when the car is respawned. Use method wreck |
0x187c |
3 × float |
The point a requested wreck comes from. |
0x18a6 |
4 × byte |
One byte per wheel, 1 while the wheel touches the ground. Use field wheels_on_ground |
Moving a car#
Setting position or rotation moves the car through the game's own respawn, so that
the physics state stays consistent: the wheels, contacts and impulses are reset, the body is placed at the new
transform, and the car is given its current speed along its new forward axis with no spin. A moving car keeps
moving and a stationary car stays put. A read immediately after the write returns the new value.
Unlike the game's respawn, the car is placed exactly where asked: it is not dropped onto the ground or tilted to the surface. The position should therefore be on, or just above, the road. Lap progress follows the move on its own for moves of up to three quarters of a lap along the route; a larger jump counts as a line crossing. Coordinates and angles describes this in detail.
wrecked is being respawned by the game at the same time. Wait for the respawn event, or for the state to read driving, before moving it.Wrecking a car#
wreck() is the wreck the game itself gives a car: the one an eliminated player gets. The car
crashes on its next physics step, tumbles for two to three seconds, and is then respawned on the track like
after any other wreck. Its state goes driving, crashing, wrecked,
respawning and back to driving, and the wreck
and respawn events run. The local player gets the wreck camera. AI
cars can be wrecked as well.
wreck(point) does the same with a hit that comes from a point in the world, such as
car.position - car.forward * 3 for a hit from behind.
respot() puts a car back on the track without a crash. The game treats it the way it treats a car
going the wrong way: the state passes through wrecked for half a second, the
wreck event runs with crashed set to false, and the car is placed back on the route
facing the right way.
-- Wrecks whoever is leading, ten seconds into the race.
ss.on("race_start", function()
ss.after(10, function()
for car in ss.vehicles.each() do
if car.race.position == 1 then car:wreck() end
end
end)
end)Example#
-- Moves the local car to 30 m behind the leader, on the leader's line, at the leader's speed.
ss.on("race_start", function()
ss.after(20, function()
local me, leader = ss.vehicle, nil
for car in ss.vehicles.each() do
if not car.is_local and (not leader or car.race.position < leader.race.position) then leader = car end
end
if not (me and leader) then return end
me.rotation = leader.rotation
me.position = leader.position - leader.forward * 30
me.velocity = leader.velocity
end)
end)