Untold Engine is an open-source Swift/Metal XR engine for high-performance Apple-platform spatial visualization apps, giving developers full control over rendering, shaders, and the engine pipeline.
Untold Engine is built for developers and teams who:
- Need full control over Metal rendering, shaders, and engine systems
- Prefer a native Swift + Metal architecture on Apple platforms
- Are building XR, 3D, or spatial visualization applications
- Need to handle large scenes, streaming data, or custom asset pipelines
- Want an open engine they can inspect, modify, extend, and embed
Creator & Lead Developer:
https://www.haroldserrano.com
Untold Engine is designed for developers building custom spatial visualization software on Apple platforms, including:
- Vision Pro and spatial computing apps
- Architectural walkthroughs and large-scene visualizers
- Product configurators and digital showrooms
- Industrial visualization and digital twin viewers
- Training simulators and interactive 3D tools
- Custom rendering pipelines and research prototypes
The engine owns the rendering and XR foundation. Your app owns the vertical workflow, product experience, and customer-specific behavior.
 |
 |
 |
 |
 |
The best first step is to run the Starter Demo. It is intentionally small and shows the basic shape of an Untold Engine app without the extra systems used by the larger showcase.
Recommendation: Use the latest stable release instead of the
developbranch. Thedevelopbranch is the bleeding-edge version of Untold Engine and is updated frequently, so it may contain unstable changes or regressions.
Clone the repository and launch the Starter Demo:
git clone https://github.com/untoldengine/UntoldEngine.git
cd UntoldEngine
git checkout v0.14.3
swift run StarterDemoAfter that, run the focused demos based on what you want to learn:
| Demo | Command | Start here when you want to learn |
|---|---|---|
| Starter Demo | swift run StarterDemo |
The minimal app structure: renderer setup, camera, light, input, and a simple scene. |
| Interaction / Gameplay Demo | swift run InteractionGameplayDemo |
Gameplay-style movement, input handling, animation switching, physics pause/resume, and parented entities. |
| Lighting Demo | swift run LightingDemo |
All four light types — directional, point, spot, and area — with live intensity and cone-angle controls. |
| Rendering Quality Demo | swift run RenderingQualityDemo |
Post-processing controls such as color grading, SSAO, bloom, vignette, depth of field, anti-aliasing, and debug views. |
| Large Scene Streaming Demo | swift run LargeSceneStreamingDemo |
Manifest-driven tiled scene streaming, LOD, batching, streaming stats, and large-world traversal. |
| Exporter Pipeline Demo | swift run ExporterPipelineDemo |
Loading exported .untold assets, applying exported animation clips, and checking validation metadata. |
| Showcase Demo | swift run ShowcaseDemo |
A broader engine showcase that combines many systems in one app. Use this after the focused demos. |
The demos live under Sources/Demos. They are runnable when working inside the
engine repository, but are not exposed as products to apps that add Untold
Engine as a package dependency.
To create your own XR, 3D, or spatial visualization app using Untold Engine, see Getting Started.
Untold Engine is built around three focused goals:
-
Spatial Engine First — Designed for spatial computing applications. LOD, geometry streaming, and static batching exist to support large, real-world-scale environments where presence and performance both matter.
-
XR / visionOS Support — Spatial input, AR workflows, and Vision Pro support are functional today and expanding with each release.
-
Metal-First Architecture — The rendering layer stays close to Metal to maintain performance, shader control, and pipeline flexibility without abstraction layers getting in the way.
Untold Engine is well-suited for:
- Vision Pro and ARKit-based visualization apps
- Large-scale scene visualization: interiors, archviz, cities, datasets
- Product configurators and digital showrooms
- Industrial visualization and digital twin viewers
- Simulation tools and training applications
- Custom rendering pipelines and graphics experiments
- Apple Platform Coverage — Unified Swift + Metal codebase for macOS, iOS, and visionOS
- Rendering Pipeline Control — Metal renderer with PBR/IBL workflows, shader-level control, rendering extensions, 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
Untold Engine is open source under MPL-2.0 and can be used in commercial apps. Paid commercial options are available for teams that need private engine modifications, sponsored engine features, priority support, or custom terms.
- Sponsored open-source features — fund roadmap-aligned engine work that is released into the public MPL engine.
- Commercial license — keep private modifications to engine internals closed under commercial terms.
- Priority support / retainers — get focused help with engine integration, rendering issues, performance, and production use.
See COMMERCIAL.md for commercial licensing details.
- Getting Started
- Create Project with CLI
- Registration System
- Transform System
- Scenegraph
- Camera System
- Input System
- Rendering System
- Materials
- Lighting System
- Animation System
- Physics System
- Steering System
- Post FX
- LOD System
- Static Batching System
- LOD-Batching-Streaming
- Geometry Streaming System
- Async Loading
- Spatial Input
- XR Immersion Modes
- Light Portals
- Rendering Extensions
- Rendering Extension Examples
- Create a Rendering Extension Plugin
- Gaussian System
- Profiler
- Spatial Debugger
- Asset Exporter
- Bake Materials
- Color Management
- Optimizations
- Rendering System
- Rendering Extensions
- XR Rendering System
- Out of Core
- Geometry Streaming System
- Streaming Cache Lifecycle
- Texture Streaming System
- Progressive Asset Loader
- Asset Remote Streaming
- Static Batching System
- LOD System
See open issues for planned features and known improvements.
For help or questions, open a GitHub Issue.
Contributions are welcome — whether that's fixing bugs, improving systems, writing documentation, or proposing ideas.
Before submitting a pull request, please review the Contributing Guidelines.
All contributions are licensed under MPL-2.0.
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 for details.
A huge thanks to the people helping shape the Untold Engine.
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 commercial apps | Yes | App code can remain proprietary |
| Build games | Yes | Game code can remain proprietary |
| Use engine unmodified in a commercial product | Yes | No royalties |
| Modify engine files | Yes | Modified engine files remain MPL when distributed |
| Keep engine modifications private | Commercial license required | See COMMERCIAL.md |
| Create plugins | Yes | Any license allowed |
Full license: https://www.mozilla.org/MPL/2.0/
Need private engine modifications, sponsored feature work, or priority support? See COMMERCIAL.md for details.
"Untold Engine" and the Untold Engine logo are trademarks of Untold Engine Studios. Forks may not use the name in a way that implies official endorsement. See TRADEMARKS.md.
- GitHub Discussions — ideas and questions
- GitHub Issues — bugs and tasks