Placing entities using head and device transform

At a glance

Project structure

Source bundle/
├── HeadTracking/HeadTrackingApp.swift  # HeadTrackingApp
├── HeadTracking/AppModel.swift  # AppModel, HeadTrackState
├── HeadTracking/FollowSystemAndComponent/FollowComponent.swift  # FollowComponent
├── HeadTracking/FollowSystemAndComponent/FollowSystem.swift  # FollowSystem
├── HeadTracking/ImmersiveView.swift  # ImmersiveView
├── Packages/RealityKitContent/Sources/RealityKitContent/RealityKitContent.swift
├── HeadTracking/TogglePanel.swift  # TogglePanel
├── Packages/RealityKitContent/Package.swift
└── Packages/RealityKitContent/Package.realitycomposerpro/ProjectData/main.json  # authored RealityKit content

Structure observations

• The runtime boundary is WindowGroup + ImmersiveSpace; the pruned tree lists only files that explain lifecycle, state, or framework integration.
• App code is split into role-named views, models, managers, providers, components, or systems.
• Authored .reality or Reality Composer Pro content is a real implementation boundary; Swift loads or drives it rather than reproducing its entity graph.

Overall architecture

flowchart LR
    HeadTrackingApp_1["HeadTrackingApp"]
    WindowGroup___ImmersiveSpace_2["WindowGroup + ImmersiveSpace"]
    ImmersiveView_3["ImmersiveView"]
    AppModel_4["AppModel"]
    RealityView_entity_graph_5["RealityView entity graph"]
    ARKit_providers___RealityKit_6["ARKit providers + RealityKit"]
    HeadTrackingApp_1 --> WindowGroup___ImmersiveSpace_2
    WindowGroup___ImmersiveSpace_2 --> ImmersiveView_3
    ImmersiveView_3 --> AppModel_4
    AppModel_4 --> RealityView_entity_graph_5
    RealityView_entity_graph_5 --> ARKit_providers___RealityKit_6

Reference code

HeadTracking/HeadTrackingApp.swift:11 — the app or executable entry declares the outer scene lifecycle.

struct HeadTrackingApp: App {
    // ...
}

The diagram is a responsibility flow, not a claim that every adjacent node directly calls the next. It keeps scene ownership, shared state, RealityKit content, and framework-provider work at separate levels.

Ownership and state

classDiagram
    HeadTrackingApp *-- AppModel : appModel
    ImmersiveView o-- AppModel : appModel
    ImmersiveView *-- Entity : followRoot
    ImmersiveView *-- Entity : headAnchorRoot

Ownership evidence

HeadTracking/HeadTrackingApp.swift:12 — representative stored state or the nearest verified lifecycle anchor.

    @State private var appModel: AppModel = AppModel()
    @Environment(\.openImmersiveSpace) var openImmersiveSpace
    
    // Register the system and the component.
    init() {
        FollowSystem.registerSystem()
        FollowComponent.registerComponent()
    }

Ownership here is deliberately narrow: @Environment and weak references are shared links, initialized @State or stored services are lifecycle ownership, and a RealityView content closure owns additions to its entity graph without making the SwiftUI view a reference-type owner.

Class and protocol design

The source defines no local substitution protocol in the reviewed boundary. Its protocol use is framework-facing (App, View, RealityKit/ARKit protocols, or platform adapters), so this document does not label the whole app protocol-oriented.

Access control

No reviewed declaration uses fileprivate, private(set), open; unmodified Swift declarations are internal.

Reference code

HeadTracking/FollowSystemAndComponent/FollowSystem.swift:15 — representative visibility boundary.

    private let arkitSession = ARKitSession()
    private let worldTrackingProvider = WorldTrackingProvider()
    
    public init(scene: RealityKit.Scene) {
        runSession()
    }

Logic ownership and placement

Design patterns

Naming conventions

• Role suffixes are evidence, not decoration: App: HeadTrackingApp; Model: AppModel; View: ImmersiveView.
• ECS names pair data and behavior: components FollowComponent; systems FollowSystem.
• Protocols: no app-defined protocol in the reviewed source.
• Commands use verb-led methods: runSession, update, startFollowMode, startHeadPositionMode, toggleHeadPositionModeOrFollowMode, playHummingbirdAnimation.
• Files generally match their primary type; Views, Models, Managers, Providers, Components, Systems, and Packages folders describe architectural roles where present.

Architecture takeaways

• Treat HeadTrackingApp as the owner of scene declarations, not as the owner of every RealityKit entity created later.
• Keep view-local interaction in SwiftUI, but move provider sessions, playback resources, shared game state, or transport state into a stable owner when their lifetime exceeds one render pass.
• Run ARKit providers for the scene lifetime and consume their asynchronous updates in cancellable tasks; map anchors to entities at the boundary.
• Use RealityKit components for per-entity data and systems for repeated simulation instead of a monolithic view model.
• Model immersive-space open, transition, and close states explicitly so windows and immersive content cannot drift apart.

Source map

• Official Apple documentation