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.

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.

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

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.

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

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

• 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

• 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

• 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

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

mkdir VisionGame
cd VisionGame
untoldengine-create create VisionGame --platform visionos
open VisionGame.xcodeproj

• Xcode project + platform-specific app template files
• GameData folder structure (Scenes, Scripts, Models, Textures, etc.)
• Engine package dependencies configured for the selected platform
• Starter GameScene code showing how to:
  • Load a mesh (city.usdz)
  • Enable geometry streaming
  • Enable static batching

Note: city.usdz should be placed in GameData/model (generated folder name is GameData/Models).

# 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 + UntoldEngineAR
• iosar: UntoldEngineAR
• ios and macos: UntoldEngine

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

For help or questions use GitHub Issues.

https://github.com/untoldengine/UntoldEngine/issues

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.

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

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.

Full license text:

https://www.mozilla.org/MPL/2.0/

“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

Use GitHub Discussions for ideas and questions:

https://github.com/untoldengine/UntoldEngine/discussions

Use GitHub Issues for bugs and tasks:

https://github.com/untoldengine/UntoldEngine/issues