SceneTree - Scene Graph Queries

Reference for `scenetree`, the scene graph interface for finding and manipulating engine objects (vehicles, lights, sound emitters, terrain, GUI elements, etc.).

Reference for scenetree, the scene graph interface for finding and manipulating engine objects (vehicles, lights, sound emitters, terrain, GUI elements, etc.).

Overview

scenetree provides access to the Torque3D scene graph. Unlike be (which manages the vehicle object pool), scenetree can find any engine object - including non-vehicle entities like terrain, lights, cameras, sound objects, and GUI canvases.

Method	Purpose
`scenetree.findObject(name)`	Find by string name
`scenetree.findObjectById(id)`	Find by numeric ID
`scenetree.findClassObjects(class)`	Find all of a class
`scenetree.<name>`	Direct named access (shorthand)

Finding Objects

By Name

-- Standard lookup
local obj = scenetree.findObject("objectName")
if obj then
    local pos = obj:getPosition()
end

-- Returns nil if not found - always guard!
local gate = scenetree.findObject("Level Gate")
if gate then
    gate:setHidden(true)
end

By ID

-- Numeric ID lookup (vehicles, sounds, etc.)
local vehicle = scenetree.findObjectById(vehId)
local sound = scenetree.findObjectById(soundObjectIds[label])

-- Common pattern: check existence before use
if scenetree.findObjectById(vehId) then
    -- Object still exists
end

Direct Named Access (Shorthand)

-- Access well-known engine objects directly as properties
-- This is equivalent to scenetree.findObject("tod")
scenetree.tod.play = false          -- Stop time-of-day cycle
scenetree.tod.play = true           -- Resume

-- GUI canvas
local canvas = scenetree.findObject("Canvas")

-- Named camera frustum
scenetree.OnlyGui:setFrustumCameraCenterOffset(Point2F(0, 0))
scenetree.OnlyGui:setFrustumCameraCenterOffset(Point2F(-0.3125, 0))

By Class

-- Find all objects of a specific engine class
local allLights = scenetree.findClassObjects("PointLight")
local allTriggers = scenetree.findClassObjects("Trigger")
local allMarkers = scenetree.findClassObjects("TSStatic")

-- Returns a table of object IDs
for _, id in ipairs(allTriggers) do
    local trigger = scenetree.findObjectById(id)
    if trigger then
        -- process trigger
    end
end

Object Properties & Methods

Common Methods (All Scene Objects)

Method	Returns	Description
`obj:getPosition()`	`Point3F`	World position
`obj:setPosition(pos)`	-	Move object
`obj:getRotation()`	`QuatF`	Orientation
`obj:setRotation(rot)`	-	Rotate object
`obj:getScale()`	`Point3F`	Scale vector
`obj:setScale(scale)`	-	Set scale
`obj:getTransform()`	`MatrixF`	Full transform matrix
`obj:setTransform(mat)`	-	Set full transform
`obj:getID()`	`number`	Unique object ID
`obj:getName()`	`string`	Object name
`obj:getClassName()`	`string`	Engine class (e.g. `"BeamNGVehicle"`)
`obj:setHidden(bool)`	-	Show/hide object
`obj:isHidden()`	`boolean`	Visibility state
`obj:delete()`	-	Remove from scene

Dynamic Fields

Scene objects support dynamic fields (custom key-value data):

-- Get a dynamic field
local value = obj:getDynDataFieldbyName("myField", 0)

-- Set a dynamic field
obj:setDynDataFieldbyName("myField", 0, "myValue")

Common Engine Classes

Class	Description	Example Use
`BeamNGVehicle`	Vehicle objects	Player/traffic cars
`TSStatic`	Static mesh objects	Props, buildings, markers
`Trigger`	Volume triggers	Enter/exit zones
`PointLight`	Point light source	Scene lighting
`SpotLight`	Spotlight source	Focused lighting
`SFXEmitter`	Sound emitter	Ambient/event sounds
`DecalRoad`	Road decal	Visual road markings
`TerrainBlock`	Terrain chunk	Ground mesh
`SimGroup`	Object container	Grouping objects
`SimSet`	Object set	Flat collection
`LevelInfo`	Level metadata	Map info

Working with Groups

Scene objects can be organized in SimGroup hierarchies:

-- Get a group
local group = scenetree.findObject("MissionGroup")
if group then
    local count = group:getCount()
    for i = 0, count - 1 do
        local child = group:getObject(i)
        local name = child:getName()
        local class = child:getClassName()
    end
end

Time of Day Control

The TimeOfDay object is commonly accessed via scenetree:

-- Stop/start day-night cycle
scenetree.tod.play = false
scenetree.tod.play = true

