Retro Engine

A production-grade, data-driven asset ecosystem: a pipeline core library, a Editor Dear ImGui editor, a deterministic zone format, and a small Vulkan runtime engine.

┌──────────────┐   tasks    ┌──────────────┐   zone file   ┌──────────────┐
│  editor   │ ─────────▶ │   pipeline   │ ────────────▶ │    engine    │
│ (ImGui GUI)  │            │ (core + CLI) │               │  (Vulkan)    │
└──────────────┘            └──────────────┘               └──────────────┘
                                    ▲
                          JSON assets + variants

Features

• Asset system — JSON assets with inheritance, @refs, ${interp}, variants.
• Task system — the only execution mechanism; tree/DAG, parallel, cacheable.
• Deterministic cache — hash-keyed derived data, reused across runs.
• Zone format — mmap-friendly binary, pointer-patched at load.
• Editor — dockable editor: terminal, task tree, outliner, editor, artifacts inspector (zone + cache with per-resource subobject breakdown).
• Engine — Vulkan renderer with directional shadow map (PCF), model / material / material-instance / texture runtime system.

Requirements

• C++20 compiler (GCC 12+ recommended, also builds on clang / MSVC)
• CMake ≥ 3.14
• Ninja or Make
• Vulkan SDK (for the engine target — pipeline + editor build without it)
• glslc (bundled with the Vulkan SDK or shaderc)

The build fetches all other dependencies (GLFW, Dear ImGui, glm, nlohmann/json) via CMake FetchContent — no manual setup needed.

Quick start

Linux / macOS / MSYS2 / Git Bash

./scripts/build.sh              # configure + build (Release, GCC)
./scripts/run_demo.sh           # pack demo zone and launch the engine
./build/editor/editor     # or: launch the editor

Windows (MinGW-w64, no Visual Studio)

One-liner — downloads a portable GCC + CMake + Ninja bundle into vendor/toolchain/ (~267 MB, one-time) and builds:

scripts\build.bat
scripts\run_demo.bat
build\editor\editor.exe

If you'd rather install the toolchain system-wide, use MSYS2:

pacman -S --needed mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake \
                   mingw-w64-x86_64-ninja mingw-w64-x86_64-shaderc \
                   mingw-w64-x86_64-vulkan-devel

The engine target additionally needs the Vulkan SDK (from LunarG). Without it, pipeline and editor still build; only the engine is skipped.

Project layout

pipeline/    core library: asset / variant / resolver / tasks / cache / jobs
zone/        runtime zone format (headers shared with pipeline and engine)
editor/   Dear ImGui editor (panels: terminal, task_tree, outliner,
             asset_editor, artifacts)
engine/      Vulkan runtime that loads a .zone and renders it
assets/    sample assets, prefabs, materials, contexts, build descriptors
scripts/     build + demo helpers
.github/     workflows, issue / PR templates, shared reference assets

Building just parts

cmake --build build --target pipeline_cli     # CLI only
cmake --build build --target editor         # editor only
cmake --build build --target engine            # runtime only

Running tasks from the CLI

build/pipeline/pipeline --assets-dir assets kick_build \
    'context=@context.dreamlike_pc' 'build=@build.demo'

This produces build/zone/demo.zone, which the engine loads:

build/engine/engine --zone build/zone/demo.zone

CI

GitHub Actions builds on Ubuntu (GCC) and Windows (MSYS2 MinGW-w64). See .github/workflows/ci.yml.

License

MIT — see LICENSE.