Vehicle Lua Cheat Sheet

Copy-paste one-liners for the most common vehicle scripting tasks. Keep this open while coding.

:::tip All snippets run in the VE (Vehicle Engine) context — inside lua/vehicle/extensions/ files. :::

1. Physical State (#core #physics #pos)

• Get Position (World): local pos = obj:getPosition()
• Get Velocity (m/s): local vel = obj:getVelocity()
• Get Speed (km/h): local speed = obj:getVelocity():length() * 3.6
• Get Direction (Forward): local fwd = obj:getDirectionVector()
• Get Direction (Up): local up = obj:getDirectionVectorUp()
• Get Rotation (Quat): local rot = obj:getRotation()
• Get Angular Velocity: local angVel = obj:getAngularVelocity()
• Teleport Vehicle (via GE): obj:queueGameEngineLua(string.format("be:getObjectByID(%d):setTransform(MatrixF(quat(0,0,0,1), vec3(0,0,0)))", obj:getId()))
• Apply Force (to Node): obj:applyForceVector(nodeId, vec3(0,1000,0))
• Get Total Mass: local mass = 0; for _, n in pairs(v.data.nodes) do mass = mass + n.nodeWeight end

2. Electrics & Data Bus (#electronics #speed #rpm)

• Get Engine RPM: local rpm = electrics.values.rpm or 0
• Get Throttle Input: local throttle = electrics.values.throttle or 0
• Get Brake Input: local brake = electrics.values.brake or 0
• Get Steering Input: local steering = electrics.values.steering or 0
• Get Airspeed (m/s): local airspeed = electrics.values.airspeed or 0
• Get Current Gear: local gear = electrics.values.gear or 0
• Check Ignition State: local ignition = electrics.values.ignitionLevel or 0 -- 0=off, 1=acc, 2=on, 3=start
• Toggle Hazard Lights: electrics.setIgnitionLevel(2); electrics.toggle_warn_signal()
• Get Battery Level (EV): local fuel = electrics.values.fuel or 0
• Custom Signal: electrics.values.mySignal = 1.0

3. Powertrain & Gearbox (#powertrain #gear #torque)

• Shift to Gear: controller.mainController.shiftToGearIndex(1)
• Set Gearbox Mode: controller.mainController.setGearboxMode('manual') -- 'arcade', 'realistic', 'manual'
• Get Engine Load: local engine = powertrain.getDevice("mainEngine"); local load = engine.engineLoad
• Get Wheel Speed: local speed = wheels.wheels[0].angularVelocity * wheels.wheels[0].radius
• Check if Engine Running: local isRunning = powertrain.getDevice("mainEngine").state == "running"
• Kill Engine: powertrain.getDevice("mainEngine"):lockUp()
• Apply Power Multiplier: powertrain.getDevice("mainEngine").outputTorqueState = 1.2 -- +20% power
• Check NOS Status: local nos = electrics.values.n2oActive or false
• Access Differential: local diff = powertrain.getDevice("rearDiff")

4. Damage & State (#damage #physics)

• Get Total Damage: local damage = beamstate.damage
• Is Tire Popped: local popped = damageTracker.getDamage("wheels", "tireFL")
• Is Engine Broken: local broken = damageTracker.getDamage("engine", "engineBlock")
• Check Radiator: local leaking = damageTracker.getDamage("engine", "radiator")
• Get Body Damage %: local fl = damageTracker.getDamage("body", "FL") or 0
• Deflate Tire: beamstate.deflateTire(0)
• Break All Hinges: beamstate.breakHinges()
• Get Part Condition: local cond = partCondition.getConditions()["engine"]
• Reset Vehicle: onVehicleReset()
• Check First Player: local seated = playerInfo.firstPlayerSeated

5. UI & Audio (#ui #communication #sound)

• UI Message (Toast): guihooks.message("Hello World", 5, "category")
• Send to Console: print("Value: " .. tostring(val))
• Play Sound (Once on Node): obj:playSFXOnce("event:>Vehicle>Failures>tire_burst", 0, 1, 1) -- event, nodeId, volume, pitch
• Trigger UI Hook: guihooks.trigger("myEvent", {data = 1})
• Update UI Stream: guihooks.queueStream("myValue", 100)
• Draw Line (Debug): obj.debugDrawProxy:drawLine(pos1, pos2, color)
• Draw Text (Debug): obj.debugDrawProxy:drawText(pos, color, "Hello")
• Draw Sphere (Debug): obj.debugDrawProxy:drawSphere(pos, 0.5, color)

6. Inter-VM & Logic (#communication #core)

• Call Game Engine: obj:queueGameEngineLua("print('Hello from VE')")
• Call Other Vehicle: obj:queueObjectLuaCommand(targetId, "print('Hello from Peer')")
• Set Timer: local timer = HighPerfTimer()
• Stop/Reset Timer: local ms = timer:stopAndReset()