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 <code>Entity.create()</code> 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

Properties

entityId : Long
[Get]
Extension to get the raw entity ID.
Example: 
val id = entity.entityId
println("Entity ID: $id")
Signature 
val Entity.entityId: Long
exists : Boolean
[Get]
Extension to check if entity exists (has a non-null ID).
Note: This only checks if the ID is non-zero. Use Entity.isValid if you also need to check that the entity is not scheduled for deletion.
Example: 
if (entity.exists) {
    // Entity has a valid ID
}
Signature 
val Entity.exists: Boolean
isNullEntity : Boolean
[Get]
Checks if this entity is the null entity.
The null entity (ID = 0) is used as a placeholder for entity attributes.
Example: 
val parent = transformParent.parent
if (parent.isNullEntity) {
    println("No parent set")
}
Signature 
val Entity.isNullEntity: Boolean
isValid : Boolean
[Get]
Extension to check if entity is valid (non-null ID, not scheduled for deletion).
Example: 
if (entity.isValid) {
    // Safe to operate on entity
}
Signature 
val Entity.isValid: Boolean

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.
modify ( transform )
Modifies a component using a transformation function and auto-saves.
This is useful for functional-style updates where you want to transform the component immutably.
Example: 
entity.modify<Health> { it.copy(current = it.current - 10f) }
Signature 
inline fun <T : ComponentBase> Entity.modify(transform: (T) -> T): Entity
Parameters
transform: Function1
  A function that takes the current component and returns the modified version.
Returns
  This entity instance for chaining.
Throws
RuntimeException
  if the component does not exist for this entity.
modifyIfPresent ( transform )
Modifies a component if it exists using a transformation function.
This is a safe version of Entity.modify that returns false if the component does not exist.
Example: 
val wasModified = entity.modifyIfPresent<Health> {
    it.copy(current = it.current - 10f)
}
Signature 
inline fun <T : ComponentBase> Entity.modifyIfPresent(transform: (T) -> T): Boolean
Parameters
transform: Function1
  A function that takes the current component and returns the modified version.
Returns
Boolean
  True if the component was modified, false if it didn't exist.
raw ( block )
Provides access to lower-level APIs when the DSL is insufficient.
Use this as an escape hatch when you need direct access to the Entity for operations not covered by the DSL.
Example: 
entity.raw { rawEntity ->
    // Direct access to Entity methods
    rawEntity.setComponentData(...)
}
Signature 
inline fun <R> Entity.raw(block: (Entity) -> R): R
Parameters
block: Function1
  A lambda that receives the raw Entity.
Returns
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.
update ( block )
Updates a component using a lambda that receives the current component as the receiver. Automatically calls setComponent() after the lambda executes.
This provides a more ergonomic way to modify components compared to the manual getComponent/modify/setComponent pattern.
Example: 
entity.update<Transform> {
    transform = Pose(Vector3(0f, 1f, 0f))
}
entity.update<Health> {
    current -= 10f
    if (current <= 0f) isDead = true
}
Signature 
inline fun <T : ComponentBase> Entity.update(block: T.() -> Unit): Entity
Parameters
block: Function1
  A lambda with the component as receiver to modify it.
Returns
  This entity instance for chaining.
Throws
RuntimeException
  if the component does not exist for this entity.
update ( block )
Update two components at once with auto-save.
Both components are automatically saved after the block executes.
Example: 
entity.update<Transform, Velocity> { transform, velocity ->
    velocity.y -= 9.8f * deltaTime
    transform.transform = transform.transform.copy(
        t = transform.transform.t + velocity.toVector3() * deltaTime
    )
}
Signature 
inline fun <A : ComponentBase, B : ComponentBase> Entity.update(block: (A, B) -> Unit): Entity
Parameters
block: Function2
  A lambda that receives both components for modification.
Returns
  This entity instance for chaining.
Throws
RuntimeException
  if either component does not exist for this entity.
update ( block )
Update three components at once with auto-save.
All components are automatically saved after the block executes.
Signature 
inline fun <A : ComponentBase, B : ComponentBase, C : ComponentBase> Entity.update(block: (A, B, C) -> Unit): Entity
Parameters
block: Function3
  A lambda that receives all three components for modification.
Returns
  This entity instance for chaining.
Throws
RuntimeException
  if any component does not exist for this entity.
updateIfPresent ( block )
Updates a component if it exists, otherwise does nothing.
This is a safe version of Entity.update that returns false if the component does not exist instead of throwing an exception.
Example: 
val wasUpdated = entity.updateIfPresent<Health> {
    current -= 10f
}
if (!wasUpdated) {
    println("Entity has no Health component")
}
Signature 
inline fun <T : ComponentBase> Entity.updateIfPresent(block: T.() -> Unit): Boolean
Parameters
block: Function1
  A lambda with the component as receiver to modify it.
Returns
Boolean
  True if the component was updated, false if it didn't 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.
