SgVehicle

Represents a physics-based vehicle composed of a chassis and one or more wheels. This class provides methods to control acceleration, braking, and steering directly from scripts.

Vehicles are useful for driving simulations, car games, or any physics-based scene where a rigid body with multiple wheel colliders is required.

Inherits from

SceneObject

Overview

A vehicle in the scenegraph consists of:

• Chassis: the main body of the vehicle. This must have physics enabled (as a rigid body) so that forces and collisions are simulated correctly.
• Wheels: individual wheel scene objects attached to the chassis. Do not enable physics on these; the vehicle system handles their motion internally.

Each wheel is automatically constrained and simulated according to its suspension and friction parameters defined in the editor or script.

You can distinguish front and rear wheels by their index or naming convention, and apply different steering or acceleration values to each group. Typically, front wheels handle steering, while rear wheels handle acceleration and braking, but this configuration is fully customizable.

In order to setup a vehicle correctly in Lemonate follow these steps:

1. Create the chassis

2. Add an SgVehicle object as a scene object.

3. Ensure “Enable Physics” is checked in the editor (or set in script).

4. The chassis should have a collision shape, typically a box or convex hull.

5. Add the wheels

6. Add four (or more) wheel scene objects as children of the chassis.

7. Do not enable physics on the wheels — they are automatically managed by the vehicle system.

8. Order or naming of the wheels determines their index, which you can use to apply controls per wheel (e.g., front-left = index 0).

9. Configure the vehicle

10. Use the vehicle editor parameters or Lua API to fine-tune suspension, friction, and wheel alignment.

11. If needed, attach a script to the Vehicle node so you can you can dynamically control steering, acceleration, and braking in Lua. See example-vehicle-lua

Usage

To use this class, add the following require at the top of your script:

local SgVehicle = require 'engine/sceneobjects/sgvehicle'

Reference

create

static create(self, options, parent)

Create a new vehicle object in the scenegraph.

Parameters

• self
• options (table): A table of options to fill the parameters
• parent (SceneObject): The parent scene object to add this to

Returns

• Promise: promise which will resolve to the created object

Example

-- Options can be omitted. This example shows the defaults,
-- only specify the ones you want different.
SgVehicle.create({
    active = true,
    name = "",
    transform = Transform.new(),
    layers = {0},
    tags = {},
    chassisNode = nil,
    wheels = {}
})

Properties

You can access these properties directly on the object or through :get("propertyName") or :set("propertyName", value) methods.

getSpeed

getSpeed()

Get speed in km/h of the vehicle

setSteering

setSteering(wheels)

Set the steering of the vehicle

Parameters

• wheels (table): an array of { index, value } objects setting a new steering value for wheels

setBrakes

setBrakes(wheels)

Set the brakes of the vehicle

Parameters

• wheels (table): an array of { index, value } objects setting a new brake value for wheels

setAcceleration

setAcceleration(wheels)

Set the acceleration of the vehicle

Parameters

• wheels (table): an array of { index, value } objects setting a new acceleration value for wheels

Examples