SceneObject¶

The SceneObject class represents a live object in the scene graph. It exists and behaves within the running scene. SceneObjects can represent anything from static geometry (like an SgSphere or SgBox) to dynamic, interactive elements with physics, animations, or scripts attached.

Unlike Items, SceneObjects are not persistent assets; they exist only at runtime. Some may be created from Items, while others (like procedural primitives or dynamically generated objects) can exist entirely on their own.

The SceneObject class provides a unified interface to inspect, modify, and control scene elements — including their transforms, visibility, materials, and behavi

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)

Usage¶

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

local SceneObject = require 'engine/sceneobject'

Reference¶

class SceneObject¶

module:

static findAllByName(name)¶

Finds all objects with the given name.

The search can be restricted to a specific hierarchy by passing a root node. If no root is provided, the search covers the entire scene.

This function supports both static and instance usage:

Static call SceneObject.findAllByName(name root?) Searches the entire scene unless a root node is provided.

Instance call obj:findAllByName(name, root?) Uses obj as the root of the search unless an explicit root argument is passed. Ideal when searching only within a specific hierarchy.

Parameters:: name (str) – Name of the objects in the scenegraph.
Returns:: A table containing all found objects, or an empty table if none are found.
Return type:: table

Usage:

-- Global search
local objects = SceneObject.findAllByName("Enemy")
for _, obj in ipairs(objects) do
    print("Found object with type:", obj:getType())
end

-- Scoped search under a specific parent node
local level = SceneObject.findByName("Level1")
local objects = SceneObject.findAllByName("Enemy", level)
for _, obj in ipairs(objects) do
    print("Found object under parent with type:", obj:getType())
end

-- Instance call: search within a specific object's hierarchy
local level = SceneObject.findByName("Level1")
local enemies = level:findAllByName("Enemy")
for _, obj in ipairs(enemies) do
    print("Found enemy under level:", obj:getName())
end

static findByName(name)¶

Finds the first occurrence of an object with the given name.

The search can be restricted to a specific hierarchy by passing a root node. If no root is provided, the search covers the entire scene.

This function supports both static and instance usage:

Static call SceneObject.findByName(name root) Searches the entire scene unless a root node is provided.

Instance call obj:findByName(name root) Uses obj as the root of the search unless an explicit root argument is passed. Ideal when searching only within a specific hierarchy.

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

Usage:

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

-- Scoped search under a specific parent node
local obj = SceneObject.findByName("Player", parentNode)
if obj then
    print("Found object under parent:", obj:getName())
end

-- Instance call: search within a specific object's hierarchy
local player = SceneObject.findByName("Player")
local weapon = player:findByName("Weapon")
if weapon then
    print("Found weapon under player:", weapon: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)¶

Finds all objects that have the specified tag.

The search can be limited to a specific hierarchy by passing a root node. If no root is provided, the search scans the entire scene.

This function supports both static and instance usage:

Static call SceneObject.findByTag(tag, root) Searches the entire scene unless a root node is provided.

Instance call obj:findByTag(tag, root) Uses obj as the root of the search unless an explicit root argument is passed. Ideal when searching only within a specific hierarchy.

Parameters:: tag (str) – The tag to look for.
Returns:: A table of objects that have the given tag. May be empty if no matches are found.
Return type:: table

Usage:

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

-- Scoped search under a specific parent node
local tagged = SceneObject.findByTag("Interactable", parentNode)
for _, obj in ipairs(tagged) do
    print("Found interactable under parent:", obj:getName())
end

-- Instance call: search within a specific object's hierarchy
local level = SceneObject.findByName("Level1")
local enemies = level:findByTag("Enemy")
for _, enemy in ipairs(enemies) do
    print("Found enemy under level:", 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)

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())

set(name, value)¶

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

Parameters:

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

Usage:

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

get(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:get("Intensity")
print("Intensity: " .. intensity)

setFieldValue(name, value)¶

Deprecated since version 25.11: Use set which is the new shorter version

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

Parameters:

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

Usage:

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

getFieldValue(name)¶

Deprecated since version 25.11: Use get which is the new shorter version

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)

animateFieldValue(name, value, duration, ease)¶