-- Or via core_environment:
core_environment.setTimeOfDay({time = 0.5})  -- 0.0-1.0 (0.5 = noon)

Common Patterns

Safe Object Access

local function getObjectSafe(name)
    local obj = scenetree.findObject(name)
    if not obj then
        log('W', 'myMod', 'Object not found: ' .. name)
        return nil
    end
    return obj
end

Vehicle Lookup (scenetree vs be)

-- These achieve similar results for vehicles:
local veh1 = be:getObjectByID(vehId)        -- Via engine binding
local veh2 = scenetree.findObjectById(vehId) -- Via scene graph
local veh3 = getObjectByID(vehId)            -- Global shortcut

-- scenetree is more general - works for ANY object type
-- be methods are vehicle-pool-specific and slightly faster

Create and Track Sound Objects

-- Create sound (typical engine pattern)
local sound = createObject("SFXEmitter")
sound:setPosition(pos)
sound.fileName = "/art/sounds/my_sound.ogg"
sound:registerObject("mySoundEmitter")

-- Later, find it
local snd = scenetree.findObject("mySoundEmitter")
if snd then
    snd:play()
end

-- Clean up
local snd = scenetree.findObjectById(soundId)
if snd then
    snd:delete()
end

Check Object Type

local obj = scenetree.findObject("something")
if obj and obj:getClassName() == "BeamNGVehicle" then
    -- It's a vehicle, safe to call vehicle methods
    obj:queueLuaCommand("print('hello from VE')")
end

Gotchas

scenetree.findObject returns nil silently - Always guard the return value.
Direct property access (scenetree.tod) only works for well-known names - For arbitrary names use findObject.
Objects can be destroyed between frames - Cache IDs, not object references, for long-lived state.
findClassObjects returns IDs, not objects - You must call findObjectById on each result.
Scene objects are not available during early boot - Wait for onClientPostStartMission or onWorldReadyState(2) hooks.
delete() is immediate - The object is gone right away. Any cached references become invalid.

Quick Reference

-- Find objects
scenetree.findObject("name")           -- By name → object or nil
scenetree.findObjectById(id)           -- By ID → object or nil
scenetree.findClassObjects("TSStatic") -- By class → table of IDs

-- Direct access to well-known objects
scenetree.tod.play = false

-- Object basics
obj:getPosition()        -- Point3F
obj:setPosition(pos)
obj:getClassName()       -- "BeamNGVehicle", "TSStatic", etc.
obj:setHidden(true)
obj:delete()

-- Groups
group:getCount()
group:getObject(i)       -- 0-indexed

Overview

Method	Purpose
`scenetree.findObject(name)`	Find by string name
`scenetree.findObjectById(id)`	Find by numeric ID
`scenetree.findClassObjects(class)`	Find all of a class
`scenetree.<name>`	Direct named access (shorthand)

Finding Objects

By Name

-- Standard lookup
local obj = scenetree.findObject("objectName")
if obj then
    local pos = obj:getPosition()
end

-- Returns nil if not found - always guard!
local gate = scenetree.findObject("Level Gate")
if gate then
    gate:setHidden(true)
end

By ID

-- Numeric ID lookup (vehicles, sounds, etc.)
local vehicle = scenetree.findObjectById(vehId)
local sound = scenetree.findObjectById(soundObjectIds[label])

-- Common pattern: check existence before use
if scenetree.findObjectById(vehId) then
    -- Object still exists
end

Direct Named Access (Shorthand)

-- Access well-known engine objects directly as properties
-- This is equivalent to scenetree.findObject("tod")
scenetree.tod.play = false          -- Stop time-of-day cycle
scenetree.tod.play = true           -- Resume

-- GUI canvas
local canvas = scenetree.findObject("Canvas")

-- Named camera frustum
scenetree.OnlyGui:setFrustumCameraCenterOffset(Point2F(0, 0))
scenetree.OnlyGui:setFrustumCameraCenterOffset(Point2F(-0.3125, 0))

By Class

-- Find all objects of a specific engine class
local allLights = scenetree.findClassObjects("PointLight")
local allTriggers = scenetree.findClassObjects("Trigger")
local allMarkers = scenetree.findClassObjects("TSStatic")

-- Returns a table of object IDs
for _, id in ipairs(allTriggers) do
    local trigger = scenetree.findObjectById(id)
    if trigger then
        -- process trigger
    end
end

Object Properties & Methods

Common Methods (All Scene Objects)

