Untold Engine is a Swift + Metal 3D engine for macOS, iOS, and visionOS — with native Apple Vision Pro support and a growing focus on spatial computing — built 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

If you've hit the ceiling of what existing engines allow on Apple platforms, this is for you.

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

The fastest way to experience Untold Engine is to run the demo project.

Clone the repository and launch the demo:

git clone https://github.com/untoldengine/UntoldEngine.git
cd UntoldEngine
swift run untolddemo

The demo UI lets you see the engine in action right away. Using the Remote Scene drop-down menu, you can choose a scene to stream directly into the demo through the engine's Asset Remote Streaming support.

Untold Engine uses its own native asset format: .untold.

To try your own USDZ file, first convert it to .untold using the Tools section in the demo UI.

After the export is complete, open the Local Scene Browse drop-down menu, choose .untold, then browse for and select your exported .untold file.

A small code sample to inspect and experiment with is available at Sources/Sandbox/GameScene.swift. Along with the Usage Example, it shows how the Untold Engine API works in practice.

The Sandbox target lets you test engine APIs — creating an entity, attaching a mesh, trying animations, and other scene setup.

To run it from the CLI:

swift run sandbox

To run it in Xcode, select the sandbox scheme and press Run.

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

To make using the Untold Engine easier, you can use the Untold Engine Studio — a standalone editor for preparing assets, composing scenes, and generating scene files used inside your game. Download Untold Engine Studio

Note, you still need the engine as a dependency in your project. The editor is only used for composing scenes.

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 and control, without abstraction layers getting in the way.

Untold Engine is well-suited for:

• 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

• 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
• Spatial Debugger
• Profiler
• Asset Exporter
• Optimizations
• Create Project with CLI
• Post FX

• 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
• Asset Remote Streaming

See open issues for planned features and known improvements.

• Feature Requests
• Bug Reports

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.

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

Need to keep engine modifications private? A commercial license is available for teams that require it. 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