API reference
API reference
Select your platform
No SDKs available
No versions available

Entity Class

Modifiers: final
Represents an entity in the spatial data model. Learn more about our Entity-Component-System (ECS) architecture here.
It is recommended to use the Entity.create() static method to create new entities instead of the Entity constructors

Signature

class Entity

Constructors

Entity ( dataModel , id , components )
Constructor for creating an entity with a specified data model, ID, and variable number of components.
Signature 
constructor(dataModel: DataModel, id: Long, vararg components: ComponentBase)
Parameters
dataModel: DataModel
  The data model to associate with this entity.
id: Long
  The unique identifier for this entity.
components: ComponentBase
  The variable number of components to associate with this entity.
Returns

Functions

addName ( name )
Signature 
fun Entity.addName(name: String): Entity
Parameters
name: String
Returns
addToMap ( attribute , value )
Parameters
attribute: Int
value: HashMap<*, *>
childrenOfAttrId ( typeID )
childrenOfTypeId returns a sequence of entities that are children of this entity's attribute.
Signature 
fun childrenOfAttrId(typeID: Int): Sequence<Entity>
Parameters
typeID: Int
  The type ID of the attribute to search for.
Returns
Sequence<Entity>
  A sequence of entities that are children of this entity's attribute.
destroy ()
Destroys this entity.
This method will remove the entity from the data model and free up any resources associated with it.
Signature 
fun destroy()
destroyWithChildren ()
Recursively destroys this entity and all of its children in the entity hierarchy.
This function traverses the entity tree using TransformParent relationships and destroys all child entities before destroying the parent entity itself.
Signature 
fun Entity.destroyWithChildren()
equals ( o )
Checks if this entity is equal to another object. The object is equal to this entity iff the object is an Entity and has the same ID as this entity.
Signature 
open operator override fun equals(o: Any?): Boolean
Parameters
o: Any?
Returns
Boolean
getComponent ( recycler )
gets the specified component with the most up to date attribute values for this entity. If the component does not exist for this entity, a RuntimeException will be thrown.
Example: 
val transform = entity.getComponent<Transform>()
Signature 
inline fun <T : ComponentBase> getComponent(recycler: ComponentRecyler? = null): T
Parameters
recycler: ComponentRecyler?
Returns
  The component instance of type T.
Throws
RuntimeException
  if the component does not exist for this entity.
getComponentsDebugString ()
Returns a debug string listing all components attached to this entity and their values.
This method iterates through all registered component types and checks if this entity has each one. For components that exist, it reads the component data and includes its toString() output.
Note: This is a relatively expensive operation as it queries all registered component types.
Signature 
fun getComponentsDebugString(): String
Returns
String
  A formatted string containing all components and their values.
hasComponent ()
Signature 
inline fun <T : ComponentBase> hasComponent(): Boolean
Returns
Boolean
isLocal ()
Returns whether the entity is local or not.
Signature 
fun isLocal(): Boolean
Returns
Boolean
  True if the entity is local, false otherwise.
markComponentChanged ()
Marks a component as "changed" without setting new component data.
This is useful in rare cases where you want the component to be considered "changed" for change detection purposes, even when the actual component data hasn't been modified. This will trigger component change listeners and queries that look for changed components.
Example: 
// Force the Panel component to be marked as changed
entity.markComponentChanged<Panel>()
Signature 
inline fun <T : ComponentBase> markComponentChanged(): Entity
Returns
  This entity instance.
Throws
RuntimeException
  if the component does not exist for this entity.
readIntoComponent ( cls )
Signature 
fun <T : ComponentBase> readIntoComponent(cls: Pair<T, Boolean>, Boolean>): T
Parameters
cls: Pair<T, Boolean>
Returns
registerEventListener ( eventName , listener )
Registers an event listener for a specific event.
Signature 
fun <T : EventArgs> registerEventListener(eventName: String, listener: (entity: Entity, eventArgs: T) -> Unit): Entity
Parameters
eventName: String
  The name of the event to listen for.
listener: Function2
  The function to call when the event is triggered.
Returns
  This entity instance.
removeComponent ()
Removes a component from this entity.
This method removes the specified component and all its associated attributes from this entity. After removal, the entity will no longer have this component, and queries that filter by this component will no longer match this entity.
Example: 
// Remove the Grabbable component from an entity
entity.removeComponent<Grabbable>()
Signature 
inline fun <T : ComponentBase> removeComponent(): Entity
Returns
  This entity instance.
Throws
RuntimeException
  if the component does not exist for this entity.
requireComponent ( errorMessage )
Gets a required component with a custom error message.
This is a generic utility for scenarios where a component is absolutely required and missing it should result in a detailed error. Unlike tryGetComponent which returns null, this method throws a RuntimeException with your custom error message.
Example: 
val transform = entity.requireComponent<Transform>(
    "Transform required for physics simulation"
)
Signature 
inline fun <T : ComponentBase> requireComponent(errorMessage: String): T
Parameters
errorMessage: String
  Custom error message to use if component is missing.
Returns
  The component instance of type T.
Throws
RuntimeException
  if the component does not exist for this entity.
setComponent ( c )
Sets a single component for this entity.
Signature 
fun setComponent(c: ComponentBase): Entity
Parameters
  The component to set.
Returns
  This entity instance.
setComponents ( components )
Sets the components for this entity.
Signature 
fun setComponents(components: List<ComponentBase>): Entity
Parameters
components: List
  The list of components to set.
Returns
  This entity instance.
setComponents ( components )
Sets the components for this entity.
Signature 
fun setComponents(vararg components: ComponentBase): Entity
Parameters
components: ComponentBase
  The variable number of components to set.
Returns
  This entity instance.
