getCar

Returns a reference to a car’s state structure. This is the starting point for almost any script interacting with vehicles.

Signature

ac.getCar(index)

Description

This function provides access to the ac.StateCar object for a specific vehicle in the session. Vehicle indices are 0-based.

Indexing

The player’s car is always at index 0. In multiplayer or races with AI, other cars will occupy indices 1 through N.

Parameters

Parameter	Type	Required	Default	Description
index	integer	Yes	-	The 0-based index of the car.

Return Values

Type	Description
ac.StateCar	A reference to the car’s data. Returns nil if the index is invalid.

Technical Notes

• Performance: Calling ac.getCar is extremely cheap (it returns a pointer to a pre-allocated FFI struct). However, it is still best practice to cache the reference if you use it many times in a single loop.
• Thread Safety: In physics scripts, this data is updated at the physics rate. In UI scripts, it is updated at the frame rate.

Examples

Check Player Speed

local car = ac.getCar(0)

if car.speedKmh > 100 then
    ac.log("Fast!")
end

Iterate All

-- it is usually better to use the iterator for multiple cars
for i, car in ac.iterateCars() do
    ui.text(string.format("Car %d: %s", i, car.driverName))
end