Skip to content
View untoldengine's full-sized avatar

Block or report untoldengine

Block user

Prevent this user from interacting with your repositories and sending you notifications. Learn more about blocking users.

You must be logged in to block users.

Please don't include any personal information such as legal names or email addresses. Maximum 100 characters, markdown supported. This note will be visible to only you.
Report abuse

Contact GitHub support about this user’s behavior. Learn more about reporting abuse.

Report abuse
untoldengine/README.md

Build Status Project license

Pull Requests welcome code with love by untoldengine

Table of Contents

About

"A Swift-based 3D game engine designed for simplicity and creativity on macOS and iOS."

The Untold Engine is an open-source 3D game engine under active development, designed for macOS and iOS platforms. Written in Swift and powered by Metal, its goal is to simplify game creation with a clean, intuitive API. While the engine already supports many core systems like rendering, physics, and animation, there’s still much to build and improve.

Current Features:

  • Simple API: Focused on ease of use, even for those new to game development.
  • Core Systems: Includes foundational systems for entity registration, rendering, physics, and more.
  • Metal Integration: Leverages Apple’s graphics API for efficient rendering.

The Journey Ahead:

The Untold Engine is a work in progress, with ambitious goals to:

  • Expand physics capabilities with collision detection.
  • Enhance PBR rendering for more realistic visuals.
  • Add new features to make game development a breeze.

Why Try the Untold Engine?

  • For Learners: A great way to explore game development with an engine that prioritizes simplicity.
  • For Game Developers: An opportunity to contribute to an open-source project and shape its future.
  • For Apple Developers: A Swift and Metal-based engine that feels at home on macOS and iOS.

The engine is far from complete, but with every iteration, it gets closer to being an amazing tool for developers. By trying it out, contributing, or sharing your feedback, you can help make the Untold Engine better for everyone.

Author: Harold Serrano


Getting Started

The Untold Engine is a game engine designed to be integrated into your game projects. It is distributed as a Swift Package using Swift Package Manager (SPM) for easy integration and maintenance.

There are two primary ways to use the engine:

  • Running the Engine Standalone – Ideal for contributors and developers who want to explore, modify, or contribute to the engine itself. This mode allows you to test the engine independently using its built-in demo assets and functionalities.
  • Integrating the Engine into Your Game Project – Perfect for game developers who want to build a game using the engine. This requires adding the engine as a Swift Package Dependency in a game project.

Prerequisites

To begin using the Untold Engine, you’ll need:

  • An Apple computer.
  • The latest version of Xcode, which you can download from the App Store.

Running the Untold Engine Standalone (For Contributors & Engine Developers)

If you want to explore, modify, or contribute to the engine, you can run it independently with its built-in demo features. Follow the step-by-step guide in Running the Untold Engine.

Integrating the Untold Engine into Your Game Project (For Game Developers)

To use the Untold Engine in your own game, you must add it as a Swift Package Dependency in your project. Follow the step-by-step guide in Create a Mac OS Game.

Choose your starting path

I’ve designed three different ways for you to Get Started with the Untold Engine. Whether you just want to explore or are ready to make your own game.

Video Tutorials

I have uploaded video tutorials to help you get started with the Untold Engine. Enjoy

  1. How to Install the Untold Engine: Quick Start Guide
  2. Getting Started with the Untold Engine: A Simple Beginner's Guide
  3. Untold Engine Onboarding: The Best Learning Path for Beginners
  4. Rendering with the Untold Engine - A Beginner’s Guide
  5. Animating in the Untold Engine - A Beginner’s Guide
  6. Moving Characters in the Untold Engine: A Beginner's Guide

High-Level API Overview

The Untold Engine offers an intuitive API for game development. Here's a quick look:

let stadium = createEntity()
setEntityMesh(entityId: stadium, filename: "stadium", withExtension: "usdc")
translateBy(entityId: stadium, position: simd_float3(0.0, 0.0, 0.0))

let player = createEntity()
setEntityMesh(entityId: player, filename: "redplayer", withExtension: "usdc", flip: false)
setEntityAnimations(entityId: player, filename: "running", withExtension: "usdc", name: "running")
changeAnimation(entityId: player, name: "running") // Start animation
setEntityKinetics(entityId: player) // Enable Physics System

Using the Untold Engine

The Untold Engine is powered by modular systems that simplify game development. Click on the links to get started.


Visuals

Here are some examples of what the Untold Engine can do, showing its progress and current features in action.

Alt text Alt text Alt text


Roadmap

See the open issues for a list of proposed features (and known issues).


Support

Reach out to the maintainer at one of the following places:


Project assistance

If you want to say thank you or/and support active development of Untold Engine:

  • Add a GitHub Star to the project.
  • Tweet about the Untold Engine.
  • Write interesting articles about the project on Dev.to, Medium or your personal blog.

Together, we can make Untold Engine better!


Contributing

We welcome contributions to the Untold Engine! Here’s how you can help:

  1. Fix Bugs: Review open issues labeled help wanted.
  2. Improve Features: Enhance existing systems, such as adding collision detection to the physics system.
  3. Create Tutorials: Write how-to guides or share examples to help other developers.
  4. Expand the Engine: Suggest and implement new features like AI systems or advanced shaders.

See the Contribution Guidelines for details.


License

This project is licensed under the LGPL v2.1.

What Does This Mean for You?

  • Developing a Game: You can use the Untold Engine to build your game without needing to open source your game’s code.
  • Modifying the Engine: If you make changes to the engine itself, those changes must be open-sourced under the LGPL v2.1.

For more details, see the full license text here.


Popular repositories Loading

  1. UntoldEngine UntoldEngine Public

    An easy to use, Open-Source, 3D game engine for iOS/macOS game development.

    Swift 354 34

  2. doxygen_dark_theme doxygen_dark_theme Public

    Forked from MaJerle/doxygen-dark-theme

    Dark theme for doxygen documentation generator

    CSS 1

  3. UntoldEngine-Game-Template UntoldEngine-Game-Template Public

    Template to start making games with the Untold Engine

    Swift 1

  4. gravity gravity Public

    Forked from marcobambini/gravity

    Gravity Programming Language

    C

535 contributions in the last year

Contribution Graph
Day of Week February March April May June July August September October November December January February
Sunday
Monday
Tuesday
Wednesday
Thursday
Friday
Saturday
Less
No contributions.
Low contributions.
Medium-low contributions.
Medium-high contributions.
High contributions.
More

Contribution activity

February 2025

Created 57 commits in 1 repository
Opened 12 pull requests in 1 repository
untoldengine/UntoldEngine 12 merged
Loading

Seeing something unexpected? Take a look at the GitHub profile guide.