Vehicle

Vehicle

A car in the world: yours, a Drivatar's, or traffic. Read where it is, how fast it goes and what its driver is doing, push it, light its exhausts or repair it.

Thread: game thread only (Game.Tick, Game.Run, an ANNA entry), or inside Game.PhysicsStep for the car it gives you.

You don't create a Vehicle yourself. You get one from Player.Car, World.Vehicles, World.GetNearestVehicle, World.GetVehiclesInRange or Game.PhysicsStep.

Example

A small boost: while you hold the throttle down on the ground, your car is pushed forwards at 10 m/s², and its exhausts shoot flames.

protected override void OnInit()
{
    Game.PhysicsStep += (car, dt) =>
    {
        if (car.IsPlayer && car.Throttle > 0.95f && car.IsOnGround)
            car.Velocity += car.ForwardFlat * (10 * dt);
    };

    Game.Tick += () =>
    {
        var car = Player.Car;
        if (car is not null) car.ExhaustFlames = car.Throttle > 0.95f;
    };
}

Protected Overrides Sub OnInit()
    AddHandler Game.PhysicsStep,
        Sub(car As Vehicle, dt As Single)
            If car.IsPlayer AndAlso car.Throttle > 0.95F AndAlso car.IsOnGround Then
                car.Velocity += car.ForwardFlat * (10 * dt)
            End If
        End Sub

    AddHandler Game.Tick,
        Sub()
            Dim car = Player.Car
            If car IsNot Nothing Then car.ExhaustFlames = car.Throttle > 0.95F
        End Sub
End Sub

Members

Properties

Member	What it does
Kind (property, get, VehicleKind)	Whose car it is: Player, Drivatar, Traffic or Other.
IsPlayer (property, get, bool)	True if it's your car.
ModelId (property, get, int)	The car's id, the one CarCatalog and Garage use.
Model (property, get, CarInfo?)	Which car it is, with its names. Null if the catalogue doesn't have it.
Position (property, get, Vector3)	Where it is, in metres.
Forward (property, get, Vector3)	Which way it points (length 1).
ForwardFlat (property, get, Vector3)	Which way it points, flattened to the ground (Y = 0) and of length 1. Good for pushing a car along the road without throwing it skyward. Zero when the nose points almost straight up or down.
Velocity (property, get/set, Vector3)	How fast and which way it's moving, in m/s. You can only set it inside Game.PhysicsStep, on the car it gives you. car.Velocity += car.ForwardFlat * (10 * dt) pushes it forwards at 10 m/s².
Speed (property, get, float)	Speed in m/s, as the car's own physics has it.
SpeedKmh (property, get, float)	Speed in km/h.
SpeedMph (property, get, float)	Speed in mph.
IsOnGround (property, get, bool)	True while it's on the ground. False from when it starts to fall freely (a jump, a crest) until a moment after it lands, so a bump doesn't count as ground at once.
IsInAir (property, get, bool)	The opposite of IsOnGround.
Gear (property, get, int)	The gear: 0 is reverse, 1 is first, and so on.
Rpm (property, get, float)	Engine speed in revolutions a minute.
Throttle (property, get, float)	The throttle as the car has it this frame, 0 to 1.
BrakePedal (property, get, float)	The brake as the car has it this frame, 0 to 1.
Steering (property, get, float)	The steering as the car has it this frame, -1 to 1.
Handbrake (property, get, float)	The handbrake as the car has it this frame, 0 to 1.
HeadlightsOn (property, get/set, bool)	The headlights. Setting them turns the game's automatic lights off for this car, as ANNA does.
ExhaustFlames (property, get/set, bool)	Flames out of the exhausts, a burst every 40 ms, until you set it back to false (or the car leaves the world). The game's own backfire effect, from the car's real exhaust tips. Works on any car. On cars other than yours: ⚠️ Not tested much in the game yet.
Handle (property, get, nint)	The game's own handle for the car, for advanced code of your own.

Methods

Member	What it does
Backfire(float seconds = 0.05f)	Flames out of the exhausts for seconds. The default is one pop. Does nothing if ExhaustFlames is already on.
Repair(bool simulated = true)	Repairs the car, as the game does when you enter the garage or start a road trip. The damage you see goes. With simulated true, the simulated damage goes too (what Damage & Tire Wear: Simulation does to the handling).
DistanceTo(Vector3 point) → float	Straight-line distance to point, in metres.
DistanceTo(Vehicle other) → float	Straight-line distance to another car, in metres.
Equals(Vehicle? other) → bool	True if both are the same car. Equals(object?) and GetHashCode() match it, so you can use cars as dictionary keys within a frame.
ToString() → string	The kind and short name of the car, for logs.

VehicleKind

Who's driving a car. Used by Vehicle.Kind and World.GetNearestVehicle.

Value	Meaning
Player (0)	Your car.
Drivatar (1)	A Drivatar's car.
Traffic (2)	A traffic car.
Other (3)	Anything else.

CarInfo

Vehicle.Model gives a CarInfo: the car's Id, ShortName ("Chevy Camaro SS") and FullName ("Camaro SS Coupe"). See Garage, CarCatalog and Profile.

Notes

• A Vehicle is only valid during the frame you got it in. Cars come and go as the world streams, so don't keep one between ticks. Get it again each time.
• Coordinates are the game's, in metres: X and Z across the map, Y up.
• Speeds are in m/s. SpeedKmh and SpeedMph convert for you.
• Setting Velocity anywhere but inside Game.PhysicsStep, for the car it gives you, throws an InvalidOperationException. The physics owns it the rest of the time.
• IsOnGround comes from the car's physics steps. It's true until the car has had a few.
• Using a Vehicle off the game thread (and outside Game.PhysicsStep) throws an InvalidOperationException that says to use Game.Tick or Game.Run.
• Exhaust flames go out when your mod is reloaded.
• On a game build the SDK doesn't know, ExhaustFlames and Backfire do nothing, and platform.log says so once ("Vehicle.ExhaustFlames off").

See also

• Player
• World
• Game
• Garage, CarCatalog and Profile
• Audio
• Camera