Using object capture assets in RealityKit

At a glance

Project structure

Source bundle/
└── CaptureChess/
    ├── GameManager.swift  # GameManager, State
    ├── AnimationSystem.swift  # AnimationSystem
    ├── CaptureChessApp.swift  # ObjectCaptureSampleApp
    ├── SplashScreenView.swift  # SplashScreenView, RectangleGrid, RectangleRow
    ├── ContentView.swift  # ContentView, OverlayView, ContentView_Previews
    ├── Components.swift  # HasChessPiece, CheckerComponent, ChessPieceComponent
    └── ChessViewport.swift  # ChessViewport, GestureView

Structure observations

• The runtime boundary is WindowGroup + SwiftUI/UIKit host; the tree is pruned to lifecycle, state, framework, rendering, and ECS files.
• The source is Metal, Swift; role-named types and feature folders separate the major responsibilities.

Overall architecture

flowchart LR
    ObjectCaptureSampleApp_1["ObjectCaptureSampleApp"]
    WindowGroup___SwiftUI_UIKit_host_2["WindowGroup + SwiftUI/UIKit host"]
    ContentView_3["ContentView"]
    GameManager_4["GameManager"]
    AnimationSystem_5["AnimationSystem"]
    RealityKit_entity_graph_6["RealityKit entity graph"]
    Object_Capture_assets___chess_ECS_7["Object Capture assets + chess ECS"]
    ObjectCaptureSampleApp_1 --> WindowGroup___SwiftUI_UIKit_host_2
    WindowGroup___SwiftUI_UIKit_host_2 --> ContentView_3
    ContentView_3 --> GameManager_4
    GameManager_4 --> AnimationSystem_5
    AnimationSystem_5 --> RealityKit_entity_graph_6
    RealityKit_entity_graph_6 --> Object_Capture_assets___chess_ECS_7

Reference code

CaptureChess/CaptureChessApp.swift:11 — executable or app-lifecycle anchor.

struct ObjectCaptureSampleApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

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 --> Player : turn
    ContentView o-- GameManager : gameManager
    GameManager --> State : state
    GameManager *-- GameManager : shared

Ownership evidence

CaptureChess/GameManager.swift:17 — representative stored state or nearest verified lifecycle anchor.

    @Published var turn: ChessGame.Player = .player1
    
    @Published var selectedPiece: ChessPiece?
    @Published var game: ChessGame = ChessGame()
    
    @Published var okayToStart = false
    @Published var loadProgress: Float = 0

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: ChessPiece → HasChessPiece. 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.

Reference code

CaptureChess/ChessViewport.swift:17 — representative visibility boundary.

class ChessViewport: ARView {
    // ...
    private let gameManager: GameManager
    // ...
}

Logic ownership and placement

Design patterns

Naming conventions

• Role suffixes are evidence, not decoration: App: ObjectCaptureSampleApp; Manager: GameManager; System: AnimationSystem; Component: CheckerComponent, ChessPieceComponent; View: ContentView, GestureView, OverlayView, SplashScreenView.
• ECS names pair data and behavior: components CheckerComponent, ChessPieceComponent; systems AnimationSystem.
• Protocols: HasChessPiece.
• Commands use verb-led methods: incrementPiecesLoaded, update, handleTap, handleDoubleTap, handlePan, handleRotation, handlePinch, moveBoard.
• 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 ObjectCaptureSampleApp 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.

Source map

• Official Apple documentation