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 )
Signature 
fun addToMap(attribute: Int, value: HashMap<*, *><out <Error class: unknown class>, out <Error class: unknown class>>)
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><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 ()
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.
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><T, 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.
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 )
Signature 
fun setMap(attribute: Int, value: HashMap<*, *><out <Error class: unknown class>, out <Error class: unknown class>>)
Parameters
attribute: Int
value: HashMap<*, *>
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><T, Boolean>, componentTypeID: Int): T?
Parameters
cls: Pair<T, Boolean>
componentTypeID: Int
Returns

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