Canyon Crosser: Building a volumetric hike-planning app

At a glance

Project structure

Source bundle/
├── CanyonCrosser/CanyonCrosserApp.swift  # CanyonCrosserApp
├── CanyonCrosser/Views/Progress Slider/WeatherOrTimeView.swift  # WeatherOrTimeView, Display, WeatherAndTime
├── CanyonCrosser/Models/AppModel/AppModel.swift  # LoadingError, AppModel
├── CanyonCrosser/Models/AppPhaseModel.swift  # AppPhaseModel, AppPhase
├── CanyonCrosser/ContentView.swift  # ContentView
├── Packages/RealityKitContent/Sources/RealityKitContent/ValueGradient.swift  # Interpolatable, ValueGradient
├── CanyonCrosser/ECS/ClippingMarginPercentageComponent.swift  # ClippingMarginPercentageComponent, Environment, Values
├── CanyonCrosser/ECS/FeatheringSystem.swift  # FadingCloudComponent, FeatheringSystem
└── Packages/RealityKitContent/Package.realitycomposerpro/ProjectData/main.json  # authored RealityKit content

Structure observations

• The runtime boundary is WindowGroup + volumetric window; 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
    CanyonCrosserApp_1["CanyonCrosserApp"]
    WindowGroup___volumetric_window_2["WindowGroup + volumetric window"]
    ContentView_3["ContentView"]
    AppModel_4["AppModel"]
    RealityView_entity_graph_5["RealityView entity graph"]
    RealityKit_components_and_systems_6["RealityKit components and systems"]
    CanyonCrosserApp_1 --> WindowGroup___volumetric_window_2
    WindowGroup___volumetric_window_2 --> ContentView_3
    ContentView_3 --> AppModel_4
    AppModel_4 --> RealityView_entity_graph_5
    RealityView_entity_graph_5 --> RealityKit_components_and_systems_6

Reference code

CanyonCrosser/CanyonCrosserApp.swift:12 — the app or executable entry declares the outer scene lifecycle.

struct CanyonCrosserApp: 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
    CanyonCrosserApp *-- AppModel : appModel
    CanyonCrosserApp *-- AppPhaseModel : appPhaseModel
    ContentView o-- AppPhaseModel : appPhaseModel
    AppModel --> AnimationPlaybackController : hikerAnimationController

Ownership evidence

CanyonCrosser/CanyonCrosserApp.swift:13 — representative stored state or the nearest verified lifecycle anchor.

    @State private var appModel: AppModel = AppModel()

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: Double → Interpolatable, Float → Interpolatable, SIMD3<Float> → Interpolatable, SIMD4<Float> → Interpolatable. Framework conformances remain adapters, not proof of an app-wide protocol architecture.

Access control

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

Reference code

CanyonCrosser/CanyonCrosserApp.swift:13 — representative visibility boundary.

    @State private var appModel: AppModel = AppModel()

Logic ownership and placement

Design patterns

Naming conventions

• Role suffixes are evidence, not decoration: App: CanyonCrosserApp; Model: AppModel, AppPhaseModel, CarouselModel; View: BackButtonView, CarouselBodyView, CarouselLabelView, CarouselView, CompactControlsView.
• ECS names pair data and behavior: components ClippingMarginPercentageComponent, FadingCloudComponent, HikePlaybackStateComponent, HikeTimingComponent; systems FeatheringSystem, HikeSystem, LightRotationSystem, TimeOfDaySystem.
• Protocols: Interpolatable.
• Commands use verb-led methods: fadeInClouds, fadeOutClouds, getHikerAnimationPlaybackController, setHikerVisibility.
• Files generally match their primary type; Views, Models, Managers, Providers, Components, Systems, and Packages folders describe architectural roles where present.

Architecture takeaways

• Treat CanyonCrosserApp 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.
• Use RealityKit components for per-entity data and systems for repeated simulation instead of a monolithic view model.

Source map

• Official Apple documentation