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:
Reference
findAllByName
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
selfname(string): Name of the objects in the scenegraph.root((optional)): SceneObject The root node to restrict the search to.
Returns
table: table containing all found objects, or an empty table if none are found.
Example
-- 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
findByName
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
selfname(string): Name of the object in the scenegraph.root((optional)): SceneObject The root node to restrict the search to.
Returns
Object|nil: first object found with the given name, or nil if not found.
Example
-- 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
findById
Find an object by its unique ID and return it.
Parameters
selfid(string): The unique ID of the object.
Returns
Object: found object or nil if not found.
Example
local obj = SceneObject.findById("2135a78324fe")
if obj then
print("Found object: ", obj:getName())
end
findByTag
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
selftag(string): The tag to look for.root((optional)): SceneObject The root node to restrict the search to.
Returns
table: table of objects that have the given tag. May be empty if no matches are found.
Example
-- 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
create
Create a new object in the scenegraph. This is a generic function, for specialized versions, see the respective Sg\<name> classes like SgBox.
Parameters
selfobjectType(string): Type of object (e.g., SceneObject.Type.Sphere).options(table): The options to use. Common options are listed below. Additional type-specific options are documented in the specialized functions (e.g., SgBox.create, SgSphere.create).parent(Object): the parent object to add the new one to or nil to put it at root level
Returns
Promise: promise resolving to a SceneObject
Example
-- Options can be omitted. This example shows the defaults,
-- only specify the ones you want different.
SceneObject.create(SceneObject.Type.Sphere, {
active = true,
static = false,
name = "",
transform = Transform.new(),
layers = {0},
tags = {},
receiveShadow = false,
castShadow = false,
-- Type-specific options (e.g., for Sphere):
radius = 1,
widthSegments = 8,
heightSegments = 6
}, nil):next(function(obj)
obj:setActive(true)
end)
getId
Get the ID of the scene object.
Returns
string: unique ID of the object.
Example
getName
Get the name of the scene object.
Returns
string: user-defined name of the object.
Example
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
string
Example
getType
Return the type of the object
Returns
string
Example
set
Set a field of the scene object to a new value.
Parameters
name(string): The name of the field.value(any): The new value to set.
Example
get
Get a field value from the scene object.
Parameters
name(string): The name of the field.
Returns
string: value of the field.
Example
local obj = SceneObject.findByName("Lamp")
local intensity = obj:get("Intensity")
print("Intensity: " .. intensity)
setFieldValue
Set a field of the scene object to a new value.
Parameters
name(string): The name of the field.value(any): The new value to set.
Example
getFieldValue
Get a field value from the scene object.
Parameters
name(string): The name of the field.
Returns
string: value of the field.
Example
local obj = SceneObject.findByName("Lamp")
local intensity = obj:getFieldValue("Intensity")
print("Intensity: " .. intensity)
animateFieldValue
Animate a field from its current value to a new value.
Parameters
name(string): The name of the fieldvalue(any): The new value to animate to.duration(number): The duration in milliseconds for the animation to takeease(string): The type of easing to use. Possible values: 'linear', 'easeInOutQuad'
Returns
number: id. Can be used to cancel animation using cancelAnimation(id)
cancelAnimation
Cancel a running animation
Parameters
id
setFieldColorValue
Set a field of the scene object to a new color value.
Parameters
name(string): The name of the field.value(Color): The new color value.
Example
local obj = SceneObject.findByName("Cube")
obj:setFieldColorValue("Color", Color.new(1, 0, 0, 1)) -- Sets the object to red.
setFieldNumberValue
Set a field of the scene object to a new number value.
Parameters
name(string): The name of the field.value(number): The new number value.
setFieldEnumValue
Set a field of the scene object to a new enum value
Parameters
name(string)value(number)
setFieldBooleanValue
Set a field of the scene object to a new boolean value.
Parameters
name(string): The name of the field.value(boolean): The new boolean value.
Example
getLayers
Get the layers of the scene object
Returns
table: table containing layer indices
setLayers
Set the layers of the scene object. Layers control rendering visibility and interaction with other objects.
Parameters
layers(table): A table containing layer indices.
Example
local obj = SceneObject.findByName("Character")
obj:setLayers({1, 3, 5}) -- Assigns the object to layers 1, 3, and 5.
getFieldColorValue
Get the value of a scene object's field as color value.
Parameters
name
Returns
Color: of the field
Example
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.
Parameters
name
Returns
number: of the field
getFieldBooleanValue
Get the value of a scene object's field as boolean value.
Parameters
name
Returns
boolean: of the field
getFieldEnumValue
Get the value of a scene object's field as string value.
Parameters
name
Returns
string: of the field
getFieldEnumOptions
Get the value of a scene object's field as string value
Parameters
name
Returns
string: of the field
getLinkItem
Get a link of the scene object to a new value
Parameters
name(string): name of the link field
Returns
number: of the linked item or nil if not set
setLinkItem
Set a link from the scene object
Parameters
name(string): name of the link fielditem(string): value can be either an item ID or an Item object
setPosition
Set the position of the scene object. Sets the object's local position to the given coordinates.
Parameters
x(number): Position along the X-axis.y(number): Position along the Y-axis.z(number): Position along the Z-axis.
Example
local obj = SceneObject.findByName("Player")
if obj then
obj:setPosition(0, 5, 0) -- Places the object at (0, 5, 0)
end
translate
Translate (move) the scene object by an offset. Adds the given offset to the object's current local position.
Parameters
x(number): Offset along the X-axis.y(number): Offset along the Y-axis.z(number): Offset along the Z-axis.
Example
local obj = SceneObject.findByName("Player")
if obj then
obj:translate(0, 1, 0) -- Moves the object up by 1 unit from its current position
end
rotate
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.
Example
local obj = SceneObject.findByName("Cube")
if obj then
obj:rotate(45, 0, 0) -- Rotates 45 degrees around the X-axis
end
scale
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.
Example
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.
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
Transform: object's local transform.
Example
local obj = SceneObject.findByName("Character")
local transform = obj:getTransform()
print("Local position:", transform.position)
withTransform
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
Example
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
Transform: object's world transform.
Example
local obj = SceneObject.findByName("Light")
local worldTransform = obj:getWorldTransform()
print("World position:", worldTransform.position)
getForward
Get the forward direction vector in world space. Returns the local -Z axis transformed by the object's rotation.
Returns
Vector3: forward direction in world space.
getRight
Get the right direction vector in world space. Returns the local +X axis transformed by the object's rotation.
Returns
Vector3: right direction in world space.
getUp
Get the up direction vector in world space. Returns the local +Y axis transformed by the object's rotation.
Returns
Vector3: up direction in world space.
setTransform
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.
Example
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)
setPhysicsPosition
Set the physics position of the scene object.
This directly updates the position of the object inside the physics engine. The position is expressed in world coordinates. Only works for objects added to the physics engine
Parameters
position(Vector3): New world position of the object.
Example
setPhysicsRotation
Parameters
rotation
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
Vector3: linear velocity of the object.
Example
local obj = SceneObject.findByName("Ball")
local velocity = obj:getLinearVelocity()
print("Velocity:", velocity)
setLinearVelocity
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.
Example
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
Vector3: angular velocity of the object.
Example
local obj = SceneObject.findByName("Wheel")
local angVel = obj:getAngularVelocity()
print("Angular velocity:", angVel)
setAngularVelocity
Set the angular velocity of the scene object.
Parameters
velocity(Vector3): The new angular velocity to apply.
Example
local obj = SceneObject.findByName("Propeller")
obj:setAngularVelocity(Vector3.new(0, 10, 0)) -- Rotate around Y-axis.
applyImpulse
Apply an impulse to the scene object.
An impulse is a sudden force applied to an object that immediately changes its velocity. This is different from a continuous force, which is applied over time.
This function only works on objects that are physics-enabled.
Parameters
impulse(Vector3): The force impulse to apply.relPos(Vector3): The relative position where the impulse is applied. Default is (0, 0, 0)
applyPushImpulse
Apply an impulse to the scene object that respects constraints.
Only works on physics-enabled objects.
Parameters
impulse(Vector3): The force impulse to apply.relPos(Vector3): The relative position where the impulse is applied. Default is (0, 0, 0)
applyCentralImpulse
Apply an impulse to the center of the object.
Applies a sudden velocity change at the object's center. Only works on physics-enabled objects.
Parameters
impulse(Vector3): The force impulse to apply.
Example
local obj = SceneObject.findByName("Box")
obj:applyCentralImpulse(Vector3.new(0, 5, 0)) -- Apply upward impulse.
applyCentralPushImpulse
Apply a central impulse that respects constraints.
Only works on physics-enabled objects and respects any joint or constraint applied.
Parameters
impulse(Vector3): The force impulse to apply.
Example
local obj = SceneObject.findByName("Box")
obj:applyCentralPushImpulse(Vector3.new(0, 5, 0)) -- Apply upward impulse.
applyForce
Apply a force to the scene object.
Unlike impulses, forces are applied over time, influencing the object's acceleration. Only works on physics-enabled objects.
Parameters
force(Vector3): The force vector to apply.relPos(Vector3): The relative position where the force is applied. Default is (0, 0, 0)
clearForces
Clear any forces on a scene object. Only works on physics-enabled objects.
Example
delete
Delete the scene object from the scene.
Example
clone
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): | 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.
Example
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
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 objectparent(SceneObject): (optional) The parent object to attach the new object to.
Example
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
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
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
boolean: if the object is active, false otherwise.
hasTag
Check if the object has a specific tag.
Parameters
tagName(string): The tag name to check.
Returns
boolean: if the object has the tag, false otherwise.
getTags
Get a list of all tags assigned to the object.
Returns
table: array of tag names.
setTags
Assign a set of tags to the object.
Parameters
tags(table): An array of tag names.
addTag
Add a tag to the object.
Parameters
tag(string): The tag to add.
clearTags
Remove all tags from the object.
takeSnapshot
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
number: snapshot handle.
rollbackSnapshot
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
boolean: if the object is enabled, false otherwise.
enable
Enable the object.
disable
Disable the object.
getMaterial
Get the material assigned to the object.
Returns
Material: material, or nil if none is assigned.
setMaterial
Set the object's material.
Parameters
mat(Material): The material to set or nil to clear the material
getEntities
Get all behaviours attached to this object.
Returns
table: list of Behaviour objects.
getBehaviours
Get all behaviours attached to this object.
Returns
table: list of Behaviour objects.
getBehaviourByScriptName
Get a behaviour attached to this object by its script name.
Parameters
name(string): The script name.
Returns
Behaviour: corresponding behaviour, or nil if not found.
getEntityByScriptName
Get a behaviour attached to this object by its script name.
Parameters
name(string): The script name.
Returns
Behaviour: corresponding behaviour, or nil if not found.
behaviour
Get a behaviour attached to this object by its script name.
Parameters
name(string): The script name.
Returns
Behaviour: corresponding behaviour, or nil if not found.
entity
Get a behaviour attached to this object by its script name.
Parameters
name(string): The script name.
Returns
Behaviour: corresponding behaviour, or nil if not found.
getParent
Get the parent of the object.
Returns
SceneObject: parent object, or nil if none exists.
getChildren
Get the children of the object.
Returns
table: table of child objects.
setAutoRecreate
Enable or disable automatic recreation of the scene object between play and stop.
When value is true, the object will be automatically recreated every time the scene starts or stops. This is useful for objects that need to reset physics, state, or procedural components at each run.
Parameters
value(boolean): Enable (true) or disable (false) automatic recreation.
recreate
Immediately recreate the scene object.
This forces the object to reset its state, physics, and components as if it was newly instantiated in the scene.
getBounds
Return the bounds of the scene object
Returns
Bounds: bounds of the object
Enum: Type
Enumeration of the available types to use with SceneObject.create()
| Field Name | Description |
|---|---|