Building an immersive experience with RealityKit

At a glance

Project structure

Source bundle/
└── BugBreakAR/
    ├── GameViewController.swift  # GameViewController
    ├── Rendering/
    │   └── MetalRenderer.swift  # MetalRenderer
    ├── Components/
    │   ├── EntitySwitcherComponent.swift  # EntitySwitcherAnimationType, EntitySwitcherComponent, ChildEntityInfo
    │   ├── AudioComponent.swift  # AudioComponent, HasAudioComponent
    │   └── InteractionComponent.swift  # InteractionComponent, InteractionComponentDelegate, HasInteraction
    ├── AppDelegate.swift  # AppDelegate
    └── GameManager.swift  # GameManager, GameState

Structure observations

• The runtime boundary is UIApplicationDelegate + UIViewController; the tree is pruned to lifecycle, state, framework, rendering, and ECS files.
• The source is C/Objective-C header, Metal, Swift; role-named types and feature folders separate the major responsibilities.
• This archive extracts to the same source-tree SHA-256 as Creating a game with scene understanding; this document focuses on underwater systems and postprocessing.

Overall architecture

flowchart LR
    AppDelegate_1["AppDelegate"]
    UIApplicationDelegate___UIViewController_2["UIApplicationDelegate + UIViewController"]
    GameViewController_3["GameViewController"]
    GameManager_4["GameManager"]
    MetalRenderer_5["MetalRenderer"]
    RealityKit_entity_graph_6["RealityKit entity graph"]
    RealityKit_gameplay___Metal_postprocess_7["RealityKit gameplay + Metal postprocess"]
    AppDelegate_1 --> UIApplicationDelegate___UIViewController_2
    UIApplicationDelegate___UIViewController_2 --> GameViewController_3
    GameViewController_3 --> GameManager_4
    GameManager_4 --> MetalRenderer_5
    MetalRenderer_5 --> RealityKit_entity_graph_6
    RealityKit_entity_graph_6 --> RealityKit_gameplay___Metal_postprocess_7

Reference code

BugBreakAR/AppDelegate.swift:13 — executable or app-lifecycle anchor.

class AppDelegate: UIResponder, UIApplicationDelegate {
    // ...
}

The diagram is a responsibility flow, not a claim that every adjacent node directly calls the next. It separates lifecycle, presentation, stable state, framework/session work, and the RealityKit entity graph.

Ownership and state

classDiagram
    GameManager o-- GameViewController : viewController
    GameManager *-- AnchorEntity : creaturesAnchor
    GameManager --> AnchorEntity : audioAnchor
    GameManager --> InputSystem : inputSystemInstance

Ownership evidence

BugBreakAR/GameManager.swift:20 — representative stored state or nearest verified lifecycle anchor.

    weak var viewController: GameViewController?
    var inputSystemInstance: InputSystem?
    var voxels: Voxels?
    weak var assets: GameAssets?

    // Game state related
    var currentState = GameState.applicationLaunched
    var assetsLoaded = false

Ownership is intentionally narrow: environment, bindings, observed objects, weak links, and delegate callbacks do not prove lifetime ownership. Initialized stored services and wrapper-managed state do; entities added inside a RealityKit content closure belong to that entity graph.

Class and protocol design

Verified protocol-oriented seams: DebugSettingBool → DebugSettingProtocol, DebugSettingInt → DebugSettingProtocol, DebugSettingFloat → DebugSettingProtocol, DebugSettingEnum → DebugSettingProtocol, CreatureEntity → HasEntitySwitcher, CreatureEntity → EntitySwitcherComponentDelegate. Framework conformances remain adapters, not proof of an app-wide protocol architecture.

Access control

No reviewed Swift access example uses private(set), open; declarations without a modifier are internal.

Objective-C/C header and implementation visibility is documented separately from Swift lexical access control.

Reference code

BugBreakAR/Components/EntitySwitcherComponent.swift:15 — representative visibility boundary.

private let log = OSLog(subsystem: appSubsystem, category: "EntitySwitchComponent")

Logic ownership and placement

Design patterns

Naming conventions

• Role suffixes are evidence, not decoration: Model: MetalModel; Controller: DebugSettingsViewController, GameViewController, MainMenuViewController; Manager: GameManager; Renderer: MetalRenderer; System: InputSystem.
• ECS names pair data and behavior: components AudioComponent, CustomCameraComponent, EntitySwitcherComponent, InteractionComponent, PathfindingComponent; systems none.
• Protocols: HasAudioComponent, HasEntitySwitcher, EntitySwitcherComponentDelegate, InteractionComponentDelegate, HasInteraction, PathfindingComponentDelegate.
• Commands use verb-led methods: viewWillAppear, viewDidAppear, prepare, configureView, resetTracking, setupIBL, gestureRecognizer, nearbyFaceWithClassification.
• Files and folders use primary-type or responsibility names such as Views, Models, Rendering, Components, Systems, Packages, or feature names where those boundaries exist.

Architecture takeaways

• Treat AppDelegate as the owner of executable or scene lifecycle, not automatically as the owner of every entity created later.
• Keep view/controller input near presentation, but move sessions, reconstruction, capture, rendering, shared game state, or documents into stable owners when their lifetime exceeds one callback or render pass.
• A shared source tree can support different documentation questions; keep each page focused on its specific architecture question rather than duplicating generic analysis.

Source map

• Official Apple documentation