Incorporating real-world surroundings in an immersive experience

At a glance

Project structure

Source bundle/
└── SceneReconstructionExample/
    ├── SceneReconstructionExampleApp.swift  # SceneReconstructionExampleApp
    ├── EntityModel.swift  # EntityModel
    ├── CubeMeshInteraction.swift  # CubeMeshInteraction
    └── Extensions.swift  # func

Structure observations

• The runtime boundary is ImmersiveSpace; the pruned tree lists only files that explain lifecycle, state, or framework integration.
• App code is compact; any explicit model, provider, or entity owner is still shown below rather than collapsed into view-local state.

Overall architecture

flowchart LR
    SceneReconstructionExampleApp_1["SceneReconstructionExampleApp"]
    ImmersiveSpace_2["ImmersiveSpace"]
    CubeMeshInteraction_3["CubeMeshInteraction"]
    EntityModel_4["EntityModel"]
    RealityView_entity_graph_5["RealityView entity graph"]
    ARKit_providers___RealityKit_6["ARKit providers + RealityKit"]
    SceneReconstructionExampleApp_1 --> ImmersiveSpace_2
    ImmersiveSpace_2 --> CubeMeshInteraction_3
    CubeMeshInteraction_3 --> EntityModel_4
    EntityModel_4 --> RealityView_entity_graph_5
    RealityView_entity_graph_5 --> ARKit_providers___RealityKit_6

Reference code

SceneReconstructionExample/SceneReconstructionExampleApp.swift:13 — the app or executable entry declares the outer scene lifecycle.

struct SceneReconstructionExampleApp: App {
    @State private var model = EntityModel()

    var body: some Scene {
        ImmersiveSpace(id: cubeMeshInteractionID) {
            CubeMeshInteraction()
                .environment(model)
        }
    }
}

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
    SceneReconstructionExampleApp *-- EntityModel : model
    EntityModel *-- ARKitSession : session
    CubeMeshInteraction o-- EntityModel : model
    EntityModel *-- HandTrackingProvider : handTracking

Ownership evidence

SceneReconstructionExample/SceneReconstructionExampleApp.swift:14 — representative stored state or the nearest verified lifecycle anchor.

    @State private var model = EntityModel()

    var body: some Scene {
        ImmersiveSpace(id: cubeMeshInteractionID) {
            CubeMeshInteraction()
                .environment(model)
        }
    }

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), public, open; unmodified Swift declarations are internal.

Reference code

SceneReconstructionExample/EntityModel.swift:21 — representative visibility boundary.

    private var meshEntities = [UUID: ModelEntity]()
    private let fingerEntities: [HandAnchor.Chirality: ModelEntity] = [
        .left: .createFingertip(),
        .right: .createFingertip()
    ]

Logic ownership and placement

Design patterns

Naming conventions

• Role suffixes are evidence, not decoration: App: SceneReconstructionExampleApp; Model: EntityModel.
• Protocols: no app-defined protocol in the reviewed source.
• Commands use verb-led methods: setupContentEntity, processHandUpdates, processReconstructionUpdates, monitorSessionEvents, addCube, createFingertip.
• Files generally match their primary type; Views, Models, Managers, Providers, Components, Systems, and Packages folders describe architectural roles where present.

Architecture takeaways

• Treat SceneReconstructionExampleApp 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.
• Model immersive-space open, transition, and close states explicitly so windows and immersive content cannot drift apart.
• The compact source does not justify adding repository, coordinator, or protocol layers beyond the model, provider, or view boundary the sample actually declares.

Source map

• Official Apple documentation