SceneObject¶

The SceneObject class represents an object within the scene graph. These objects can be anything from static geometry to dynamic entities with physics, scripts, and other properties. SceneObject provides a unified interface for interacting with scene elements, modifying their properties, and controlling their behavior.

Creating and Finding SceneObjects¶

Scene objects can be retrieved using static methods such as SceneObject.findByName(), SceneObject.findById() or SceneObject.findByTag().

-- Find an object by name
local obj = SceneObject.findByName("Player")
if obj then
    print("Found Player:", obj:getName())
end

-- Clone an object at a new position
obj:clone(Vector3.new(5, 0, 2)):next(function(clone)
    clone:setActive(true)
end)

Modifying SceneObjects¶

SceneObjects expose various methods to modify their properties, such as position, scale, rotation, and other fields.

-- Move the object in the scene
obj:translate(1, 0, 0)  -- Move 1 unit along the X-axis

-- Rotate the object 90 degrees on the Y-axis
obj:rotate(0, 90, 0)

-- Set a any field by name
obj:setFieldValue("CastShadow", true)

Physics and Interaction¶

If the object is part of the physics engine, you can apply forces, impulses, and velocities.

-- Apply an impulse to push an object upwards
obj:applyImpulse(Vector3.new(0, 5, 0), Vector3.new(0, 0, 0))

-- Set linear velocity
obj:setLinearVelocity(Vector3.new(2, 0, 0))  -- Moves the object to the right

Hierarchy and Parenting¶

SceneObjects can have a parent-child relationship, allowing structured organization.

-- Get the parent of an object
local parent = obj:getParent()
if parent then
    print("Parent object:", parent:getName())
end

-- Get child objects
local children = obj:getChildren()
for _, child in ipairs(children) do
    print("Child object:", child:getName())
end

Tags and Layers¶

SceneObjects support tagging and layering to organize and filter them.

-- Add a tag to an object
obj:addTag("Enemy")

-- Check if an object has a tag
if obj:hasTag("Enemy") then
    print("This object is an enemy!")
end

-- Assign the object to specific layers
obj:setLayers({1, 3})

Snapshots and State Management¶

SceneObjects support snapshotting, allowing state restoration.

-- Take a snapshot
local snapshot = obj:takeSnapshot(true)

-- Restore to the previous snapshot state
obj:rollbackSnapshot(snapshot)

Conclusion¶

SceneObject is a fundamental class for working with objects in the scene graph. It provides a flexible API for manipulation, physics, hierarchy, and interactivity. For a full list of available methods, see below.

Reference¶

class SceneObject¶

module:

static findByName(name)¶

Find an object by name and return it.

Parameters:¶: name (str) – Name of the object in the scenegraph.
Returns:¶: The found object or nil if not found.
Return type:¶: Object

Usage:

local obj = SceneObject.findByName("Player")
if obj then
    print("Found object:", obj:getName())
end

static findById(id)¶

Find an object by its unique ID and return it.

Parameters:¶: id (str) – The unique ID of the object.
Returns:¶: The found object or nil if not found.
Return type:¶: Object

Usage:

local obj = SceneObject.findById("2135a78324fe")
if obj then
    print("Found object: ", obj:getName())
end

static findByTag(tag)¶

Find all objects with a given tag and return them as a table.

Parameters:¶: tag (str) – The tag to search for.
Returns:¶: A table containing all objects with the given tag.
Return type:¶: table

Usage:

local enemies = SceneObject.findByTag("Enemy")
for _, enemy in ipairs(enemies) do
    print("Found enemy:", enemy:getName())
end

static create(objectType, options, parent)¶

Create a new object in the scenegraph. This is a generic function, for specialized versions, see the respective Sg<name> classes like SgBox.

Parameters:¶

objectType (str) – Type of object.
options (table) – The options to use. For information about the possible options, see the specialized functions below.
parent (Object) – the parent object to add the new one to or nil to put it at root level

Returns:¶

a promise resolving to a SceneObject

Return type:¶

Promise

Usage:

local promise = SceneObject.create(SceneObject.Type.Sphere, { radius = 1 }, nil)
promise:next(function(obj)
    obj:setActive(true)
end)

static fromHandle(handle)¶

Create a scene object by handle number. Used internally

Parameters:¶: handle (number)

