Hello World

At a glance

Project structure

Source bundle/
├── World/WorldApp.swift  # WorldApp
├── World/Model/ViewModel.swift  # ViewModel, WindowState
├── Packages/WorldAssets/Sources/WorldAssets/SunPositionSystem.swift  # SunPositionComponent, SunPositionSystem
├── World/Systems/TraceSystem.swift  # TraceComponent, TraceSystem, TraceMesh
├── World/Modules/Modules.swift  # Modules
├── World/Systems/RotationSystem.swift  # RotationComponent, RotationSystem
├── World/RealityViews/OpenWindow.swift  # OpenWindow, OpenWindowButton
├── World/Globe/GlobeControls.swift  # GlobeControls, GlobeTiltPicker, TiltButtonAlignment
└── Packages/WorldAssets/Package.realitycomposerpro/ProjectData/main.json  # authored RealityKit content

Structure observations

• The runtime boundary is Window + 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.

Overall architecture

flowchart LR
    WorldApp_1["WorldApp"]
    Window___WindowGroup___volumetric_window___ImmersiveSpace_2["Window + WindowGroup + volumetric window + ImmersiveSpace"]
    Modules_3["Modules"]
    ViewModel_4["ViewModel"]
    RealityView_entity_graph_5["RealityView entity graph"]
    RealityKit_components_and_systems_6["RealityKit components and systems"]
    WorldApp_1 --> Window___WindowGroup___volumetric_window___ImmersiveSpace_2
    Window___WindowGroup___volumetric_window___ImmersiveSpace_2 --> Modules_3
    Modules_3 --> ViewModel_4
    ViewModel_4 --> RealityView_entity_graph_5
    RealityView_entity_graph_5 --> RealityKit_components_and_systems_6

Reference code

World/WorldApp.swift:13 — the app or executable entry declares the outer scene lifecycle.

struct WorldApp: 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
    WorldApp *-- ViewModel : model
    WorldApp *-- ImmersionStyle : orbitImmersionStyle
    WorldApp *-- ImmersionStyle : solarImmersionStyle
    WindowState --> WindowState : navigationWindowState

Ownership evidence

World/WorldApp.swift:15 — representative stored state or the nearest verified lifecycle anchor.

    @State private var model = ViewModel()

    // The immersion styles for different modules.
    @State private var orbitImmersionStyle: ImmersionStyle = .mixed
    @State private var solarImmersionStyle: ImmersionStyle = .full

    static let modulesWindowID = "ModulesWindowID"
    static let solarSystemControlsWindowID = "SolarSystemControlsWindowID"

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

Reference code

World/Entities/EarthEntity.swift:18 — representative visibility boundary.

class EarthEntity: Entity {
    // ...
    private var earth: Entity = Entity()
    // ...
}

Logic ownership and placement

Design patterns

Naming conventions

• Role suffixes are evidence, not decoration: App: WorldApp; ViewModel: ViewModel; View: ItemView.
• ECS names pair data and behavior: components SunPositionComponent, RotationComponent, TraceComponent; systems SunPositionSystem, RotationSystem, TraceSystem.
• Protocols: no app-defined protocol in the reviewed source.
• Commands use verb-led methods: update, getModelDescendents, setSunPosition, addPosition, generateIndices, makeTraceModel.
• Files generally match their primary type; Views, Models, Managers, Providers, Components, Systems, and Packages folders describe architectural roles where present.

Architecture takeaways

• Treat WorldApp 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.
• Model immersive-space open, transition, and close states explicitly so windows and immersive content cannot drift apart.

Source map

• Official Apple documentation