Skip to content

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

../../_images/editor_vehicle.png

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 = {},
    receiveShadow = false,
    castShadow = false
})

Properties

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

Property Type Default Description
active Boolean true A Boolean attribute indicating whether the 3D object is active or not. When set to true, the object is considered active in the scene.
static Boolean false A Boolean attribute indicating whether the 3D object is static or not. Static objects can and will never be transformed during runtime.
transform Transform Transform.new() Specifies the transformation properties of the 3D object, including its position, rotation, and scale in the scene.
layers Layers [0] Determines the layers the 3D object belongs to. Layers are used to organize objects in the scene for various purposes like rendering and interaction.
tags Tags [] A list of tags associated with the 3D object. Tags are used for categorizing and identifying objects for scripting and scene management.
rendered Boolean true Indicates if the 3D object is being rendered.
chassisNode Node
wheelNode Node
isFront Boolean false
suspensionRestLength Float 0.6
suspensionStiffness Float 20
suspensionDamping Float 2.3
suspensionCompression Float 4.4
friction Float 1000
rollInfluence Float 0.2
radius Float 0.1
acceleration Float 0
brakes Float 0
steering Float 0
wheelNode Node
isFront Boolean false
suspensionRestLength Float 0.6
suspensionStiffness Float 20
suspensionDamping Float 2.3
suspensionCompression Float 4.4
friction Float 1000
rollInfluence Float 0.2
radius Float 0.1
acceleration Float 0
brakes Float 0
steering Float 0

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