Vehicles#

A vehicle is an object somebody can get into and drive: a car, a bike, a truck, a boat, a plane.

local self = require("self") self:vehicle({ preset = "car" })

That is a whole car. Click it to get in: W / S drive and brake, A / D steer, Space is the handbrake, Shift is the boost, F gets out.

The object can be one box or a model made of parts. Either way it becomes one body that the physics moves, and it is driven without delay: the driver's own game simulates the car while the region checks it.

The presets#

A preset is a starting point. Every number in it can be replaced, and only the ones you name change:

self:vehicle({    preset = "drift",    mass = 1100,    engine = { power = 400, top_speed = 240 },    wheels = { rear = { grip = 0.85 } },})

self:vehicle(options) → true, or nil, reason

A misspelt option is refused on the line that wrote it, with the names it could have been:

local ok, why = self:vehicle({ engine = { powr = 400 } })-- nil, "unknown option 'engine.powr' (it has: power, top_speed, gears, ...)"

self:vehicle(false) stops the object being a vehicle.

Wheels and seats, by name#

When the object is a model made of parts, the vehicle reads the parts' names:

So a downloaded car whose wheels are called wheel-front-left, wheel-back-right and so on needs nothing more than the one line. The wheel parts turn, steer and ride on their suspension by themselves.

With no wheel parts, a car or a bike gets wheels at the corners of its body, which work the same and are simply not drawn. With no seat part, the vehicle itself is the driver's seat.

A seat is an ordinary seat: its place and direction are set in the editor's Physics page, live, while you sit in it. The Driver's seat switch there says which one drives.

Which way is the front#

The front is read from the wheels' names when they say. Otherwise it is the object's forward (-z), or +x when the object is longer along x. Say it when the model points another way:

self:vehicle({ preset = "car", front = "+z" })   -- "-z", "+z", "+x" or "-x"

The options#

Positions are in the object's own frame, in metres.

engine#

wheels#

Fields given directly apply to every wheel. front = { … } and rear = { … } apply to one end. A list replaces the wheels altogether.

stiffness and damping do not depend on the vehicle's weight: the same numbers ride the same on a kart and on a truck. And the vehicle always sits at the height it was modelled at, whatever it weighs.

self:vehicle({    preset = "car",    wheels = { all = { travel = 0.35, stiffness = 1.3 }, rear = { grip = 1.0 } },})

More grip behind than in front makes a car that runs wide at the limit and does not spin. Less grip behind makes one that oversteers. That one balance is most of how a car feels.

steering#

drift is the dial between a car that never spins and a car that drifts. With the steering key held, the assist lets the tail hang out this far and then turns the wheels the other way by itself. 10 is a road car; 40 is a drift car. assist = 0 is a raw wheel with no help at all.

brakes#

aero#

assist#

thrusters#

A force at a point: a propeller, a jet, a rocket. A list.

local vec = require("vec") self:vehicle({    preset = "car",    thrusters = { { pos = vec(0, 0.5, 2), accel = 14, axis = "boost" } },})

wings#

A surface that lifts: lift across the airflow, drag along it. A list.

hull#

How the body sits in water, on top of the floating every object already does.

controls#

controls = "car" (the default) or "plane".

Reading it#

vehicle_state#

self:vehicle_state() → a table, or nil when the object is not a vehicle

local self = require("self")local players = require("players") self:vehicle({ preset = "car" }) local DASH = {    id = "dash", size = { 150, 60 }, vars = { kmh = 0, gear = 1 },    pages = { main = {        { "text", "{kmh} km/h", size = 22, align = "center" },        { "text", "gear {gear}", size = 12, align = "center" },    } },} self:on_sit(function(p)    p:show_hud(DASH)end) self:on_stand(function(p)    p:hide_hud("dash")end) self:on_timer(0.2, function()    local v = self:vehicle_state()    local p = v and v.driver and players:get(v.driver)    if p then        p:update_hud("dash", { kmh = math.floor(math.abs(v.kmh)), gear = v.gear })    endend)

vehicle_input#

self:vehicle_input(controls) → true, or nil, reason

The script drives. For a car with nobody in it: traffic, a taxi, a ghost.

self:vehicle_input(nil) hands the vehicle back to whoever sits in the driver's seat.

self:vehicle({ preset = "car" })self:vehicle_input({ throttle = 0.5, steer = 0.4 })

In multiplayer#

The driver's own machine runs the vehicle they drive. Steering, braking and the camera answer on the frame a key is pressed, at any ping. Everybody else sees the vehicle a moment behind, exactly in step with its driver's avatar.

The server checks every report it gets about a driven vehicle. It refuses a vehicle going faster than its own engine.top_speed (or its fastest thruster) allows, one that jumps from place to place, one that goes through a wall, and one under the ground. A refused vehicle goes back to the last place the server accepted.

• A script that pushes a driven vehicle (self:push, self:set_velocity) takes it back from the driver for that moment. The push lands exactly as scripted.
• A script driving with self:vehicle_input drives it on the server, and the driver's keys wait until self:vehicle_input(nil).
• Getting out of a moving vehicle brakes it to a stop first. Holding the leave key gets out at once, whatever the vehicle is doing.

Loose physics objects work the same way while someone on foot pushes them. The pusher's machine moves the object, and the server keeps it within reach of that player. When a second player walks into the object, the server takes it back.

Common mistakes#

See also#

• Being sat on: seats, and how a script seats somebody
• Joints: doors, lifts and other things that move on a hinge
• HUD reference: for a dashboard

Updated 17 October 2026