Native Architecture

Decision

Use SwiftUI for the application shell and HUD, with RealityKit hosted in a non-AR ARView for the interactive 3D mechanism. The minimum target is iOS 18.

RealityKit is presentation. The domain model is a deterministic state machine built on integer grid points.

flowchart TD
    Input["Tap / drag / axis input"] --> Session["GameSession"]
    Session --> Rules["Grid paths + occupancy"]
    Rules --> Snapshot["GameSnapshot"]
    Snapshot --> Scene["RealityKit renderer"]
    Snapshot --> HUD["SwiftUI HUD"]

Domain model

• LevelDefinition owns bounds and ordered PieceDefinition values.
• Each piece owns one or more PathDefinition values.
• A path can be available for every axis or require X/Z.
• GameSnapshot stores origins, extracted IDs, the selected ID, and the axis state.
• Occupancy is evaluated at grid origins. This is deliberate for the prototype; future compound footprints should remain grid-based.

Move transaction

1. Resolve the selected piece's active path.

2. Walk nodes in the drag direction.

3. Stop at the first occupied in-bounds node.

4. If no node was entered, emit blocked feedback and leave the snapshot unchanged.

5. Otherwise commit the last legal node, or mark the piece extracted after it exits bounds.

6. Store the previous snapshot for undo.

Axis transaction

1. Create a candidate snapshot with the target axis.

2. For every non-extracted piece, require exactly one active path containing its current origin.

3. Reject the entire transition if any piece fails.

4. Commit once, animate the ring once, and preserve the old path briefly as a ghost.

Rendering

• A camera-relative root provides a stable product-shot presentation on device and simulator.
• Piece geometry is assembled from rounded box primitives and rivets.
• PhysicallyBasedMaterial supplies metalness and roughness; unlit cyan/amber geometry preserves route readability.
• Entity transforms are derived only from committed snapshots.
• Hit-test names map scene entities back to stable domain IDs.

Scaling path

• Load level definitions from versioned JSON after the prototype rules settle.
• Add multi-cell piece footprints before introducing more complex shapes.
• Add a level validator that proves each route is contiguous and each start cell is unique.
• Add replay serialization for debugging and analytics without capturing gestures.
• Replace procedural pieces selectively with optimized USDZ assets, preserving entity IDs and pivots.