Animate a field from its current value to a new value.

Parameters:

name (str) – The name of the field
value (any) – The new value to animate to.
duration (number) – The duration in milliseconds for the animation to take
ease (str) – The type of easing to use. Possible values: ‘linear’, ‘easeInOutQuad’

Returns:

animation id. Can be used to cancel animation using cancelAnimation(id)

Return type:

number

cancelAnimation(name)¶

Cancel a running animation

Parameters:: name (str) – The name of the field

setFieldColorValue(name, value)¶

Deprecated since version 25.09: Use set which handle the correct type automatically.

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)¶

Deprecated since version 25.09: Use set which handle the correct type automatically.

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)¶

Deprecated since version 25.09: Use set which handle the correct type automatically.

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.

getFieldColorValue()¶

Deprecated since version 25.09: Use get which always returns the correct type.

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()¶

Deprecated since version 25.09: Use get which always returns the correct type.

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

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

getFieldBooleanValue()¶

Deprecated since version 25.09: Use get which always returns the correct type.

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

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

getFieldEnumValue()¶

Deprecated since version 25.09: Use get which always returns the correct type.

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)

Deprecated since version 25.09: Use set which handle the correct type automatically.

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)¶

Deprecated since version 25.11: Use get which handles items now too

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)¶

Deprecated since version 25.11: Use set which handles items now too

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(cacheLocal)¶

Get the local transform of a scene object.

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

Parameters:: cacheLocal (boolean) – if set to true, the transform will be cached locally for the future for performance reasons. This should only be used if no other script changes the transform
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, cacheLocal)¶

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.
cacheLocal (boolean) – if set to true, the transform will be cached locally for the future for performance reasons. This should only be used if no other script changes the transform

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.

applyPushImpulse(impulse, relPos)¶

Apply an impulse to the scene object that will also respect constraints

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:applyPushImpulse(Vector3.new(0, 5, 0), Vector3.new(0, 0, 0)) -- Apply upward impulse.

applyCentralImpulse(impulse)¶

Apply an impulse to the center of the object

Parameters:: impulse (Vector3) – The force impulse to apply.

Usage:

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

applyCentralPushImpulse(impulse)¶

Apply an impulse to the center of the object that will also respect constraints

Parameters:: impulse (Vector3) – The force impulse to apply.

Usage:

local obj = SceneObject.findByName("Box")
obj:applyCentralPushImpulse(Vector3.new(0, 5, 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.

clearForces()¶: Clear any forces on a scene object.

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)

createFromThis(options, parent)¶

Create a new object of same type from this one. If no options are specified this will be basically a clone.

If an options table is passed, this will specify all fields with their values that should be changed. At the very least, this should contain a new Transform, otherwise the new object will be at the exact location of the old one.

Parameters:

options (table) – the table of fields to set on the new object
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 = SceneObject.findByName("Tree")
local parentObj = SceneObject.findByName("Group")
local clone = await(obj:createFromThis({
    transform = Transform.new(Vector3.new(4, 6, 8)),
    active = true,
    name = "Cloned tree"
}, parentObj)

moveToParent(parent)¶

Move the scene object to a different parent. This parent can not be a child of the scene object

Parameters:: parent (SceneObject) – (optional) The parent object to attach the new object to. if nil, the object will be moved to the scenegraph root

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

setMaterial(mat)¶

Set the object’s material.

Parameters:: mat (Material) – The material to set or nil to clear the material

getEntities()¶

Deprecated since version 25.12: use getBehaviours.

Get all behaviours attached to this object.

Returns:: A list of Behaviour objects.
Return type:: table

getBehaviours()¶

Get all behaviours attached to this object.

Returns:: A list of Behaviour objects.
Return type:: table

getBehaviourByScriptName(name)¶

Get a behaviour attached to this object by its script name.

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

getEntityByScriptName(name)¶

Deprecated since version ?.

Get a behaviour attached to this object by its script name.

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

behaviour(name)¶

Get a behaviour attached to this object by its script name.

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

entity(name)¶

Get a behaviour attached to this object by its script name.

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

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

setAutoRecreate(value)¶

Parameters:: value (any)

recreate()¶