setMap ( attribute , value )
Parameters
attribute: Int
value: HashMap<*, *>
toString ()
Returns a string representation of this entity including its ID and all components.
When EntityDebugInfo.captureCreationCallstack is enabled, this also includes the callstack from when the entity was created and the time alive since creation.
Example output: 
Entity(id=42, components=[
  Component{name: Transform, type: 123, {pose=...}},
  Component{name: Mesh, type: 456, {uri=...}}
])
Signature 
open override fun toString(): String
Returns
String
  A string representation of this entity with all its components. When EntityDebugInfo.includeComponentsInToString is enabled, this also includes all components attached to this entity and their current values.
tryGetComponent ( recycler )
A safe way to get a component with the most up to date attribute values for this entity. If the component does not exist for this entity, null will be returned.
Example: 
val transform = entity.tryGetComponent<Transform>()
Signature 
inline fun <T : ComponentBase> tryGetComponent(recycler: ComponentRecyler? = null): T?
Parameters
recycler: ComponentRecyler?
Returns
  The component instance of type T or null if the component does not exist for this entity
tryReadIntoComponent ( cls , componentTypeID )
Signature 
fun <T : ComponentBase> tryReadIntoComponent(cls: Pair<T, Boolean>, Boolean>, componentTypeID: Int): T?
Parameters
cls: Pair<T, Boolean>
componentTypeID: Int
Returns
tryRemoveComponent ()
Removes a component from this entity if it exists.
This method is a safe version of Entity.removeComponent that returns false if the component does not exist instead of throwing an exception.
Example: 
// Try to remove the Grabbable component, returns false if not present
val wasRemoved = entity.tryRemoveComponent<Grabbable>()
Signature 
inline fun <T : ComponentBase> tryRemoveComponent(): Boolean
Returns
Boolean
  True if the component was removed, false if the component did not exist.
willBeDeleted ()
Checks if this entity will be deleted in the next frame.
Returns true if destroy() has been called on this entity in the current frame, but the entity hasn't been fully removed yet. The entity will be inaccessible starting in the next frame.
Signature 
fun willBeDeleted(): Boolean
Returns
Boolean
  True if the entity is scheduled for deletion, false otherwise.

Companion Object

Companion Object Functions

create ()
Creates a new entity with the default data model.
Signature 
fun create(): Entity
Returns
  A new entity instance.
create ( dm )
Creates a new entity with the specified data model.
Signature 
fun create(dm: DataModel): Entity
Parameters
  The data model to use for the new entity.
Returns
  A new entity instance.
create ( component )
Creates a new entity with the specified component.
Signature 
fun create(component: ComponentBase): Entity
Parameters
component: ComponentBase
  The component to add to the new entity.
Returns
  A new entity instance.
create ( components )
Creates a new entity with the specified list of components.
Signature 
fun create(components: List<ComponentBase>): Entity
Parameters
components: List
  The list of components to add to the new entity.
Returns
  A new entity instance.
create ( components )
Creates a new entity with the specified variable number of components.
Signature 
fun create(vararg components: ComponentBase): Entity
Parameters
components: ComponentBase
  The variable number of components to add to the new entity.
Returns
  A new entity instance.
createPanelEntity ( panelId , transform , components )
Signature 
fun Entity.Companion.createPanelEntity(panelId: Int, transform: Transform, vararg components: ComponentBase): Entity
Parameters
panelId: Int
transform: Transform
components: ComponentBase
Returns
createPanelEntity ( entityId , panelId , transform , components )
Signature 
fun Entity.Companion.createPanelEntity(entityId: Int, panelId: Int, transform: Transform, vararg components: ComponentBase): Entity
Parameters
entityId: Int
panelId: Int
transform: Transform
components: ComponentBase
Returns
fromBox ( length , transform , material , components )
Signature 
fun Entity.Companion.fromBox(length: Float, transform: Transform, material: Material? = null, vararg components: ComponentBase): Entity
Parameters
length: Float
transform: Transform
material: Material?
components: ComponentBase
Returns
fromGLB ( mesh , transform , components )
Signature 
fun Entity.Companion.fromGLB(mesh: Mesh, transform: Transform, vararg components: ComponentBase): Entity
Parameters
mesh: Mesh
transform: Transform
components: ComponentBase
Returns
fromMeshAndMaterial ( mesh , material , transform , components )
Signature 
fun Entity.Companion.fromMeshAndMaterial(mesh: Mesh, material: Material, transform: Transform, vararg components: ComponentBase): Entity
Parameters
mesh: Mesh
material: Material
transform: Transform
components: ComponentBase
Returns
fromPanelRegistry ( registry , transform , components )
Signature 
fun Entity.Companion.fromPanelRegistry(registry: PanelRegistration, transform: Transform, vararg components: ComponentBase): Entity
Parameters
transform: Transform
components: ComponentBase
Returns
fromSphere ( length , transform , material , components )
Signature 
fun Entity.Companion.fromSphere(length: Float, transform: Transform, material: Material? = null, vararg components: ComponentBase): Entity
Parameters
length: Float
transform: Transform
material: Material?
components: ComponentBase
Returns
nullEntity ()
Creates a null entity. You cannot use this entity to set or get components. The nullEntity is generally used as a placeholder for Entity attributes.
Here is an example using TransformParent: 
val transformParent = myEntity.getComponent<TransformParent>()
transformParent.parent = Entity.nullEntity() // This makes it as if no TransformParent is set.
myEntity.setComponent(transformParent)
Signature 
fun nullEntity(): Entity
Returns
  A null entity instance.
Did you find this page helpful?
Nav Logo
Virtual reality / Meta Horizon
Virtual reality / Meta Horizon
Virtual reality / Meta Horizon
English (US)
© 2026 Meta