🎮 UntoldArcade

UntoldArcade is the demo playground for the Untold Engine — a real, running Xcode project for every major thing the engine can do, from mixed-reality digital twins to GPU cloth you can punch a ball through.

Clone it, open a folder, hit ⌘R, and you're looking at the feature instead of reading about it.

---

📺 Demos

Each demo is a standalone Xcode project with its own README, tutorial, and bundled assets — no setup beyond opening the .xcodeproj. The four Rendering Extensions (CoolSaber, CoolWater, CoolCloth, CoolWeb) are reusable plugins — each ships its own shader library, pipelines, and render-graph passes, and can be dropped into any project.

⚔️ CoolSaber — visionOS · Rendering Extension

Lightsaber duels driven by PSVR2 Sense controllers — pull the trigger to ignite a glowing blade, then duel a friend over SharePlay with clashing sparks, haptic kicks, and synthesized saber audio. Requires a physical Vision Pro (the deferred G-buffer exceeds simulator tile memory).

open CoolSaber/Examples/CoolSaberVisionOS/CoolSaberVisionOS.xcodeproj

💧 CoolWater — visionOS · Rendering Extension

Real-time animated water with reflection/refraction and ripple simulation.

open CoolWater/Examples/CoolWaterVisionOS/CoolWaterVisionOS.xcodeproj

🧵 CoolCloth — visionOS · Rendering Extension

GPU cloth simulation (XPBD, small-steps scheme) hanging in your real room — pinch it to grab a particle, throw a ball through it, switch materials live, and let real furniture occlude it.

open CoolCloth/Examples/CoolClothVisionOS/CoolClothVisionOS.xcodeproj

🕸️ CoolWeb — visionOS · Rendering Extension