getId()¶

Get the ID of the scene object.

Returns:¶: The unique ID of the object.
Return type:¶: str

Usage:

local obj = SceneObject.findByName("Cube")
print("Object ID:", obj:getId())

getName()¶

Get the name of the scene object.

Returns:¶: The user-defined name of the object.
Return type:¶: str

Usage:

local obj = SceneObject.findByName("Cube")
print("Object name:", obj:getName())

getDisplayName()¶

Return the display name of the scene object. In case the object has no user-given name, a name will be generated

in the format “type <id>”

Returns:¶: Displayname
Return type:¶: str

Usage:

local obj = SceneObject.findByName("Enemy")
print("Display name:", obj:getDisplayName())

getType()¶

Return the type of the object

Returns:¶: Type
Return type:¶: str

Usage:

local obj = SceneObject.findByName("Wall")
print("Object type:", obj:getType())

setFieldValue(name, value)¶

Set a field of the scene object to a new value.

Parameters:¶

name (str) – The name of the field.
value (str) – The new value to set.

Usage:

local obj = SceneObject.findByName("Light")
obj:setFieldValue("Brightness", "High")

setFieldColorValue(name, value)¶

Set a field of the scene object to a new color value.

Parameters:¶

name (str) – The name of the field.
value (Color) – The new color value.

Usage:

local obj = SceneObject.findByName("Cube")
obj:setFieldColorValue("Color", Color.new(1, 0, 0, 1)) -- Sets the object to red.

setFieldNumberValue(name, value)¶

Set a field of the scene object to a new number value.

Parameters:¶

name (str) – The name of the field.
value (number) – The new number value.

setFieldEnumValue(name, value)¶

Set a field of the scene object to a new enum value

Parameters:¶

name (str)
value (number)

setFieldBooleanValue(name, value)¶

Set a field of the scene object to a new boolean value

Parameters:¶

name (str)
value (boolean)

setLayers(layers)¶

Set the layers of the scene object.

Layers control rendering visibility and interaction with other objects.

Parameters:¶: layers (table) – A table containing layer indices.

Usage:

local obj = SceneObject.findByName("Character")
obj:setLayers({1, 3, 5}) -- Assigns the object to layers 1, 3, and 5.

getFieldValue(name)¶

Get a field value from the scene object.

Parameters:¶: name (str) – The name of the field.
Returns:¶: The value of the field.
Return type:¶: str

Usage:

local obj = SceneObject.findByName("Lamp")
local intensity = obj:getFieldValue("Intensity")
print("Intensity: " .. intensity)

getFieldColorValue()¶

Get the value of a scene object’s field as color value

Returns:¶: value of the field
Return type:¶: Color

Usage:

local obj = SceneObject.findByName("Lamp")
local color = obj:getFieldColorValue("Color")
print("Color: " .. color)

getFieldNumberValue()¶

Get the value of a scene object’s field as number value

Returns:¶: value of the field
Return type:¶: number

getFieldBooleanValue()¶

Get the value of a scene object’s field as boolean value

Returns:¶: value of the field
Return type:¶: boolean

getFieldEnumValue()¶

Get the value of a scene object’s field as string value

Returns:¶: value of the field
Return type:¶: str

getFieldEnumOptions()¶

Get the value of a scene object’s field as string value

Returns:¶: value of the field
Return type:¶: str

setFieldBooleanValue(name, value)

Set a field of the scene object to a new boolean value.

Parameters:¶

name (str) – The name of the field.
value (boolean) – The new boolean value.

Usage:

local obj = SceneObject.findByName("Door")
obj:setFieldBooleanValue("PhysicsEnabled", true)

getLayers()¶

Get the layers of the scene object

Returns:¶: A table containing layer indices
Return type:¶: table

getLinkItem(name)¶

Get a link of the scene object to a new value

Parameters:¶: name (str) – name of the link field
Returns:¶: handle of the linked item or nil if not set
Return type:¶: number

setLinkItem(name, item)¶

Set a link from the scene object

Parameters:¶

name (str) – name of the link field
item (str) – value can be either an item ID or an Item object

translate(x, y, z)¶

Translate (move) the scene object.

Moves the object by the given offset along each axis.

Parameters:¶

x (number) – Offset along the X-axis.
y (number) – Offset along the Y-axis.
z (number) – Offset along the Z-axis.

Usage:

local obj = SceneObject.findByName("Character")
if obj then
    obj:translate(0, 1, 0) -- Moves the object up by 1 unit
end

rotate(x, y, z)¶

Rotate the scene object.

Rotation is applied in degrees and follows Euler angles (XYZ order).

Parameters:¶

x (number) – Rotation around the X-axis in degrees.
y (number) – Rotation around the Y-axis in degrees.
z (number) – Rotation around the Z-axis in degrees.

Usage:

local obj = SceneObject.findByName("Cube")
if obj then
    obj:rotate(45, 0, 0) -- Rotates 45 degrees around the X-axis
end

scale(x, y, z)¶

Scale the scene object.

Parameters:¶

x (number) – Scale factor along the X-axis.
y (number) – Scale factor along the Y-axis.
z (number) – Scale factor along the Z-axis.

Usage:

local obj = SceneObject.findByName("Tree")
if obj then
    obj:scale(2, 2, 2) -- Doubles the size of the object
end

getTransform()¶

Get the local transform of a scene object.

The transform contains position, rotation, and scale relative to the object’s parent.

Returns:¶: The object’s local transform.
Return type:¶: Transform

Usage:

local obj = SceneObject.findByName("Character")
local transform = obj:getTransform()
print("Local position:", transform.position)

withTransform(func)¶

Apply a function to modify the object’s transform, then update it.

This allows making changes to the transform while ensuring they are properly applied back.

Parameters:¶: func (function) – A function that takes a Transform object as its only argument.

Usage:

local obj = SceneObject.findByName("Cube")
obj:withTransform(function(transform)
    transform.position.x = transform.position.x + 1  -- Move object 1 unit to the right
end)

getWorldTransform()¶

Get the world transform of a scene object.

The world transform includes absolute position, rotation, and scale in the scene.

Returns:¶: The object’s world transform.
Return type:¶: Transform

Usage:

local obj = SceneObject.findByName("Light")
local worldTransform = obj:getWorldTransform()
print("World position:", worldTransform.position)

setTransform(transform)¶

Set the local transform of a scene object.

Updates the object’s position, rotation, and scale relative to its parent.

Parameters:¶: transform (Transform) – The new local transform to apply.

Usage:

local obj = SceneObject.findByName("Door")
local newTransform = Transform.new()
newTransform.position = Vector3.new(0, 2, 0)  -- Move the object up 2 units
obj:setTransform(newTransform)

getLinearVelocity()¶

Get the linear velocity of the scene object.

This function returns the object’s velocity in world coordinates. Only works for objects added to the physics engine with watchLinearVelocity enabled.

Returns:¶: The linear velocity of the object.
Return type:¶: Vector3

Usage:

local obj = SceneObject.findByName("Ball")
local velocity = obj:getLinearVelocity()
print("Velocity:", velocity)

setLinearVelocity(velocity)¶

Set the linear velocity of the scene object.

This function assigns a new velocity to the object, but only works if the object is in the physics engine.

Parameters:¶: velocity (Vector3) – The new linear velocity to apply.

Usage:

local obj = SceneObject.findByName("Car")
obj:setLinearVelocity(Vector3.new(10, 0, 0)) -- Move object at speed 10 in the X direction.

getAngularVelocity()¶

Get the angular velocity of the scene object.

Only works for objects added to the physics engine with watchAngularVelocity enabled.

Returns:¶: The angular velocity of the object.
Return type:¶: Vector3

Usage:

local obj = SceneObject.findByName("Wheel")
local angVel = obj:getAngularVelocity()
print("Angular velocity:", angVel)

setAngularVelocity(velocity)¶

Set the angular velocity of the scene object.

Parameters:¶: velocity (Vector3) – The new angular velocity to apply.

Usage:

local obj = SceneObject.findByName("Propeller")
obj:setAngularVelocity(Vector3.new(0, 10, 0)) -- Rotate around Y-axis.

applyImpulse(impulse, relPos)¶

Apply an impulse to the scene object.

Parameters:¶

impulse (Vector3) – The force impulse to apply.
relPos (Vector3) – The relative position where the impulse is applied. Default is 0/0/0

Usage:

local obj = SceneObject.findByName("Box")
obj:applyImpulse(Vector3.new(0, 5, 0), Vector3.new(0, 0, 0)) -- Apply upward impulse.

applyForce(force, relPos)¶

Apply a force to the scene object.

Parameters:¶

force (Vector3) – The force vector to apply.
relPos (Vector3) – The relative position where the force is applied. Default is 0/0/0

Usage:

local obj = SceneObject.findByName("Ball")
obj:applyForce(Vector3.new(10, 0, 0), Vector3.new(0, 0, 0)) -- Push the object along X-axis.

delete()¶: Delete the scene object from the scene.

clone(x, y, z, parent)¶

Clone a scene object to a new position and return it.

The position can be provided as: 1. Separate x, y, z coordinates. 2. A Vector3 containing the position.

If no position is provided, the clone will appear in the same location as the original.

Parameters:¶

x (number or Vector3) – The X-coordinate of the new position, or a Vector3 containing x, y, z. If a Vector3 is passed, y and z should be omitted.
y (number) – (optional) The Y-coordinate of the new position. Omit this if passing a Vector3.
z (number) – (optional) The Z-coordinate of the new position. Omit this if passing a Vector3.
parent (SceneObject) – (optional) The parent object to attach the new object to.

Returns:¶

A promise resolving to a SceneObject.

Return type:¶

Promise

Usage:

local obj = scene:findByName("Tree")
obj:clone(5, 0, 2):next(function(clone)
    clone:setActive(true)  -- Activate the cloned object
end)

local pos = Vector3.new(3, 1, 0)
obj:clone(pos):next(function(clone)
    clone:setFieldValue("Name", "ClonedTree")  -- Rename the cloned object
end)

local parentObj = scene:findByName("Group")
obj:clone(pos, parentObj):next(function(clone)
    clone:setFieldValue("Name", "AnotherClonedTree")  -- Rename the cloned object
end)

setActive(value)¶

Set the active state of the scene object.

Parameters:¶: value (boolean) – True to activate, false to deactivate.

getActive()¶

Get the active state of the scene object.

Returns:¶: True if the object is active, false otherwise.
Return type:¶: boolean

hasTag(tagName)¶

Check if the object has a specific tag.

Parameters:¶: tagName (str) – The tag name to check.
Returns:¶: True if the object has the tag, false otherwise.
Return type:¶: boolean

getTags()¶

Get a list of all tags assigned to the object.

Returns:¶: An array of tag names.
Return type:¶: table

setTags(tags)¶

Assign a set of tags to the object.

Parameters:¶: tags (table) – An array of tag names.

addTag(tag)¶

Add a tag to the object.

Parameters:¶: tag (str) – The tag to add.

clearTags()¶: Remove all tags from the object.

takeSnapshot(recursive)¶

Take a snapshot of the object and its children, if specified.

This allows restoring the object to a previous state.

Parameters:¶: recursive (boolean) – Whether to include child objects in the snapshot.
Returns:¶: The snapshot handle.
Return type:¶: number

rollbackSnapshot(snapshot)¶

Restore a snapshot, reverting any changes made after the snapshot was taken.

Parameters:¶: snapshot (number) – The snapshot handle to restore.

isEnabled()¶

Check if the object is enabled.

Returns:¶: True if the object is enabled, false otherwise.
Return type:¶: boolean

enable()¶: Enable the object.

disable()¶: Disable the object.

getMaterial()¶

Get the material assigned to the object.

Returns:¶: The material, or nil if none is assigned.
Return type:¶: Material

getEntities()¶

Get all entities attached to this object.

Returns:¶: A list of Entity objects.
Return type:¶: table

getEntityByScriptName(name)¶

Get an entity attached to this object by its script name.

Parameters:¶: name (str) – The script name.
Returns:¶: The corresponding entity, or nil if not found.
Return type:¶: Entity

getParent()¶

Get the parent of the object.

Returns:¶: The parent object, or nil if none exists.
Return type:¶: SceneObject

getChildren()¶

Get the children of the object.

Returns:¶: A table of child objects.
Return type:¶: table

SceneObject¶

Creating and Finding SceneObjects¶

Modifying SceneObjects¶

Physics and Interaction¶

Hierarchy and Parenting¶

Tags and Layers¶

Snapshots and State Management¶

Conclusion¶

Reference¶

Examples¶