SceneObject
ClassAn object in the scene hierarchy, containing a Transform and possibly Component.
- Available on all platforms
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
Properties
Methods
- copyComponent
- copySceneObject
- copyWholeHierarchy
- createComponent
- destroy
- getChild
- getChildrenCount
- getComponent
- getComponentInAncestors
- getComponentInDescendants
- getComponents
- getComponentsInAncestors
- getComponentsInDescendants
- getParent
- getTransform
- getTypeName
- hasParent
- isDescendantOf
- isOfType
- isSame
- removeParent
- removeParentPreserveWorldTransform
- setParent
- setParentPreserveWorldTransform
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
readonlychildren: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
readonlyisBeingDestroyed: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
readonlyisEnabledInHierarchy: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
readonlyonDisabled: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
readonlyonEnabled: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
readonlyuniqueIdentifier: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
| Parameter | Type |
|---|---|
component | K |
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
| Parameter | Type |
|---|---|
sceneObject | SceneObject |
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
| Parameter | Type |
|---|---|
sceneObject | SceneObject |
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
| Parameter | Type |
|---|---|
typeName | K |
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
| Parameter | Type |
|---|---|
typeName | TypeName<T> |
Returns
T
destroy()
destroy():
void
Destroys the SceneObject, including all of its Components and children.
The destruction process occurs in two phases:
- All
OnDestroyEventcallbacks fire for the SceneObject and its entire sub-hierarchy - 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
| Parameter | Type |
|---|---|
index | number |
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
| Parameter | Type |
|---|---|
componentType | K |
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
| Parameter | Type |
|---|---|
componentType | TypeName<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, allComponenttypes are considered.onlyEnabled: Iftrue, the search only returnsComponents whereisEnabledInHierarchyis true. This means theComponentitself must be enabled, and itsSceneObjectmust be enabled in the hierarchy. Defaults tofalse.includeSelf: Iftrue, the search will include theSceneObjectthis is called on. Defaults tofalse.maxDepth: Limits how many levels up to search. UseInfinityfor an unlimited search depth. Defaults toInfinity.
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
| Parameter | Type |
|---|---|
componentType | K |
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, allComponenttypes are considered.onlyEnabled: Iftrue, the search only returnsComponents whereisEnabledInHierarchyis true. This means theComponentitself must be enabled, and itsSceneObjectmust be enabled in the hierarchy. Defaults tofalse.includeSelf: Iftrue, the search will include theSceneObjectthis is called on. Defaults tofalse.maxDepth: Limits how many levels up to search. UseInfinityfor an unlimited search depth. Defaults toInfinity.
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
| Parameter | Type |
|---|---|
componentType | TypeName<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, allComponenttypes are considered.onlyEnabled: Iftrue, the search only returnsComponents whereisEnabledInHierarchyis true. This means disabledSceneObjects are skipped during traversal, and both theComponentand itsSceneObjectmust be enabled in the hierarchy. Defaults tofalse.includeSelf: Iftrue, the search will include theSceneObjectthis is called on. Defaults tofalse.maxDepth: Limits how many levels down to search. UseInfinityfor an unlimited search depth. Defaults toInfinity.
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
| Parameter | Type |
|---|---|
componentType | K |
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, allComponenttypes are considered.onlyEnabled: Iftrue, the search only returnsComponents whereisEnabledInHierarchyis true. This means disabledSceneObjects are skipped during traversal, and both theComponentand itsSceneObjectmust be enabled in the hierarchy. Defaults tofalse.includeSelf: Iftrue, the search will include theSceneObjectthis is called on. Defaults tofalse.maxDepth: Limits how many levels down to search. UseInfinityfor an unlimited search depth. Defaults toInfinity.
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
| Parameter | Type |
|---|---|
componentType | TypeName<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
| Parameter | Type |
|---|---|
componentType | K |
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
| Parameter | Type |
|---|---|
componentType | TypeName<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, allComponenttypes are considered.onlyEnabled: Iftrue, the search only returnsComponents whereisEnabledInHierarchyis true. This means theComponentitself must be enabled, and itsSceneObjectmust be enabled in the hierarchy. Defaults tofalse.includeSelf: Iftrue, the search will include theSceneObjectthis is called on. Defaults tofalse.maxDepth: Limits how many levels up to search. UseInfinityfor an unlimited search depth. Defaults toInfinity.
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
| Parameter | Type |
|---|---|
componentType | K |
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, allComponenttypes are considered.onlyEnabled: Iftrue, the search only returnsComponents whereisEnabledInHierarchyis true. This means theComponentitself must be enabled, and itsSceneObjectmust be enabled in the hierarchy. Defaults tofalse.includeSelf: Iftrue, the search will include theSceneObjectthis is called on. Defaults tofalse.maxDepth: Limits how many levels up to search. UseInfinityfor an unlimited search depth. Defaults toInfinity.
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
| Parameter | Type |
|---|---|
componentType | TypeName<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, allComponenttypes are considered.onlyEnabled: Iftrue, the search only returnsComponents whereisEnabledInHierarchyis true. This means disabledSceneObjects are skipped during traversal, and both theComponentand itsSceneObjectmust be enabled in the hierarchy. Defaults tofalse.includeSelf: Iftrue, the search will include theSceneObjectthis is called on. Defaults tofalse.maxDepth: Limits how many levels down to search. UseInfinityfor an unlimited search depth. Defaults toInfinity.
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
| Parameter | Type |
|---|---|
componentType | K |
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, allComponenttypes are considered.onlyEnabled: Iftrue, the search only returnsComponents whereisEnabledInHierarchyis true. This means disabledSceneObjects are skipped during traversal, and both theComponentand itsSceneObjectmust be enabled in the hierarchy. Defaults tofalse.includeSelf: Iftrue, the search will include theSceneObjectthis is called on. Defaults tofalse.maxDepth: Limits how many levels down to search. UseInfinityfor an unlimited search depth. Defaults toInfinity.
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
| Parameter | Type |
|---|---|
componentType | TypeName<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
getTypeName()
staticgetTypeName():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
| Parameter | Type |
|---|---|
potentialAncestor | SceneObject |
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
| Parameter | Type |
|---|---|
type | string |
Returns
boolean
Inherited from
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
| Parameter | Type |
|---|---|
other | ScriptObject |
Returns
boolean
Inherited from
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
| Parameter | Type |
|---|---|
newParent? | SceneObject |
Returns
void
setParentPreserveWorldTransform()
setParentPreserveWorldTransform(
newParent?):void
Changes the parent of the SceneObject without altering its world position, rotation, or scale.
Parameters
| Parameter | Type |
|---|---|
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);
}