Skip to main content

SceneObject

Class

An object in the scene hierarchy, containing a Transform and possibly Component.

  • Available on all platforms
Platform details: Snapchat, SPECS, Camera Kit Web, Camera Kit Mobile fully supported.

Platform details

  • Snapchat — Fully supported.

  • SPECS — Fully supported.

  • Camera Kit Web — Fully supported.

  • Camera Kit Mobile — Fully supported.

An object in the scene hierarchy, containing a Transform and possibly Component. A script can access the SceneObject holding it through the method script.getSceneObject().

There is a global limit of 100,000 SceneObjects. There is no limit on how many children a given SceneObject can have, but the hierarchy depth cannot exceed 256 levels.

Index

Example

// Look for a MaterialMeshVisual on this SceneObject
var sceneObj = script.getSceneObject();
var meshVisual = sceneObj.getComponent(MaterialMeshVisual.getTypeName());
if(meshVisual)
{
// ...
}
// Rename each child SceneObject
var sceneObj = script.getSceneObject();
for(var i=0; i<sceneObj.getChildrenCount(); i++)
{
var child = sceneObj.getChild(i);
var newName = i + "_" + child.name;
child.name = newName;
print(child.name);
}

Extends

Properties

children

readonly children: SceneObject[]

Get an array of the scene object's children.


enabled

enabled: boolean

Whether the SceneObject, including its components and children, is enabled or disabled.

Default Value

true

isBeingDestroyed

readonly isBeingDestroyed: boolean

Returns true if this SceneObject is currently being destroyed. Becomes true as soon as destruction begins via SceneObject#destroy, and propagates to all descendants and attached Components before any OnDestroyEvent callbacks fire.

Since

Lens Scripting Version 364

Example

if (!script.getSceneObject().isBeingDestroyed) {
// SceneObject is still fully alive
}

isEnabledInHierarchy

readonly isEnabledInHierarchy: boolean

Returns true if this SceneObject and all of its parents are enabled.


layer

layer: LayerSet

Gets or sets the LayerSet of layers this SceneObject belongs to. This is used to determine which Camera will render the SceneObject.

Default Value

LayerSet.fromNumber(0)

name

name: string

The name of the SceneObject.

Default Value

""

onDisabled

readonly onDisabled: event0<void>

An event that will trigger when a SceneObject goes from enabled in the hiearchy to disabled in the hiearchy.

Since

Lens Scripting Version 158


onEnabled

readonly onEnabled: event0<void>

An event that will trigger when a SceneObject goes from disabled in the hiearchy to enabled in the hiearchy.

Since

Lens Scripting Version 158


uniqueIdentifier

readonly uniqueIdentifier: string

Since

Lens Scripting Version 176

Inherited from

SerializableWithUID.uniqueIdentifier

Methods

copyComponent()

copyComponent<K>(component): K

Copies component and adds it to the SceneObject, then returns it.

Type Parameters

Type Parameter
K extends Component

Parameters

ParameterType
componentK

Returns

K


copySceneObject()

copySceneObject(sceneObject): SceneObject

Creates a shallow copy of the passed in sceneObject (not including its hierarchy), and parents it to this SceneObject.

Parameters

ParameterType
sceneObjectSceneObject

Returns

SceneObject


copyWholeHierarchy()

copyWholeHierarchy(sceneObject): SceneObject

Creates a deep copy of the passed in sceneObject (including its hierarchy), and parents it to this SceneObject.

Parameters

ParameterType
sceneObjectSceneObject

Returns

SceneObject


createComponent()

Call Signature

createComponent<K>(typeName): ComponentNameMap[K]

Adds a new component of type typeName to the SceneObject.

Type Parameters
Type Parameter
K extends keyof ComponentNameMap
Parameters
ParameterType
typeNameK
Returns

ComponentNameMap[K]

Call Signature

createComponent<T>(typeName): T

Adds a new component of type typeName to the SceneObject.

Type Parameters
Type Parameter
T extends Component
Parameters
ParameterType
typeNameTypeName<T>
Returns

T


destroy()

destroy(): void

Destroys the SceneObject, including all of its Components and children.

The destruction process occurs in two phases:

  1. All OnDestroyEvent callbacks fire for the SceneObject and its entire sub-hierarchy
  2. The SceneObjects and Components are actually destroyed and removed from the scene

This guarantees that during OnDestroyEvent callbacks, the full hierarchy is still intact and accessible.

Important: If destroy is called on a parent or child object during an OnDestroyEvent callback (for example, calling parent.destroy() from a child's OnDestroyEvent), the destruction will be queued and processed after the current destruction completes. This ensures all OnDestroyEvent callbacks fire before any objects are actually removed.

Returns

void


getChild()

getChild(index): SceneObject

Returns this SceneObject's child at index index.

Parameters

ParameterType
indexnumber

Returns

SceneObject


getChildrenCount()

getChildrenCount(): number

Returns the number of children the SceneObject has.

Returns

number


getComponent()

Call Signature

getComponent<K>(componentType): ComponentNameMap[K]

Returns the first attached Component with type matching or deriving from componentType.

Type Parameters
Type Parameter
K extends keyof ComponentNameMap
Parameters
ParameterType
componentTypeK
Returns

ComponentNameMap[K]

Call Signature

getComponent<T>(componentType): T

Returns the first attached Component with type matching or deriving from componentType.

Type Parameters
Type Parameter
T extends Component
Parameters
ParameterType
componentTypeTypeName<T>
Returns

T


getComponentInAncestors()

Call Signature

getComponentInAncestors<K>(componentType, onlyEnabled?, includeSelf?, maxDepth?): ComponentNameMap[K]

Returns the first Component with type matching or deriving from componentType found in the ancestors of this object. The search stops immediately upon finding a match.

Arguments:

  • componentType: If an empty string, all Component types are considered.
  • onlyEnabled: If true, the search only returns Components where isEnabledInHierarchy is true. This means the Component itself must be enabled, and its SceneObject must be enabled in the hierarchy. Defaults to false.
  • includeSelf: If true, the search will include the SceneObject this is called on. Defaults to false.
  • maxDepth: Limits how many levels up to search. Use Infinity for an unlimited search depth. Defaults to Infinity.

The search begins at the immediate parent, or at self if includeSelf is true. Returns null if no matching Component is found.

Note: Hierarchy searches can be very expensive. Be mindful of what, and how often you're searching.

Type Parameters
Type Parameter
K extends keyof ComponentNameMap
Parameters
ParameterType
componentTypeK
onlyEnabled?boolean
includeSelf?boolean
maxDepth?number
Returns

ComponentNameMap[K]

Example
// Find the first Camera in the ancestor hierarchy.
var camera = sceneObject.getComponentInAncestors(Camera.getTypeName());

// Search this SceneObject and its ancestors for an enabled RenderMeshVisual.
var visual = sceneObject.getComponentInAncestors(RenderMeshVisual.getTypeName(), true, true);

// Search only the direct parent, including disabled components, excluding this SceneObject.
var camera = sceneObject.getComponentInAncestors(Camera.getTypeName(), false, false, 1);

Call Signature

getComponentInAncestors<T>(componentType, onlyEnabled?, includeSelf?, maxDepth?): T

Returns the first Component with type matching or deriving from componentType found in the ancestors of this object. The search stops immediately upon finding a match.

Arguments:

  • componentType: If an empty string, all Component types are considered.
  • onlyEnabled: If true, the search only returns Components where isEnabledInHierarchy is true. This means the Component itself must be enabled, and its SceneObject must be enabled in the hierarchy. Defaults to false.
  • includeSelf: If true, the search will include the SceneObject this is called on. Defaults to false.
  • maxDepth: Limits how many levels up to search. Use Infinity for an unlimited search depth. Defaults to Infinity.

The search begins at the immediate parent, or at self if includeSelf is true. Returns null if no matching Component is found.

Note: Hierarchy searches can be very expensive. Be mindful of what, and how often you're searching.

Type Parameters
Type Parameter
T extends Component
Parameters
ParameterType
componentTypeTypeName<T>
onlyEnabled?boolean
includeSelf?boolean
maxDepth?number
Returns

T

Example
// Find the first Camera in the ancestor hierarchy.
var camera = sceneObject.getComponentInAncestors(Camera.getTypeName());

// Search this SceneObject and its ancestors for an enabled RenderMeshVisual.
var visual = sceneObject.getComponentInAncestors(RenderMeshVisual.getTypeName(), true, true);

// Search only the direct parent, including disabled components, excluding this SceneObject.
var camera = sceneObject.getComponentInAncestors(Camera.getTypeName(), false, false, 1);

getComponentInDescendants()

Call Signature

getComponentInDescendants<K>(componentType, onlyEnabled?, includeSelf?, maxDepth?): ComponentNameMap[K]

Returns the first Component with type matching or deriving from componentType found in the descendants of this object. The search stops immediately upon finding a match.

Arguments:

  • componentType: If an empty string, all Component types are considered.
  • onlyEnabled: If true, the search only returns Components where isEnabledInHierarchy is true. This means disabled SceneObjects are skipped during traversal, and both the Component and its SceneObject must be enabled in the hierarchy. Defaults to false.
  • includeSelf: If true, the search will include the SceneObject this is called on. Defaults to false.
  • maxDepth: Limits how many levels down to search. Use Infinity for an unlimited search depth. Defaults to Infinity.

The search begins at the immediate children, or at self if includeSelf is true, and uses Breadth-First Search to find the nearest match. Returns null if no matching Component is found.

Note: Hierarchy searches can be very expensive. Be mindful of what, and how often you're searching.

Type Parameters
Type Parameter
K extends keyof ComponentNameMap
Parameters
ParameterType
componentTypeK
onlyEnabled?boolean
includeSelf?boolean
maxDepth?number
Returns

ComponentNameMap[K]

Example
// Find the first RenderMeshVisual in the descendant hierarchy.
var visual = sceneObject.getComponentInDescendants(RenderMeshVisual.getTypeName());

// Search this SceneObject and its descendants for an enabled Camera.
var camera = sceneObject.getComponentInDescendants(Camera.getTypeName(), true, true);

// Search only immediate children, including disabled components, excluding this SceneObject.
var visual = sceneObject.getComponentInDescendants(RenderMeshVisual.getTypeName(), false, false, 1);

Call Signature

getComponentInDescendants<T>(componentType, onlyEnabled?, includeSelf?, maxDepth?): T

Returns the first Component with type matching or deriving from componentType found in the descendants of this object. The search stops immediately upon finding a match.

Arguments:

  • componentType: If an empty string, all Component types are considered.
  • onlyEnabled: If true, the search only returns Components where isEnabledInHierarchy is true. This means disabled SceneObjects are skipped during traversal, and both the Component and its SceneObject must be enabled in the hierarchy. Defaults to false.
  • includeSelf: If true, the search will include the SceneObject this is called on. Defaults to false.
  • maxDepth: Limits how many levels down to search. Use Infinity for an unlimited search depth. Defaults to Infinity.

The search begins at the immediate children, or at self if includeSelf is true, and uses Breadth-First Search to find the nearest match. Returns null if no matching Component is found.

Note: Hierarchy searches can be very expensive. Be mindful of what, and how often you're searching.

Type Parameters
Type Parameter
T extends Component
Parameters
ParameterType
componentTypeTypeName<T>
onlyEnabled?boolean
includeSelf?boolean
maxDepth?number
Returns

T

Example
// Find the first RenderMeshVisual in the descendant hierarchy.
var visual = sceneObject.getComponentInDescendants(RenderMeshVisual.getTypeName());

// Search this SceneObject and its descendants for an enabled Camera.
var camera = sceneObject.getComponentInDescendants(Camera.getTypeName(), true, true);

// Search only immediate children, including disabled components, excluding this SceneObject.
var visual = sceneObject.getComponentInDescendants(RenderMeshVisual.getTypeName(), false, false, 1);

getComponents()

Call Signature

getComponents<K>(componentType): ComponentNameMap[K][]

Returns a list of attached components with types matching or deriving from componentType.

Type Parameters
Type Parameter
K extends keyof ComponentNameMap
Parameters
ParameterType
componentTypeK
Returns

ComponentNameMap[K][]

Call Signature

getComponents<T>(componentType): T[]

Returns a list of attached components with types matching or deriving from componentType.

Type Parameters
Type Parameter
T extends Component
Parameters
ParameterType
componentTypeTypeName<T>
Returns

T[]


getComponentsInAncestors()

Call Signature

getComponentsInAncestors<K>(componentType, onlyEnabled?, includeSelf?, maxDepth?): ComponentNameMap[K][]

Returns an array of all Components with type matching or deriving from componentType found in the ancestors of this object. This search does not stop at the first match.

Arguments:

  • componentType: If an empty string, all Component types are considered.
  • onlyEnabled: If true, the search only returns Components where isEnabledInHierarchy is true. This means the Component itself must be enabled, and its SceneObject must be enabled in the hierarchy. Defaults to false.
  • includeSelf: If true, the search will include the SceneObject this is called on. Defaults to false.
  • maxDepth: Limits how many levels up to search. Use Infinity for an unlimited search depth. Defaults to Infinity.

The search begins at the immediate parent, or at self if includeSelf is true. Returns an empty array if no matching Components are found.

Note: Hierarchy searches can be very expensive. Be mindful of what, and how often you're searching.

Type Parameters
Type Parameter
K extends keyof ComponentNameMap
Parameters
ParameterType
componentTypeK
onlyEnabled?boolean
includeSelf?boolean
maxDepth?number
Returns

ComponentNameMap[K][]

Example
// Collect all Cameras from ancestor hierarchy.
var cameras = sceneObject.getComponentsInAncestors(Camera.getTypeName());

// Search this SceneObject and its ancestors for all enabled RenderMeshVisuals.
var visuals = sceneObject.getComponentsInAncestors(RenderMeshVisual.getTypeName(), true, true);

// Search only the direct parent, including disabled, excluding this SceneObject.
var cameras = sceneObject.getComponentsInAncestors(Camera.getTypeName(), false, false, 1);

Call Signature

getComponentsInAncestors<T>(componentType, onlyEnabled?, includeSelf?, maxDepth?): T[]

Returns an array of all Components with type matching or deriving from componentType found in the ancestors of this object. This search does not stop at the first match.

Arguments:

  • componentType: If an empty string, all Component types are considered.
  • onlyEnabled: If true, the search only returns Components where isEnabledInHierarchy is true. This means the Component itself must be enabled, and its SceneObject must be enabled in the hierarchy. Defaults to false.
  • includeSelf: If true, the search will include the SceneObject this is called on. Defaults to false.
  • maxDepth: Limits how many levels up to search. Use Infinity for an unlimited search depth. Defaults to Infinity.

The search begins at the immediate parent, or at self if includeSelf is true. Returns an empty array if no matching Components are found.

Note: Hierarchy searches can be very expensive. Be mindful of what, and how often you're searching.

Type Parameters
Type Parameter
T extends Component
Parameters
ParameterType
componentTypeTypeName<T>
onlyEnabled?boolean
includeSelf?boolean
maxDepth?number
Returns

T[]

Example
// Collect all Cameras from ancestor hierarchy.
var cameras = sceneObject.getComponentsInAncestors(Camera.getTypeName());

// Search this SceneObject and its ancestors for all enabled RenderMeshVisuals.
var visuals = sceneObject.getComponentsInAncestors(RenderMeshVisual.getTypeName(), true, true);

// Search only the direct parent, including disabled, excluding this SceneObject.
var cameras = sceneObject.getComponentsInAncestors(Camera.getTypeName(), false, false, 1);

getComponentsInDescendants()

Call Signature

getComponentsInDescendants<K>(componentType, onlyEnabled?, includeSelf?, maxDepth?): ComponentNameMap[K][]

Returns an array of all Components with type matching or deriving from componentType found in the descendants of this object. This search does not stop at the first match. Restrict maxDepth to minimize performance cost.

Arguments:

  • componentType: If an empty string, all Component types are considered.
  • onlyEnabled: If true, the search only returns Components where isEnabledInHierarchy is true. This means disabled SceneObjects are skipped during traversal, and both the Component and its SceneObject must be enabled in the hierarchy. Defaults to false.
  • includeSelf: If true, the search will include the SceneObject this is called on. Defaults to false.
  • maxDepth: Limits how many levels down to search. Use Infinity for an unlimited search depth. Defaults to Infinity.

The search begins at the immediate children, or at self if includeSelf is true, and uses Breadth-First Search. Returns an empty array if no matching Components are found.

Note: Hierarchy searches can be very expensive. Be mindful of what, and how often you're searching.

Type Parameters
Type Parameter
K extends keyof ComponentNameMap
Parameters
ParameterType
componentTypeK
onlyEnabled?boolean
includeSelf?boolean
maxDepth?number
Returns

ComponentNameMap[K][]

Example
// Collect all RenderMeshVisuals in the descendant hierarchy.
var visuals = sceneObject.getComponentsInDescendants(RenderMeshVisual.getTypeName());

// Search this SceneObject and its descendants for all enabled Cameras.
var cameras = sceneObject.getComponentsInDescendants(Camera.getTypeName(), true, true);

// Search only immediate children, including disabled components, excluding this SceneObject.
var visuals = sceneObject.getComponentsInDescendants(RenderMeshVisual.getTypeName(), false, false, 1);

Call Signature

getComponentsInDescendants<T>(componentType, onlyEnabled?, includeSelf?, maxDepth?): T[]

Returns an array of all Components with type matching or deriving from componentType found in the descendants of this object. This search does not stop at the first match. Restrict maxDepth to minimize performance cost.

Arguments:

  • componentType: If an empty string, all Component types are considered.
  • onlyEnabled: If true, the search only returns Components where isEnabledInHierarchy is true. This means disabled SceneObjects are skipped during traversal, and both the Component and its SceneObject must be enabled in the hierarchy. Defaults to false.
  • includeSelf: If true, the search will include the SceneObject this is called on. Defaults to false.
  • maxDepth: Limits how many levels down to search. Use Infinity for an unlimited search depth. Defaults to Infinity.

The search begins at the immediate children, or at self if includeSelf is true, and uses Breadth-First Search. Returns an empty array if no matching Components are found.

Note: Hierarchy searches can be very expensive. Be mindful of what, and how often you're searching.

Type Parameters
Type Parameter
T extends Component
Parameters
ParameterType
componentTypeTypeName<T>
onlyEnabled?boolean
includeSelf?boolean
maxDepth?number
Returns

T[]

Example
// Collect all RenderMeshVisuals in the descendant hierarchy.
var visuals = sceneObject.getComponentsInDescendants(RenderMeshVisual.getTypeName());

// Search this SceneObject and its descendants for all enabled Cameras.
var cameras = sceneObject.getComponentsInDescendants(Camera.getTypeName(), true, true);

// Search only immediate children, including disabled components, excluding this SceneObject.
var visuals = sceneObject.getComponentsInDescendants(RenderMeshVisual.getTypeName(), false, false, 1);

getParent()

getParent(): SceneObject

Returns the SceneObject's parent in the hierarchy, or null if there isn't one.

Returns

SceneObject


getTransform()

getTransform(): Transform

Returns the Transform attached to the SceneObject.

Returns

Transform


getTypeName()

static getTypeName(): TypeName<SceneObject>

Returns the fully-qualified JavaScript type name for this class (for example, "Component.Camera"). This is a static accessor (no instance required) and returns the same value as the instance getTypeName().

Returns

TypeName<SceneObject>

Overrides

SerializableWithUID.getTypeName


getTypeName()

getTypeName(): string

Returns the name of this object's type.

Returns

string

Inherited from

SerializableWithUID.getTypeName


hasParent()

hasParent(): boolean

Returns whether the SceneObject has a parent in the scene hierarchy.

Returns

boolean


isDescendantOf()

isDescendantOf(potentialAncestor): boolean

Returns true if this SceneObject is a descendant (child, grandchild, etc.) of potentialAncestor. Returns false otherwise.

Note: Hierarchy searches can be very expensive. Be mindful of what, and how often you're searching.

Parameters

ParameterType
potentialAncestorSceneObject

Returns

boolean

Since

Lens Scripting Version 346


isOfType()

isOfType(type): boolean

Returns true if the object matches or derives from the passed in type.

Parameters

ParameterType
typestring

Returns

boolean

Inherited from

SerializableWithUID.isOfType


isSame()

isSame(other): boolean

Returns true if this object is the same as other. Useful for checking if two references point to the same thing.

Parameters

ParameterType
otherScriptObject

Returns

boolean

Inherited from

SerializableWithUID.isSame


removeParent()

removeParent(): void

Unparents the SceneObject in the hierarchy, making it an orphan.

Returns

void


removeParentPreserveWorldTransform()

removeParentPreserveWorldTransform(): void

Unparents the SceneObject without altering its world position, rotation, or scale.

Returns

void

Since

Lens Scripting Version 354


setParent()

setParent(newParent?): void

Sets the SceneObject's parent to newParent in the scene hierarchy.

Parameters

ParameterType
newParent?SceneObject

Returns

void


setParentPreserveWorldTransform()

setParentPreserveWorldTransform(newParent?): void

Changes the parent of the SceneObject without altering its world position, rotation, or scale.

Parameters

ParameterType
newParent?SceneObject

Returns

void

Example

// Look for a MaterialMeshVisual on this SceneObject
var sceneObj = script.getSceneObject();
var meshVisual = sceneObj.getComponent(MaterialMeshVisual.getTypeName());
if(meshVisual)
{
// ...
}
// Rename each child SceneObject
var sceneObj = script.getSceneObject();
for(var i=0; i<sceneObj.getChildrenCount(); i++)
{
var child = sceneObj.getChild(i);
var newName = i + "_" + child.name;
child.name = newName;
print(child.name);
}