Bringing your SceneKit projects to RealityKit

At a glance

Project structure

Source bundle/
├── Pyro Panda RealityKit/Pyro Panda RealityKit/PyroPandaRealityKitApp.swift  # PyroPandaRealityKitApp
├── Pyro Panda RealityKit/Pyro Panda RealityKit/AppModel.swift  # AppModel, ImmersiveSpaceState
├── Pyro Panda RealityKit/Packages/AgentComponent/Sources/AgentComponent/AgentSystem.swift  # AgentSystem
├── Pyro Panda RealityKit/Packages/AgentComponent/Sources/AgentComponent/AgentComponent.swift  # AgentComponent, AgentType, AgentState
├── Pyro Panda RealityKit/Pyro Panda RealityKit/Views/ContentView.swift  # ContentView
├── Pyro Panda SceneKit/Swift/Shared/UI/Menu.swift  # MenuDelegate, Menu
├── Pyro Panda SceneKit/Swift/iOS/ButtonOverlay.swift  # ButtonOverlayDelegate, ButtonOverlay
└── Pyro Panda RealityKit/Packages/PyroPanda/Package.realitycomposerpro/ProjectData/main.json  # authored RealityKit content

Structure observations

• The runtime boundary is WindowGroup + ImmersiveSpace + SwiftUI/UIKit host; the tree is pruned to lifecycle, state, framework, rendering, and ECS files.
• The source is Swift; role-named types and feature folders separate the major responsibilities.
• Authored .reality, .rkassets, or Reality Composer Pro content is an implementation boundary; Swift loads or drives it rather than reproducing its entity graph.

Overall architecture

flowchart LR
    PyroPandaRealityKitApp_1["PyroPandaRealityKitApp"]
    WindowGroup___ImmersiveSpace___SwiftUI_UIKit_host_2["WindowGroup + ImmersiveSpace + SwiftUI/UIKit host"]
    ContentView_3["ContentView"]
    AppModel_4["AppModel"]
    AgentSystem_5["AgentSystem"]
    RealityKit_entity_graph_6["RealityKit entity graph"]
    RealityKit_ECS_feature_packages_7["RealityKit ECS feature packages"]
    PyroPandaRealityKitApp_1 --> WindowGroup___ImmersiveSpace___SwiftUI_UIKit_host_2
    WindowGroup___ImmersiveSpace___SwiftUI_UIKit_host_2 --> ContentView_3
    ContentView_3 --> AppModel_4
    AppModel_4 --> AgentSystem_5
    AgentSystem_5 --> RealityKit_entity_graph_6
    RealityKit_entity_graph_6 --> RealityKit_ECS_feature_packages_7

Reference code

Pyro Panda RealityKit/Pyro Panda RealityKit/PyroPandaRealityKitApp.swift:13 — executable or app-lifecycle anchor.

struct PyroPandaRealityKitApp: App {
    // ...
}

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
    PyroPandaRealityKitApp *-- AppModel : appModel
    AppModel --> Entity : gameRoot
    ContentView o-- AppModel : appModel
    AppModel --> ImmersiveSpaceState : immersiveSpaceState

Ownership evidence

Pyro Panda RealityKit/Pyro Panda RealityKit/PyroPandaRealityKitApp.swift:15 — representative stored state or nearest verified lifecycle anchor.

@main
struct PyroPandaRealityKitApp: App {
    // ...
    @State private var appModel = AppModel()
    // ...
}

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

The reviewed source defines no local substitution protocol. Its App, View, delegate, renderer, ARKit, and RealityKit conformances are framework-facing contracts, so this document does not label the whole app protocol-oriented.

Access control

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

Reference code

Pyro Panda RealityKit/Packages/PyroPanda/Sources/PyroPanda/RunAwayComponent.swift:35 — representative visibility boundary.

    private static func registerSystem() {
        Task {
            await RunAwaySystem.registerSystem()
        }
    }

Logic ownership and placement

Design patterns

Naming conventions

• Role suffixes are evidence, not decoration: App: PyroPandaRealityKitApp; Model: AppModel; Controller: GameController, WASDController; System: AgentSystem, CharacterMovementSystem, ControllerInputSystem, FollowSystem, MoveBetweenSystem; Component: AgentComponent, AttackComponent, BaseComponent, CharacterMovementComponent, CharacterStateComponent.
• ECS names pair data and behavior: components AgentComponent, CharacterMovementComponent, CharacterStateComponent, ControllerInputReceiver, RunAwayComponent; systems AgentSystem, CharacterMovementSystem, ControllerInputSystem, RunAwaySystem, SpinSystem.
• Protocols: MenuDelegate, ButtonOverlayDelegate, PadOverlayDelegate.
• Commands use verb-led methods: reset, didConnectController, didDisconnectController, update, constrainPosition, updateAgentState, fearingUpdate, chasingUpdate.
• 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 PyroPandaRealityKitApp 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.
• Use components for per-entity data and systems for repeated simulation instead of centralizing every update in a view model or controller.
• Count authored Reality Composer Pro assets as implementation; the Swift shell is not the complete architecture.

Source map

• Official Apple documentation