with ( block )
Provides scoped read-only access to a component (side-effect only).
Use this when you need to read component data without returning a value. Returns this entity for chaining.
Example: 
entity.with<Health> { health ->
    println("Current HP: ${health.current}/${health.max}")
}
Signature 
inline fun <T : ComponentBase> Entity.with(block: (T) -> Unit): Entity
Parameters
block: Function1
  A lambda that receives the component.
Returns
  This entity for chaining.
Throws
RuntimeException
  if the component does not exist for this entity.
with ( block )
Provides scoped read-only access to a component with a return value.
Use this when you need to extract a value from a component. For side-effect only access, use the Unit-returning overload which doesn't require specifying R.
Example: 
val position = entity.with<Transform, _> { transform ->
    transform.transform.t
}
// Or with full inference:
val position = entity.with { transform: Transform -> transform.transform.t }
Signature 
inline fun <T : ComponentBase, R> Entity.with(block: (T) -> R): R
Parameters
block: Function1
  A lambda that receives the component and returns a value.
Returns
Throws
RuntimeException
  if the component does not exist for this entity.
with ( block )
Access two components at once (side-effect only).
This is useful when you need to work with multiple components together without returning a value. Returns this entity for chaining.
Example: 
entity.with<Transform, Velocity> { transform, velocity ->
    println("Position: ${transform.transform.t}, Velocity: ${velocity.direction}")
}
Signature 
inline fun <A : ComponentBase, B : ComponentBase> Entity.with(block: (A, B) -> Unit): Entity
Parameters
block: Function2
  A lambda that receives both components.
Returns
  This entity for chaining.
Throws
RuntimeException
  if either component does not exist for this entity.
with ( block )
Access two components at once with a return value.
Use this when you need to extract a value from multiple components. For side-effect only access, use the Unit-returning overload which doesn't require specifying R.
Example: 
val distance = entity.with<Transform, Target, _> { transform, target ->
    (transform.transform.t - target.position).length()
}
// Or with full inference:
val distance = entity.with { t: Transform, tgt: Target -> (t.transform.t - tgt.position).length() }
Signature 
inline fun <A : ComponentBase, B : ComponentBase, R> Entity.with(block: (A, B) -> R): R
Parameters
block: Function2
  A lambda that receives both components and returns a value.
Returns
Throws
RuntimeException
  if either component does not exist for this entity.
with ( block )
Access three components at once.
Example: 
entity.with<Transform, Velocity, Physics> { transform, velocity, physics ->
    // Apply physics to velocity, then velocity to transform
}
Signature 
inline fun <A : ComponentBase, B : ComponentBase, C : ComponentBase, R> Entity.with(block: (A, B, C) -> R): R
Parameters
block: Function3
  A lambda that receives all three components and returns a value.
Returns
Throws
RuntimeException
  if any component does not exist for this entity.
with ( block )
Access four components at once.
Example: 
entity.with<Transform, Velocity, Physics, Health> { t, v, p, h ->
    // Work with all four components
}
Signature 
inline fun <A : ComponentBase, B : ComponentBase, C : ComponentBase, D : ComponentBase, R> Entity.with(block: (A, B, C, D) -> R): R
Parameters
block: Function4
  A lambda that receives all four components and returns a value.
Returns
Throws
RuntimeException
  if any component does not exist for this entity.
withOrNull ( block )
Provides scoped read-only access to a component if it exists.
This is a safe version of Entity.with that returns null if the component does not exist.
Example: 
val position = entity.withOrNull<Transform> { transform ->
    transform.transform.t
}
if (position == null) {
    println("Entity has no Transform")
}
Signature 
inline fun <T : ComponentBase, R> Entity.withOrNull(block: (T) -> R): R?
Parameters
block: Function1
  A lambda that receives the component and returns a value.
Returns
withOrNull ( block )
Access two components if both exist, returns null otherwise.
This is a safe version that won't throw if either component is missing.
Example: 
val result = entity.withOrNull<Transform, Velocity> { transform, velocity ->
    transform.transform.t + velocity.direction
}
if (result == null) {
    println("Entity missing Transform or Velocity")
}
Signature 
inline fun <A : ComponentBase, B : ComponentBase, R> Entity.withOrNull(block: (A, B) -> R): R?
Parameters
block: Function2
  A lambda that receives both components and returns a value.
Returns
withOrNull ( block )
Access three components if all exist, returns null otherwise.
Signature 
inline fun <A : ComponentBase, B : ComponentBase, C : ComponentBase, R> Entity.withOrNull(block: (A, B, C) -> R): R?
Parameters
block: Function3
  A lambda that receives all three components and returns a value.
Returns
withOrNull ( block )
Access four components if all exist, returns null otherwise.
Signature 
inline fun <A : ComponentBase, B : ComponentBase, C : ComponentBase, D : ComponentBase, R> Entity.withOrNull(block: (A, B, C, D) -> R): R?
Parameters
block: Function4
  A lambda that receives all four components and returns a value.
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