Tracking a handheld accessory as a virtual sculpting tool

At a glance

Project structure

Source bundle/
└── SpatialSculpting/
    └── SpatialSculpting/
        ├── ViewModel/
        │   ├── SculptingToolModel.swift  # SculptingToolModel
        │   └── HapticsModel.swift  # HapticsModel
        ├── Document/
        │   └── VolumeDocument.swift  # VolumeDocumentError, VolumeDocument
        ├── SpatialSculptingApp.swift  # SpatialSculptingApp
        ├── Compute/
        │   └── ComputeSystem.swift  # ComputeUpdateContext, ComputeSystem, ComputeSystemComponent
        ├── ContentView.swift  # ContentView
        └── ECS/
            └── SculptingToolComponent.swift  # SculptingMode, SculptingToolComponent, SculptingToolSystem

Structure observations

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

Overall architecture

flowchart LR
    SpatialSculptingApp_1["SpatialSculptingApp"]
    WindowGroup___volumetric_window___SwiftUI_UIKit_host_2["WindowGroup + volumetric window + SwiftUI/UIKit host"]
    ContentView_3["ContentView"]
    SculptingToolModel_4["SculptingToolModel"]
    SculptingToolSystem_5["SculptingToolSystem"]
    RealityKit_entity_graph_6["RealityKit entity graph"]
    accessory_tracking___compute_sculpting_7["accessory tracking + compute sculpting"]
    SpatialSculptingApp_1 --> WindowGroup___volumetric_window___SwiftUI_UIKit_host_2
    WindowGroup___volumetric_window___SwiftUI_UIKit_host_2 --> ContentView_3
    ContentView_3 --> SculptingToolModel_4
    SculptingToolModel_4 --> SculptingToolSystem_5
    SculptingToolSystem_5 --> RealityKit_entity_graph_6
    RealityKit_entity_graph_6 --> accessory_tracking___compute_sculpting_7

Reference code

SpatialSculpting/SpatialSculpting/SpatialSculptingApp.swift:11 — executable or app-lifecycle anchor.

struct SpatialSculptingApp: 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
    ContentView *-- VolumeDocument : saveDocument
    SculptingToolModel --> Entity : rootEntity
    SculptingToolModel --> AnchorEntity : sculptingEntity
    SculptingToolModel --> ModelEntity : trackingStateIndicator

Ownership evidence

SpatialSculpting/SpatialSculpting/ContentView.swift:23 — representative stored state or nearest verified lifecycle anchor.

struct ContentView: View {
    // ...
    @State var saveDocument: VolumeDocument? = nil
    // ...
}

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: SculptingToolSystem → ComputeSystem. Framework conformances remain adapters, not proof of an app-wide protocol architecture.

Access control

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

Objective-C/C header and implementation visibility is documented separately from Swift lexical access control.

Reference code

SpatialSculpting/SpatialSculpting/Mesh/MarchingCubesMesh.swift:27 — representative visibility boundary.

    private let marchPipeline: MTLComputePipelineState = makeComputePipeline(named: "march")!
    // Compute pipeline corresponding to the Metal compute shader function `clear`.
    //
    // See `MarchingCubesCompute.metal`.
    private let clearPipeline: MTLComputePipelineState = makeComputePipeline(named: "clear")!

Logic ownership and placement

Design patterns

Naming conventions

• Role suffixes are evidence, not decoration: App: SpatialSculptingApp; Model: HapticsModel, SculptingToolModel; Document: VolumeDocument; System: ComputeDispatchSystem, ComputeSystem, SculptingToolSystem; Component: ComputeSystemComponent, SculptingToolComponent.
• ECS names pair data and behavior: components ComputeSystemComponent, SculptingToolComponent; systems ComputeDispatchSystem, SculptingToolSystem.
• Protocols: ComputeSystem.
• Commands use verb-led methods: selectToolbarElement, displayToolbar, handlePalettePress, updateTrackingStateIndicatorIfDirty, updateSculptingTool, addEntityAttachmentToRoot, loadFromURL, fileWrapper.
• 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 SpatialSculptingApp 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