Placing content on detected planes

At a glance

Project structure

Source bundle/
└── ObjectPlacement/
    ├── App/
    │   ├── PlacementManager.swift  # PlacementManager
    │   └── AppState.swift  # AppState
    ├── Utilities/
    │   ├── PlaneAnchorHandler.swift  # PlaneAnchorHandler
    │   └── PersistenceManager.swift  # PersistenceManager
    ├── Views/
    │   ├── ObjectPlacementRealityView.swift  # ObjectPlacementRealityView, Attachments
    │   ├── HomeView.swift  # HomeView
    │   └── ObjectPlacementMenuView.swift  # ObjectPlacementMenuView
    └── ObjectPlacementApp.swift  # UIIdentifier, ObjectPlacementApp

Structure observations

• The runtime boundary is WindowGroup + 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.
• Uses the Object Placement archive but focuses on plane updates, ray projection, collision checks, and placement preview state.

Overall architecture

flowchart LR
    ObjectPlacementApp_1["ObjectPlacementApp"]
    WindowGroup___ImmersiveSpace_2["WindowGroup + ImmersiveSpace"]
    HomeView_3["HomeView"]
    AppState_4["AppState"]
    RealityView_entity_graph_5["RealityView entity graph"]
    ARKit_providers___RealityKit_6["ARKit providers + RealityKit"]
    ObjectPlacementApp_1 --> WindowGroup___ImmersiveSpace_2
    WindowGroup___ImmersiveSpace_2 --> HomeView_3
    HomeView_3 --> AppState_4
    AppState_4 --> RealityView_entity_graph_5
    RealityView_entity_graph_5 --> ARKit_providers___RealityKit_6

Reference code

ObjectPlacement/ObjectPlacementApp.swift:16 — the app or executable entry declares the outer scene lifecycle.

struct ObjectPlacementApp: 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
    ObjectPlacementApp *-- AppState : appState
    ObjectPlacementApp *-- ModelLoader : modelLoader
    ObjectPlacementApp o-- ScenePhase : scenePhase
    HomeView --> AppState : appState

Ownership evidence

ObjectPlacement/ObjectPlacementApp.swift:17 — representative stored state or the nearest verified lifecycle anchor.

    @State private var appState = AppState()

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 open; unmodified Swift declarations are internal.

Reference code

ObjectPlacement/App/AppState.swift:16 — representative visibility boundary.

    private(set) weak var placementManager: PlacementManager? = nil

    private(set) var placeableObjectsByFileName: [String: PlaceableObject] = [:]
    private(set) var modelDescriptors: [ModelDescriptor] = []
    var selectedFileName: String?

Logic ownership and placement

Design patterns

Naming conventions

• Role suffixes are evidence, not decoration: App: ObjectPlacementApp; Manager: PersistenceManager, PlacementManager; View: HomeView, ObjectPlacementMenuView, ObjectPlacementRealityView, ObjectSelectionView, TooltipView.
• Protocols: no app-defined protocol in the reviewed source.
• Commands use verb-led methods: saveWorldAnchorsObjectsMapToDisk, addPlacementTooltip, removeHighlightedObject, runARKitSession, collisionBegan, collisionEnded, select, processWorldAnchorUpdates.
• Files generally match their primary type; Views, Models, Managers, Providers, Components, Systems, and Packages folders describe architectural roles where present.

Architecture takeaways

• Treat ObjectPlacementApp 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.
• Run ARKit providers for the scene lifetime and consume their asynchronous updates in cancellable tasks; map anchors to entities at the boundary.
• Model immersive-space open, transition, and close states explicitly so windows and immersive content cannot drift apart.

Source map

• Official Apple documentation