Chapter 2
Entities, Anchors, and Scene Hierarchies

Venture into the dynamic organs of RealityKit-entities, anchors, and scenes-where structure and adaptability shape the very essence of every AR experience. This chapter demystifies how digital objects persist, relate, and move within physical space, empowering you to construct AR worlds that respond intuitively to users and their environments. Whether you're aiming for hyper-realistic placements or intricate interactive hierarchies, you'll uncover the patterns and best practices needed to master spatial logic in AR.

2.1 Entity Lifecycle and State Management

Entities in RealityKit serve as the fundamental building blocks of augmented reality (AR) scenes, encapsulating spatial, visual, and interactive components. Understanding the lifecycle and state management of these entities is essential for creating dynamic and responsive AR applications that maintain consistent performance and behavior throughout runtime.

Entity creation in RealityKit typically begins with instantiating an Entity or one of its subclasses such as ModelEntity, AnchorEntity, or LightEntity. These classes provide specialized functionality tailored to distinct roles within the scene. The initialization phase establishes the entity's initial state, including its transform, components, and child entities.

Entities are often initialized with specific components that define their properties and capabilities. Components represent modular data-including the TransformComponent for position, rotation, and scale, the ModelComponent for rendering geometry, or the PhysicsBodyComponent for physical simulation. The combination of such components forms an entity's functional identity, enabling it to interact with other scene elements and respond to application logic.

let modelEntity = ModelEntity(mesh: .generateBox(size: 0.2),
materials: [SimpleMaterial(color: .blue, isMetallic: false)])
modelEntity.position = [0, 0.5, 0]

In this example, a ModelEntity is instantiated with a blue box mesh and positioned within the AR scene. The initial component setup is crucial for downstream lifecycle management and updates.

The state of an entity encompasses its components, properties, and hierarchical relationships within the scene graph. Maintaining state persistence is a significant challenge in AR applications, especially when considering session interruptions or dynamic scene updates.

RealityKit provides direct access to an entity's components through its components collection, enabling read and write operations at runtime. State mutation involves modifying these components to reflect changes in position, appearance, physics properties, or other attributes. The mutability of components leverages Swift's value semantics with advanced copy-on-write behavior, ensuring efficient state management without unnecessary overhead.

if var transform = modelEntity.components[TransformComponent.self] {
transform.translation += SIMD3<Float>(0.0, 0.1, 0.0)
modelEntity.components[TransformComponent.self] = transform
}

This pattern demonstrates how to safely mutate an entity's transform component by retrieving, modifying, and reassigning it. Additionally, entities can dynamically add or remove components to adapt their behavior:

modelEntity.components.set(PhysicsBodyComponent(massProperties: .default,
material: .default,
mode: .dynamic))

Here, physics is introduced programmatically, changing how the entity interacts within a physics-enabled environment.

Entities form a directed acyclic graph (DAG), where parent-child relationships facilitate complex scene hierarchies and logical grouping. Adding an entity as a child to an AnchorEntity or another entity integrates it into the rendered scene and the AR session's coordinate space.

let anchor = AnchorEntity(world: SIMD3<Float>(0, 0, 0))
anchor.addChild(modelEntity)
arView.scene.addAnchor(anchor)

The addition to an anchor entity ensures the entity's transform is tracked relative to a stable world reference and supports arbitrary hierarchy structures. When entities are part of a hierarchical chain, transform mutations propagate through the hierarchy, combining parent and child transform components to yield final world positions and rotations.

Robust lifecycle management mandates mechanisms to observe and react to entity state changes through event-driven paradigms. RealityKit facilitates this through notifications and delegate callbacks that inform about additions, removals, or component changes within entities.

One such mechanism is the SceneEvents protocol, which allows subscribing to event streams such as when an entity is added to or removed from a scene:

extension MyARView: HasAnchoring {
func setupEntityLifecycleObservers(for entity: Entity) {
entity.scene?.subscribe(to: SceneEvents.EntityAdded.self) { event in
if event.entity == entity {
print("Entity added to scene")
}
}.store(in: &cancellables)

entity.scene?.subscribe(to: SceneEvents.EntityRemoved.self) { event in
if event.entity == entity {
print("Entity removed from scene")
}
}.store(in: &cancellables)
}
}

These event subscriptions provide asynchronous hooks to monitor and respond to lifecycle transitions, such as initializing resources only when the entity becomes active in the scene or cleaning up upon removal.

Similarly, mutation events within components can be tracked indirectly by manually emitting notifications or through periodic polling strategies, as automatic component change events are not natively exposed. Effective state synchronization can be achieved by combining event subscriptions with state snapshots, especially in multi-threaded or networked contexts.

Explicit entity destruction is commonly performed by removing the entity from its parent or anchor and ensuring proper deallocation to avoid memory leaks. RealityKit's scene graph manages references to entities via strong ownership; thus, severing an entity's connections typically initiates its lifecycle termination.

modelEntity.removeFromParent()

Once detached, proper cleanup of associated resources-such as physical simulation objects, textures, or custom components-must be undertaken. Developers are encouraged to encapsulate cleanup routines inside entity-specific methods or lifecycle observers, especially when implementing complex components or resources bound to hardware.

In multi-user or networked AR experiences, entity state synchronization introduces an additional complexity layer to lifecycle management. RealityKit incorporates mechanisms such as MultipeerConnectivity and Cloud Anchors to persist and synchronize entity states between devices.

Entity states, including transform and component data, must be serialized efficiently and distributed via network protocols. Updates to the lifecycle-creation, mutation, destruction-are broadcast to all peers and reconciled to maintain a consistent shared environment. State management in these contexts demands careful consideration of latency, consistency models, and conflict resolution strategies.

To achieve robust and responsive AR content, several architectural and design principles are recommended:

Encapsulation of State Logic: Encapsulate entity state and lifecycle management logic within...