Chaparral Village: Building an immersive visionOS adventure game

At a glance

Project structure

Source bundle/
├── ChaparralVillageBuildingAnImmersiveVisionOSAdventureGame/ChaparralVillage/ChaparralVillageApp.swift  # ChaparralVillageApp, PluginHandler
├── ChaparralVillageBuildingAnImmersiveVisionOSAdventureGame/ChaparralVillage/ContentView.swift  # ContentView, ChaparralVillageRealityView
├── ChaparralVillageBuildingAnImmersiveVisionOSAdventureGame/Packages/RCPCustomComponents/Sources/RCPCustomComponents/Managers/LevelManager.swift  # LevelManager, LoadSlotData, LevelLoadedEvent
├── ChaparralVillageBuildingAnImmersiveVisionOSAdventureGame/Packages/RCPCustomComponents/Sources/RCPCustomComponents/Managers/InputManager.swift  # DragInput, InputManager, EventStateStatus
├── ChaparralVillageBuildingAnImmersiveVisionOSAdventureGame/Packages/RCPCustomComponents/Sources/RCPCustomComponents/Managers/AppState.swift  # AppPhase, AppState
├── ChaparralVillageBuildingAnImmersiveVisionOSAdventureGame/Packages/RCPCustomComponents/Sources/RCPCustomComponents/EcsAbstractions/SceneBound.swift  # SceneBound, SceneBoundTracker
├── ChaparralVillageBuildingAnImmersiveVisionOSAdventureGame/Packages/RCPCustomComponents/Sources/RCPCustomComponents/LevelMarkup/ForceContainer.swift  # ForceContainer, PhysicsUpdateBehavior, ForceContainerReset
├── ChaparralVillageBuildingAnImmersiveVisionOSAdventureGame/Packages/RCPCustomComponents/Sources/RCPCustomComponents/Managers/InputProtocols.swift  # TapHandler, DragEvent, DragHandler
└── ChaparralVillageBuildingAnImmersiveVisionOSAdventureGame/ChaparralVillage.realitycomposerpro/Assets/Audio/Ambient Audio/VillageAtmosphere.tm_audio_file  # authored RealityKit content

Structure observations

• The runtime boundary is WindowGroup + volumetric window + 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.
• This source came from Apple’s Apple-Account-gated DMG, ingested read-only after the user authenticated; it is not a public DocC ZIP.
• Apple publishes no checksum for that DMG. The SHA-256 here is the locally computed immutable identity of the authenticated download, not an Apple-published checksum.

Overall architecture

flowchart LR
    ChaparralVillageApp_1["ChaparralVillageApp"]
    WindowGroup___volumetric_window___ImmersiveSpace_2["WindowGroup + volumetric window + ImmersiveSpace"]
    ContentView_3["ContentView"]
    AppState_4["AppState"]
    RealityView_entity_graph_5["RealityView entity graph"]
    RealityKit_components_and_systems_6["RealityKit components and systems"]
    ChaparralVillageApp_1 --> WindowGroup___volumetric_window___ImmersiveSpace_2
    WindowGroup___volumetric_window___ImmersiveSpace_2 --> ContentView_3
    ContentView_3 --> AppState_4
    AppState_4 --> RealityView_entity_graph_5
    RealityView_entity_graph_5 --> RealityKit_components_and_systems_6

Reference code

ChaparralVillageBuildingAnImmersiveVisionOSAdventureGame/ChaparralVillage/ChaparralVillageApp.swift:16 — the app or executable entry declares the outer scene lifecycle.

struct ChaparralVillageApp: 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
    ChaparralVillageApp *-- AppState : appState
    ChaparralVillageApp *-- SaveManager : saveManager
    CauldronWaterDisplay --> Entity : cauldron
    ContentView --> SaveManager : saveManager

Ownership evidence

ChaparralVillageBuildingAnImmersiveVisionOSAdventureGame/ChaparralVillage/ChaparralVillageApp.swift:18 — representative stored state or the nearest verified lifecycle anchor.

    @State private var appState = AppState()
    @Environment(\.physicalMetrics) var physicalMetrics

    init() {
        RCPCustomComponentsPlugin
            .create()
            .setup(context: PluginHandler())
    }

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

Verified protocol-oriented seams: BuoyancySim → PhysicsUpdateBehavior, CutsceneManager → SceneBound, ZoneCutsceneHandler → ZoneChangeHandler, DebugDraw → SceneBound, InputProxyManager → SceneBound, ARManager → SceneBound. Framework conformances remain adapters, not proof of an app-wide protocol architecture.

Access control

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

Reference code

ChaparralVillageBuildingAnImmersiveVisionOSAdventureGame/ChaparralVillage/ChaparralVillageApp.swift:18 — representative visibility boundary.

@main
struct ChaparralVillageApp: App {
    // ...
    @State private var appState = AppState()
    // ...
}

Logic ownership and placement

Design patterns

Naming conventions

• Role suffixes are evidence, not decoration: App: ChaparralVillageApp; Model: DialogModel, LadderModel; Controller: DioramaViewController; Manager: ARManager, AudioManager, CutsceneManager, InputManager, InputProxyManager.
• ECS names pair data and behavior: components BuoyantObject, Cauldron, CauldronWaterDisplay, CurtainPinComponent; systems BuoyantObjectSystem, StirringSystem, CauldronWaterDisplaySystem, CurtainClothBodySystem.
• Protocols: SceneBound, PhysicsUpdateBehavior, TapHandler, DragHandler, Affordance, CustomRestore.
• Commands use verb-led methods: registerComponent, registerAction, registerSystem, store, load, fadeInRestoredEntities, fadeOutExistingLevel, unload.
• Files generally match their primary type; Views, Models, Managers, Providers, Components, Systems, and Packages folders describe architectural roles where present.

Architecture takeaways

• Treat ChaparralVillageApp 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
• Provenance note: Apple-Account-authenticated DMG, ingested locally read-only; SHA-256 computed locally because Apple does not publish one for this download.