A Spider-Man web-shooter demo — strike the classic web-shooter pose (thumb, index and pinky extended, middle and ring curled) and a web line fires from your wrist, blooms into a net on the surface it hits, and stays tethered to your hand until you open your palm to release it. Requires a physical Vision Pro (hand tracking and scene reconstruction aren't available in the simulator).

open CoolWeb/Examples/CoolWebVisionOS/CoolWebVisionOS.xcodeproj

🏀 CoolBasket — visionOS · Physics Backend

Mixed-reality basketball, and the first consumer of the engine's physics backend plugin seam: a pure-Swift PhysicsBackend simulates the ball against your real floor, walls and furniture (ARKit plane detection), the hoop you place in your room, and your hands. Look at the floor and pinch to place the hoop, pinch near the ball to pick it up, flick to throw — a shot only counts when it comes down through the rim.

• PhysicsBackendPlugin installed before renderer creation, driven by the engine's PhysicsCoordinator — zero engine changes
• Rigid bodies, static colliders and trigger volumes expressed with the engine-owned RigidBodyComponent/ColliderComponent
• Contact and trigger events delivered through PhysicsEvents

open CoolBasket/Examples/CoolBasketVisionOS/CoolBasketVisionOS.xcodeproj

🧲 UntoldJoltPhysics — plugin · Physics Backend

Jolt Physics behind the engine's physics backend seam, as a Swift package every demo can depend on: untoldengine/UntoldJoltPhysics. Jolt comes as source from the untoldengine/JoltPhysics fork (the upstream tree plus a Package.swift) and SwiftPM compiles it — no binaries — for macOS, iOS and visionOS. CoolBasket can run on it instead of its built-in backend: pick "Jolt Physics" in its control window.

.package(url: "https://github.com/untoldengine/UntoldJoltPhysics.git", branch: "develop")

🏛️ ArchvizViewer — visionOS

Load a Blender-authored architectural visualization straight into mixed reality — lights, camera, and color management carried over exactly as the artist set them up. Pinch-drag and two-hand rotate to walk the scene around your room. Reference project for the Archviz To Vision Pro tutorial.

• Async, non-blocking model loading (setEntityMeshAsync)
• Blender-authored lights/camera/color management (loadSceneAuthored)
• Vision Pro spatial picking and two-hand scene rotation

open ArchvizViewer/ArchvizViewer.xcodeproj

🛋️ BedroomTwin — visionOS

A digital twin of a bedroom: the same room model, but different parts of it behave differently. The window becomes a passthrough light portal; the lamps, door, curtains, and laptop stay individually tappable and carry live mock status data. Reference project for the Bedroom Digital Twin tutorial.

• SceneChannel splitting geometry into context / window / selectable objects by naming convention
• Light-portal + passthrough ghost rendering on the window channel
• Per-object tap selection resolved against mock digital-twin status data

open BedroomTwin/BedroomTwin.xcodeproj

🏙️ CityStreaming — visionOS

A city too big to fit in GPU memory, streamed in tile by tile as you walk through it — nearby tiles load at full detail, distant ones fall back to LOD/HLOD, and static batching updates incrementally in the background. Reference project for City Streaming On Vision Pro.

• Tiled streaming manifests (setEntityStreamScene) instead of one monolithic model
• Distance-based load/unload with LOD/HLOD fallback
• Spatial debug overlays for tile bounds, octree residency, and texture streaming tiers

open CityStreaming/CityStreaming.xcodeproj

🛠️ SceneBuilder — macOS / iOS

A declarative, SwiftUI-style syntax for building 3D scenes in code — cubes, PBR materials, and animated waves assembled without a scene editor.

open SceneBuilder/SceneBuilder.xcodeproj

🫧 SplatTwin — macOS

Mesh-to-Gaussian-splat twins: three objects cross-fade from their mesh to a splat "capture" as you walk up to them and back as you leave, while the mesh keeps writing depth as a shrunk occluder shell and keeps casting its shadow. The captures are synthesised at first launch, so nothing large ships. The swap policy is the demo's own code on the engine's public API, an example of extending the engine from outside; a HUD exposes the swap distance, fade, splat exposure and the occluder shells.

open SplatTwin/SplatTwin.xcodeproj

---

⚙️ Requirements

• Xcode 26.1 or later
• macOS 26.01+ (for macOS demos)
• iOS 26.01+ (for iOS demos)
• visionOS 26.01+ (for Vision Pro demos)
• Metal-capable GPU
• A physical Apple Vision Pro for CoolSaber (simulator can't run the deferred renderer's G-buffer) and CoolWeb (simulator has no hand tracking or scene reconstruction)

---

🚀 Getting Started

1. Clone the repo

git clone https://github.com/untoldengine/UntoldArcade.git
cd UntoldArcade

2. Open a demo project

Each demo is a standalone Xcode project. Navigate to the demo folder and open the .xcodeproj file — see the open command under each demo above.

Most demos generate their Xcode project from project.yml via XcodeGen. If you add/remove source files or change dependencies, re-run xcodegen generate inside that demo's folder before opening/building.

3. Build and run

• Select your target device (Mac, iPhone, iPad, or Vision Pro simulator)
• Press ⌘R to build and run
• SPM will automatically fetch the Untold Engine dependency on first build

🔗 Engine Dependency

Each demo project depends on the Untold Engine via Swift Package Manager (SPM). The workspace is already configured to fetch the engine from its develop branch on GitHub.

📂 Project Structure

UntoldArcade/
├── CoolSaber/           # Rendering Extension — PSVR2 lightsaber duels + SharePlay
├── CoolWater/           # Rendering Extension — real-time animated water
├── CoolCloth/           # Rendering Extension — GPU cloth simulation (XPBD)
├── CoolWeb/             # Rendering Extension — Spider-Man web-shooter demo
├── CoolBasket/          # Physics Backend — mixed-reality basketball on the plugin seam, on either backend
├── ArchvizViewer/       # visionOS — Blender archviz scene in mixed reality
├── BedroomTwin/         # visionOS — digital-twin bedroom with channel-based selection
├── CityStreaming/       # visionOS — tiled city streaming with LOD/HLOD
├── SceneBuilder/        # macOS/iOS — declarative scene-building demo
├── SplatTwin/           # macOS — mesh-to-Gaussian-splat twins
└── docs/media/          # Screenshots/GIFs/video referenced by this README

Each demo folder generally follows:

<Demo>/
├── project.yml               # XcodeGen config (where used)
├── README.md                 # Demo-specific overview + what it teaches
└── Sources/<Demo>/
    ├── <Demo>App.swift        # App entry point
    ├── GameScene.swift        # Scene setup, input, per-frame logic
    └── GameData/               # Bundled models, textures, HDRs, streamed tiles

🤝 Contributing

We welcome contributions! If you'd like to:

• Add a new demo game
• Improve existing demos
• Enhance documentation

Please fork the repo, open a PR, or join discussions in the Untold Engine repo.

📜 License

This project follows the same license as Untold Engine. See the LICENSE file for details.