AeonEngine is a cross-platform, plugin-based 3D game engine written in C++. It supports multiple rendering backends, uses Protocol Buffers for asset serialization, and integrates with Blender for content creation workflows.

This is the 3rd iteration of the engine, the first one was started circa 1996 and was lost on a hard drive crash, the second one was started circa 2001 and still exists, but is a mess and a patchwork of collected ideas of 15 years of trying to keep up.

⚠️ THIS IS A WORK IN PROGRESS.

• Vulkan — Primary renderer with SPIR-V shader compilation via glslang. On macOS, Vulkan is provided through MoltenVK.
• OpenGL 4.5 — Secondary renderer using core profile. Disabled on macOS (Apple does not support OpenGL 4.5).
• Minimum common denominator design — All uniforms use Uniform Buffer Objects (UBOs) so the same shaders work identically across Vulkan, OpenGL, and potential future backends (DirectX, Metal).
• Compute pipelines — A unified Pipeline asset can carry both graphics and multiple ordered compute stages. The Renderer interface exposes Dispatch and Barrier, and both backends support Shader Storage Buffer Objects (SSBOs) with SPIR-V reflection and transient storage-buffer memory pools. Skeletal meshes are skinned on the GPU in a compute pre-pass that writes posed vertices into a buffer the mesh is drawn from, removing skinning from the vertex shader.
• Clustered Forward+ lighting — A compute-driven light culling pipeline bins lights into view-space clusters (cluster_build), culls them per cluster (light_cull, including a cone-vs-cluster test for spot lights), and packs a global light-index list via an atomic allocator. An optional depth pre-pass marks active clusters so only visible clusters are shaded. Per-frame lights are uploaded as an SSBO (cap 4096). A cluster light-count heatmap debug view is available.

• Camera — First-person/third-person camera component
• ModelComponent — Model rendering component (mesh + material + pipeline)
• PointLight / SpotLight / DirectionalLight — Scene illumination with radius attenuation and spot-cone falloff
• CharacterController — Movement/turn controller wired to the input system

All game assets are serialized using Protocol Buffers, including meshes, materials, pipelines, skeletons, animations, scenes, and models.

• aeontool — Command-line utility for asset conversion (binary ↔ text), packaging, base64 encoding, and pipeline compilation.
• WorldEditor — Qt6-based GUI editor for scene and node hierarchy editing, component management, property inspection, and renderer selection.
• Blender Addons — Export meshes, materials, skeletons, animations, models, collisions, images, and scenes directly from Blender to AeonEngine formats. The model exporter splits multi-material objects into one assembly per material slot, mapping each Blender Principled BSDF to the engine's Phong material.

This repository uses Git Large File Storage (LFS) to manage large binary asset files (meshes, base64-encoded resources, etc.). You must install and initialize Git LFS before cloning, otherwise these files will be checked out as small pointer files instead of actual data.

1. Install Git LFS (one-time per machine):

   • Windows (MSYS2): pacboy -S git-lfs:p
   • Arch Linux: pacman -S git-lfs
   • Ubuntu/Linux: sudo apt-get install git-lfs
   • macOS: brew install git-lfs
   • Windows (Git for Windows): Git LFS is bundled — no extra install needed.

2. Initialize Git LFS (one-time per machine):

   git lfs install

3. Clone the repository as usual — LFS files are downloaded automatically:

   git clone https://github.com/AeonGames/AeonEngine.git

If you already cloned without LFS, run git lfs pull inside the repository to download the LFS objects.

The tracked patterns are defined in .gitattributes and currently include *.msh and *.b64 files.

The AeonEngine uses CMake and supports building on multiple platforms. Choose the method that best fits your environment.

Visual Studio Code is not required to build, but is highly recommended for development. The project includes VS Code configuration templates for tasks, launch, and settings.

Go to MSYS2 and install MSYS2. Development targets 64-bit, so choose that if you are unsure.

Open an MSYS2 terminal and update all installed packages:

pacman -Syuu --noconfirm

You may need to close the terminal and run the command again until no more updates are reported.

Install general system tools:

pacman -S --needed --noconfirm git pactoys make

The pactoys package provides pacboy, which installs packages for specific toolchains. Pick a subplatform (mingw64, clang64, or ucrt64), open the corresponding terminal, and install the required packages:

pacboy -S --needed --noconfirm \
    toolchain:p \
    cmake:p \
    make:p \
    tools-git:p \
    vulkan:p \
    vulkan-devel:p \
    qt6:p \
    protobuf:p \
    zlib:p \
    libpng:p \
    glslang:p \
    portaudio:p \
    libogg:p \
    libvorbis:p \
    cairo:p \
    gtest:p

