How osv22/spatial-vacuum works
Project Type and Purpose
• Spatial Vacuum is an AR/VR iOS app (built with SwiftUI + RealityKit/ARKit) whose goal is to let users “vacuum” virtual coins in their real environment.
• It follows an MVVM‑style front end entwined with RealityKit’s ECS (Entity‑Component-System).
File Structure
• Top‑level:
• SpatialSweeper.xcodeproj + Info.plist → standard Xcode project files.
• SpatialSweeper/… → application code (SwiftUI views, view model, RealityKit controller, systems).
• Packages/RealityKitContent → a Swift Package containing 3D assets (.usdz, .usda), audio, materials, and the Package.swift manifest.
• AssetProjects/… → source .blend files for 3D models.
• Key patterns: MVVM in SwiftUI, RealityKit’s ECS for 3D content, use of a separate Swift Package for RealityKit assets.
README
• Confirms MVVM/RealityKit: mentions “SweeperRealityController,” hand‑tracking maintenance notes, and the coin‑collection logic.
• Credits point to external tutorials and asset origins but no additional sub‑services.
Main Components
a. SwiftUI Layer (Views + ViewModel)
• ContentView, HomeView, AboutView, custom View Components (buttons, selectors).
• AppViewModel: publishes UI state (selected vacuum type, score).
b. RealityKit / ARKit Layer
• SweeperRealityController: manages ARSession, anchors, entity creation/destruction.
• RotateSystem / RotateComponent: RealityKit ECS system for animating models.
• Hand‑tracking subsystem: processes ARFrame data, computes transforms for hand visualization.
c. Asset Package
• RealityKitContent Swift Package: holds assets (models, materials, sounds).
• Loaded at runtime by SweeperRealityController.
d. iOS Platform Services
• ARKit & camera feed
• Device sensors (motion, depth if available)
e. External Dependencies
• No remote web services; all logic and assets reside locally.
Model Interactions and Data Flow
• User taps PlayButton in SwiftUI → AppViewModel updates “isSessionRunning”
• AppViewModel notifies SweeperRealityController → starts ARSession
• SweeperRealityController loads assets from RealityKitContent → instantiates Entities in AR Scene
• ARKit delivers ARFrame to SweeperRealityController → hand tracking logic updates entity transforms (RotateSystem)
• Collision events (coin collected) → RealityKit notifies controller → AppViewModel increments score → SwiftUI updates scoreboard
• On ‘Real’ vacuum selection → scoreboard anchored to head instead of world.
Architectural Patterns
• MVVM: separation of View ↔ ViewModel ↔ Model/Controller
• RealityKit Entity‑Component‑System: discrete systems (RotateSystem) operate on components (RotateComponent)
• Modular asset distribution via Swift Package (RealityKitContent)
Essential Elements
• Annotations for special cases (e.g., “if Real vacuum: attach scoreboard to head anchor”).