UntoldEngine
An easy to use, Open-Source, 3D game engine for iOS/macOS game development.
Install / Use
/learn @untoldengine/UntoldEngineREADME
Untold Engine
Untold Engine is an open-source 3D engine written in Swift and powered by Metal, designed for Apple platforms including macOS, iOS, and visionOS.
The project focuses on building a clean, system-driven architecture with modern rendering, an ECS-based gameplay model, and an extensible asset pipeline.
The engine is under active development and continues to evolve as new systems and workflows are added.
🎯 Who is this for?
Untold Engine is designed for developers who:
- Want full control over rendering and systems
- Prefer working directly with Swift + Metal
- Are building XR, 3D, or visualization applications
- Need to handle large scenes, streaming data, or custom pipelines
This is not a drag-and-drop editor-first engine — it is a code-driven engine for developers who want to understand and shape the system.
Check out these videos to see the engine capabilities using the Vision Pro
Creator & Lead Developer:
http://www.haroldserrano.com
🚀 Try the Engine Right Now
The fastest way to experience Untold Engine is to run the demo project.
Clone the repository, run the engine and load a USDZ file:
git clone https://github.com/untoldengine/UntoldEngine.git
cd UntoldEngine
swift run untoldsandbox
Legacy alias (prints deprecation warning):
swift run DemoGame
This will:
- Build the engine using Swift Package Manager
- Compile the demo project
- Launch the demo so you can see the engine running immediately
No additional setup is required.
🧱 Core Direction
Untold Engine is being developed with the following goals:
-
Large Scene Rendering
Striving to support LOD, geometry streaming, batching, and memory-aware systems for large datasets -
XR / visionOS Support
Expanding support for spatial input, AR workflows, and Vision Pro experiences -
Metal-First Architecture
Keeping the rendering layer close to Metal to maintain performance and control
🖼 Example Use Cases
Untold Engine aims to support applications such as:
- XR applications (Vision Pro, ARKit-based apps)
- Large-scale scene visualization (cities, archviz, datasets)
- Custom rendering pipelines and experiments
- Simulation tools and interactive 3D systems
Current Features
- Apple Platform Coverage: Unified Swift + Metal codebase for macOS, iOS, and visionOS
- Rendering Pipeline: Metal renderer with PBR/IBL workflows and post-processing across standard and XR paths
- AR and XR Runtime Support: Built-in AR workflows plus visionOS integration and spatial interaction support
- ECS + Scene Graph Core: Component-based architecture with hierarchical transforms and scene root transform controls
- Async Content Loading: Asynchronous loading pipeline for scenes and assets to improve responsiveness on large worlds
- LOD and Streaming: LOD support with geometry streaming, streaming regions, and memory budget management
- Static Batching and Culling: Static batching, octree acceleration, and occlusion culling for large-scene performance
- Advanced Picking: Scene, ground, and GPU ray picking with octree-backed intersection paths
- Spatial Input Features: XR spatial input helpers including anchored pinch drag, distance tracking, and two-hand rotation
- Scripting System (USC): Untold Script Core with multi-script support plus camera, math, and physics APIs (Experimental)
- Gameplay Systems: Physics, animation, camera waypoint, and input systems (keyboard, mouse, touch, and gamepad)
- Gaussian Splat Rendering: Native Metal support for rendering and compositing 3D Gaussian content
- Tooling Integration: Optional Untold Editor workflow and Swift Package Manager integration
Engine API
- Getting Started
- Registration System
- Scenegraph
- Transform System
- Camera System
- Rendering System
- Lighting System
- Materials
- Input System
- Physics System
- Steering System
- Animation System
- Async Loading
- LOD System
- Static Batching System
- Geometry Streaming System
- LOD-Batching-Streaming
- Spatial Input
- Gaussian System
- Spatical Debugger
- Profiler
Engine Architecture:
- Rendering System
- XR Rendering System
- Static Batching System
- Geometry Streaming System
- LOD System
- Progressive Asset Loader
- Streaming Cache Lifecycle
- Texture Streaming System
- Out of Core
Set Up an Xcode Project with Untold Engine
Use untoldengine-create to generate a ready-to-run Xcode project with Untold Engine wired in.
Install it from the repository:
git clone https://github.com/untoldengine/UntoldEngine.git
cd UntoldEngine
./scripts/install-untoldengine-create.sh
Vision Pro Example
mkdir VisionGame
cd VisionGame
untoldengine-create create VisionGame --platform visionos
open VisionGame.xcodeproj
What this creates for you
- Xcode project + platform-specific app template files
GameDatafolder structure (Scenes,Scripts,Models,Textures, etc.)- Engine package dependencies configured for the selected platform
- Starter
GameScenecode showing how to:- Load a mesh (
city.usdz) - Enable geometry streaming
- Enable static batching
- Load a mesh (
Note: city.usdz should be placed in GameData/model (generated folder name is GameData/Models).
Platform options
# visionOS (Apple Vision Pro)
untoldengine-create create MyGame --platform visionos
# macOS (default)
untoldengine-create create MyGame --platform macos
# iOS with ARKit
untoldengine-create create MyGame --platform iosar
# iOS
untoldengine-create create MyGame --platform ios
Dependency behavior by platform:
visionos:UntoldEngineXR+UntoldEngineARiosar:UntoldEngineARiosandmacos:UntoldEngine
Roadmap
See open issues for planned features and improvements.
Feature Requests
https://github.com/untoldengine/UntoldEngine/issues?q=label%3Aenhancement
Bug Reports
https://github.com/untoldengine/UntoldEngine/issues?q=label%3Abug
Support
For help or questions use GitHub Issues.
https://github.com/untoldengine/UntoldEngine/issues
Contributing
Contributions are welcome.
You can help by:
- Fixing bugs
- Improving systems such as rendering, physics, or ECS
- Writing documentation
- Proposing new ideas
Before submitting a pull request please read:
- CONTRIBUTING.md
- CONTRIBUTOR_LICENSE_AGREEMENT.md
- Contributing Guidelines
- Formatting
- Versioning
All contributions are licensed under MPL-2.0.
Contributor License Agreement
To ensure the long-term sustainability of the project, contributors must agree to the CLA.
By submitting a pull request you agree that your contributions may be distributed under the Mozilla Public License 2.0.
See:
CONTRIBUTOR_LICENSE_AGREEMENT.md
GitHub Sponsors
A huge thanks to the people helping shape the Untold Engine.
<p align="center"> <a href="https://github.com/miolabs"> <img src="docs/images/top_contributors/MioLogo.png" alt="MioLabs" width="120"/> </a> </p>License
Untold Engine is licensed under the Mozilla Public License 2.0 (MPL-2.0).
This allows developers to build commercial applications while ensuring improvements to the engine itself remain open.
| Use Case | Allowed | Obligation | |----------|--------|-----------| | Build games | Yes | Game code can remain pr