Method	Returns	Description
`obj:getPosition()`	`Point3F`	World position
`obj:setPosition(pos)`	-	Move object
`obj:getRotation()`	`QuatF`	Orientation
`obj:setRotation(rot)`	-	Rotate object
`obj:getScale()`	`Point3F`	Scale vector
`obj:setScale(scale)`	-	Set scale
`obj:getTransform()`	`MatrixF`	Full transform matrix
`obj:setTransform(mat)`	-	Set full transform
`obj:getID()`	`number`	Unique object ID
`obj:getName()`	`string`	Object name
`obj:getClassName()`	`string`	Engine class (e.g. `"BeamNGVehicle"`)
`obj:setHidden(bool)`	-	Show/hide object
`obj:isHidden()`	`boolean`	Visibility state
`obj:delete()`	-	Remove from scene

Dynamic Fields

Scene objects support dynamic fields (custom key-value data):

-- Get a dynamic field
local value = obj:getDynDataFieldbyName("myField", 0)

-- Set a dynamic field
obj:setDynDataFieldbyName("myField", 0, "myValue")

Common Engine Classes

Class	Description	Example Use
`BeamNGVehicle`	Vehicle objects	Player/traffic cars
`TSStatic`	Static mesh objects	Props, buildings, markers
`Trigger`	Volume triggers	Enter/exit zones
`PointLight`	Point light source	Scene lighting
`SpotLight`	Spotlight source	Focused lighting
`SFXEmitter`	Sound emitter	Ambient/event sounds
`DecalRoad`	Road decal	Visual road markings
`TerrainBlock`	Terrain chunk	Ground mesh
`SimGroup`	Object container	Grouping objects
`SimSet`	Object set	Flat collection
`LevelInfo`	Level metadata	Map info

Working with Groups

Scene objects can be organized in SimGroup hierarchies:

-- Get a group
local group = scenetree.findObject("MissionGroup")
if group then
    local count = group:getCount()
    for i = 0, count - 1 do
        local child = group:getObject(i)
        local name = child:getName()
        local class = child:getClassName()
    end
end

Time of Day Control

The TimeOfDay object is commonly accessed via scenetree:

-- Stop/start day-night cycle
scenetree.tod.play = false
scenetree.tod.play = true

-- Or via core_environment:
core_environment.setTimeOfDay({time = 0.5})  -- 0.0-1.0 (0.5 = noon)

Common Patterns

Safe Object Access

local function getObjectSafe(name)
    local obj = scenetree.findObject(name)
    if not obj then
        log('W', 'myMod', 'Object not found: ' .. name)
        return nil
    end
    return obj
end

Vehicle Lookup (scenetree vs be)

-- These achieve similar results for vehicles:
local veh1 = be:getObjectByID(vehId)        -- Via engine binding
local veh2 = scenetree.findObjectById(vehId) -- Via scene graph
local veh3 = getObjectByID(vehId)            -- Global shortcut

-- scenetree is more general - works for ANY object type
-- be methods are vehicle-pool-specific and slightly faster

Create and Track Sound Objects

-- Create sound (typical engine pattern)
local sound = createObject("SFXEmitter")
sound:setPosition(pos)
sound.fileName = "/art/sounds/my_sound.ogg"
sound:registerObject("mySoundEmitter")

-- Later, find it
local snd = scenetree.findObject("mySoundEmitter")
if snd then
    snd:play()
end

-- Clean up
local snd = scenetree.findObjectById(soundId)
if snd then
    snd:delete()
end

Check Object Type

local obj = scenetree.findObject("something")
if obj and obj:getClassName() == "BeamNGVehicle" then
    -- It's a vehicle, safe to call vehicle methods
    obj:queueLuaCommand("print('hello from VE')")
end

Gotchas

scenetree.findObject returns nil silently - Always guard the return value.
Direct property access (scenetree.tod) only works for well-known names - For arbitrary names use findObject.
Objects can be destroyed between frames - Cache IDs, not object references, for long-lived state.
findClassObjects returns IDs, not objects - You must call findObjectById on each result.
Scene objects are not available during early boot - Wait for onClientPostStartMission or onWorldReadyState(2) hooks.
delete() is immediate - The object is gone right away. Any cached references become invalid.

Quick Reference

-- Find objects
scenetree.findObject("name")           -- By name → object or nil
scenetree.findObjectById(id)           -- By ID → object or nil
scenetree.findClassObjects("TSStatic") -- By class → table of IDs

-- Direct access to well-known objects
scenetree.tod.play = false

-- Object basics
obj:getPosition()        -- Point3F
obj:setPosition(pos)
obj:getClassName()       -- "BeamNGVehicle", "TSStatic", etc.
obj:setHidden(true)
obj:delete()

-- Groups
group:getCount()
group:getObject(i)       -- 0-indexed

SceneTree - Scene Graph Queries

On this page

SceneTree - Scene Graph Queries

On this page