Repeat for each subplatform you want to target.

git clone https://github.com/AeonGames/AeonEngine.git
cd AeonEngine
cmake -G "MSYS Makefiles" -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

cd build
ctest --output-on-failure

Open the repository root folder in VS Code (File → Open Folder). Go to View → Terminal to get an integrated bash terminal where you can run build commands directly. Running executables from the debug environment uses GDB, supporting breakpoints and the Debug Console.

sudo apt-get update
sudo apt-get install -y \
    build-essential \
    software-properties-common \
    gcc \
    g++ \
    llvm \
    clang \
    sed \
    python3 \
    tar \
    wget \
    cmake \
    autoconf \
    automake \
    libtool \
    curl \
    make \
    unzip \
    zlib1g-dev \
    libpng-dev \
    vim-common \
    git \
    portaudio19-dev \
    libogg-dev \
    libvorbis-dev \
    googletest \
    libglu1-mesa-dev \
    freeglut3-dev \
    mesa-common-dev \
    libcairo2-dev \
    libprotobuf-dev \
    protobuf-compiler \
    mesa-vulkan-drivers \
    libvulkan1 \
    libvulkan-dev \
    qt6-base-dev \
    qt6-tools-dev \
    qt6-tools-dev-tools \
    qt6-l10n-tools \
    libxkbcommon-dev \
    glslang-dev \
    glslang-tools \
    libglx-mesa0 \
    vulkan-validationlayers

With GCC:

git clone https://github.com/AeonGames/AeonEngine.git
cd AeonEngine
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

With Clang:

cmake -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=cmake/clang-toolchain.cmake
cmake --build build

cd build
ctest --output-on-failure

Dependency management uses Microsoft's vcpkg. Requires Visual Studio 2022 or later.

1. vcpkg — Install via the Visual Studio Installer. The project includes a vcpkg.json manifest that automatically downloads and builds required packages—you just need to point CMake at the vcpkg.cmake toolchain file.
2. Vulkan SDK — Download and install from LunarG.
3. Git for Windows — Download and install from git-scm.com.

Open a VS Developer Command Prompt or Developer PowerShell:

git clone https://github.com/AeonGames/AeonEngine.git
cd AeonEngine
cmake -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake -B build
cmake --build build --config Release

Or open the generated .sln file in Visual Studio and build from the IDE.

Note: OpenGL 4.5 is not supported on macOS. Only the Vulkan renderer (via MoltenVK) is available. The standalone application is also disabled on macOS.

Make sure Homebrew is installed, then:

brew update
brew install \
    cmake \
    make \
    protobuf \
    zlib \
    libpng \
    glslang \
    portaudio \
    libogg \
    libvorbis \
    cairo \
    googletest \
    qt6 \
    pkg-config \
    molten-vk

git clone https://github.com/AeonGames/AeonEngine.git
cd AeonEngine
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

cd build
ctest --output-on-failure

Example — build with only the Vulkan renderer:

cmake -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_OPENGL_RENDERER=OFF
cmake --build build

The CMake configuration installs a git pre-commit hook that formats code using astyle (C++), autopep8 (Python/Blender scripts), and cmake-format (CMake files). Install the formatters before creating commits:

python3 -m pip install autopep8 cmake-format

AeonEngine/
├── application/     # Standalone game launcher/viewer
├── assets/          # Bundled demo assets (Aerin model, Sponza scene)
├── cmake/           # CMake modules, toolchain files, and templates
├── engine/          # Core engine library
│   ├── components/  #   Camera, ModelComponent, PointLight
│   ├── core/        #   Scene, Node, Renderer, Pipeline, Material, Mesh, etc.
│   ├── gui/         #   AeonGUI integration (optional)
│   ├── images/      #   Image loaders (PNG)
│   ├── math/        #   Vector, Matrix, Quaternion, Transform, AABB, Frustum
│   ├── renderers/   #   Vulkan and OpenGL renderer plugins
│   └── sound/       #   PortAudio + Ogg Vorbis audio
├── game/            # Game data (scenes, shaders, materials, meshes, models)
├── include/         # Public engine headers (aeongames/)
├── proto/           # Protocol Buffer definitions for all asset types
├── tests/           # GTest unit tests
├── tools/
│   ├── aeontool/    #   CLI asset conversion and packaging tool
│   ├── blender/     #   Blender exporter addons
│   └── worldeditor/ #   Qt6 scene editor GUI
└── vcpkg-port/      # Custom vcpkg port overlays

Licensed under the Apache License, Version 2.0.