API reference
Entity Class
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 id: Long
The unique identifier for this entity.
Returns Entity |
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 |
Methods
addName
(
name
)
| |
addToMap
(
attribute
, value
)
| Parameters attribute: Intvalue: 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?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 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.
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 Entity |
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.
|
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 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.
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 |
setComponents
(
components
)
|
Sets the components for this entity.
Signature
fun setComponents(components: List<ComponentBase>): Entity Parameters components: List
The list of components to set.
|
setComponents
(
components
)
|
Sets the components for this entity.
Signature
fun setComponents(vararg components: ComponentBase): Entity Parameters |
setMap
(
attribute
, value
)
| Parameters attribute: Intvalue: 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 Entity?
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: IntReturns Entity? |
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.
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.
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.
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.
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.
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
Methods
create
()
|
Creates a new entity with the default data model.
Signature
fun create(): Entity |
create
(
dm
)
| |
create
(
component
)
|
Creates a new entity with the specified component.
Signature
fun create(component: ComponentBase): Entity Parameters |
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.
|
create
(
components
)
|
Creates a new entity with the specified variable number of components.
Signature
fun create(vararg components: ComponentBase): Entity Parameters |
createPanelEntity
(
panelId
, transform
, components
)
|
Signature
fun Entity.Companion.createPanelEntity(panelId: Int, transform: Transform, vararg components: ComponentBase): Entity Parameters Returns Entity |
createPanelEntity
(
entityId
, panelId
, transform
, components
)
|
Signature
fun Entity.Companion.createPanelEntity(entityId: Int, panelId: Int, transform: Transform, vararg components: ComponentBase): Entity Parameters Returns Entity |
fromBox
(
length
, transform
, material
, components
)
|
Signature
fun Entity.Companion.fromBox(length: Float, transform: Transform, material: Material? = null, vararg components: ComponentBase): Entity Parameters Returns Entity |
fromGLB
(
mesh
, transform
, components
)
|
Signature
fun Entity.Companion.fromGLB(mesh: Mesh, transform: Transform, vararg components: ComponentBase): Entity Parameters Returns Entity |
fromMeshAndMaterial
(
mesh
, material
, transform
, components
)
|
Signature
fun Entity.Companion.fromMeshAndMaterial(mesh: Mesh, material: Material, transform: Transform, vararg components: ComponentBase): Entity Parameters Returns Entity |
fromPanelRegistry
(
registry
, transform
, components
)
|
Signature
fun Entity.Companion.fromPanelRegistry(registry: PanelRegistration, transform: Transform, vararg components: ComponentBase): Entity Parameters Returns Entity |
fromSphere
(
length
, transform
, material
, components
)
|
Signature
fun Entity.Companion.fromSphere(length: Float, transform: Transform, material: Material? = null, vararg components: ComponentBase): Entity Parameters Returns Entity |
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 |
Virtual reality / Meta Horizon
Support and legal
Virtual reality / Meta Horizon
Support and legal
Virtual reality / Meta Horizon
Support and legal
English (US)
© 2026 Meta