Skip to content

About

Open-source Swift/Metal 3D engine for macOS, iOS, and Vision Pro, with full control over rendering, shaders, and the engine pipeline.

Topics

Resources

Code of conduct

Contributing

Stars

146 stars

Watchers

4 watching

Forks

Latest commit

 

History

3,841 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Build Status Project license Pull Requests welcome Version Commits Last Commit


Untold Engine

Full control over rendering. Built for Apple platforms.

Untold Engine is an open-source Swift and Metal engine for macOS, iOS, and Apple Vision Pro. Build exactly the visuals and performance your app needs — with direct access to shaders, the rendering pipeline, physics, and input.

Creator & Lead Developer:
https://www.haroldserrano.com

State of the Engine 2026


Built For

Untold Engine is built for developers and teams who:

  • Need full control over Metal rendering, shaders, physics, and engine systems
  • Prefer a native Swift + Metal architecture on Apple platforms
  • Are building 3D, XR, or spatial applications/games with requirements beyond standard tools
  • Need to handle large scenes, streaming data, or custom asset pipelines
  • Want an open engine they can inspect, modify, extend, and embed

Untold Engine is well-suited for:

  • Custom rendering pipelines — rendering extensions, and shader-level control
  • Interactive XR experiences on Vision Pro — hand tracking, physics, and gameplay built on ARKit

The engine owns the rendering and XR foundation. Your app owns the vertical workflow, product experience, and customer-specific behavior.


Extend the Renderer

Untold Engine is designed to be extended. Add your own shaders, materials, and render passes — or plug in entirely new rendering techniques — without forking the engine.


Watch It in Action — Apple Vision Pro Demos

Custom Rendering

Demo Description
CoolWater Real-time animated water with reflection, refraction, and ripples
CoolCloth GPU cloth simulation (XPBD) you can punch a ball through
CoolSaber PSVR2-driven energy-blade duels, blades clashing over SharePlay[

Large Scenes & Digital Twins

Demo Description
City Streaming City-scale scene streamed in tile by tile with LOD/HLOD
Archviz Viewer Blender-authored architectural scene walked through in mixed reality
Bedroom Digital Twin Tap-to-inspect digital twin bedroom with live mock status data

Interactive XR

Demo Description
CoolSaber PSVR2-driven energy-blade duels, blades clashing over SharePlay
CoolWeb Web-shooter — gesture-triggered webs that stick to real room geometry
CoolMirror Virtual mirror — a rigged character mimics your real-world motion via iPhone + headset tracking
CoolBasket Mixed-reality basketball — first demo on the engine's pluggable physics backend seam
CoolBowling Mixed-reality bowling with Jolt Physics rigid-body pins you knock down for real
ImmersiveGol Mixed-reality penalty shootout — save shots from an animated kicker with your tracked hands
CoolFutbol Mixed-reality tabletop soccer controlled with a PSVR2 Sense controller

Full source for the demos lives in the UntoldArcade repo.


Current Features

  • Rendering Pipeline Control — Metal renderer with PBR/IBL workflows, shader-level control, rendering extensions, and post-processing across standard and XR paths
  • Gaussian Splat Rendering — Native Metal support for rendering and compositing 3D Gaussian content
  • 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
  • Async Content Loading — Asynchronous loading pipeline for scenes and assets to improve responsiveness on large worlds
  • Apple Platform Coverage — Unified Swift + Metal codebase for macOS, iOS, and visionOS
  • AR and XR Runtime Support — Built-in AR workflows plus visionOS integration and spatial interaction support
  • Spatial Input Features — XR spatial input helpers including anchored pinch drag, distance tracking, and two-hand rotation
  • Advanced Picking — Scene, ground, and GPU ray picking with octree-backed intersection paths
  • ECS + Scene Graph Core — Component-based architecture with hierarchical transforms and scene root transform controls
  • Gameplay Systems — Physics, animation, camera waypoint, and input systems (keyboard, mouse, touch, and gamepad)
  • Scripting System (USC) — Untold Script Core with multi-script support plus camera, math, and physics APIs (Experimental)
  • Tooling Integration — Optional Untold Editor workflow and Swift Package Manager integration

Requirements

  • macOS 26 or newer
  • Swift 6 / Xcode 26 or newer
  • Apple Silicon Mac
  • Supported platforms: macOS, iOS, and visionOS

Getting Started

For Game/App Developers

Build your own 3D, XR, or spatial app with Untold Engine as a dependency — no need to clone the engine repository. Pick the path that fits how you like to work:

Both guides take you from nothing installed to a running app with a cube you can move in code, and end with pointers to the full Building Your First Vision Pro Scene and the Tutorials.

For Contributors

Fixing bugs, adding engine features, or working on the engine's own source? Clone the engine repository itself.

Recommendation: Use the latest stable release instead of the develop branch. The develop branch is the bleeding-edge version of Untold Engine and is updated frequently, so it may contain unstable changes or regressions.

git clone https://github.com/untoldengine/UntoldEngine.git
cd UntoldEngine
git checkout v0.25.1
swift run StarterDemo

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.

Engineering Principles

Reliability · Testing · Simplicity · Compatibility · Developer Experience · Performance

These principles guide how we design, build, test, and maintain Untold Engine. The engine is backed by 1,000+ tests across rendering, animation, streaming, and physics.

Read our Engineering Principles for the standards that guide our development decisions.


Engine API


Engine Architecture


Contributing

Contributions are welcome — whether that's fixing bugs, improving systems, writing documentation, or proposing ideas.

All contributions are expected to follow our Engineering Principles.

Before submitting a pull request, please review the Contributing Guidelines.

All contributions are licensed under MPL-2.0.

Roadmap

See open issues for planned features and known improvements.

Contributor License Agreement

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.


GitHub Sponsors

A huge thanks to the people helping shape the Untold Engine.

MioLabs


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 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/


Custom Development, Commercial Use, and Support

Need a rendering capability that doesn't exist yet? Untold Engine is open source under MPL-2.0 and can be used in commercial apps. For teams that need more, paid options are available:

  • Custom rendering development — new rendering features, custom pipelines, and performance work for your app, starting with a focused, paid proof of concept (typically 1–2 weeks).
  • 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.

To discuss your project, contact Harold Serrano. See COMMERCIAL.md for commercial licensing details.


Trademark

"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.


Community

For help or questions, open a GitHub Issue.

About

Open-source Swift/Metal 3D engine for macOS, iOS, and Vision Pro, with full control over rendering, shaders, and the engine pipeline.

Topics

Resources

Code of conduct

Contributing

Stars

146 stars

Watchers

4 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages