OloEngine

OloEngine is a cross-platform (Windows / Linux) C++23 interactive-application and rendering engine. It started as a follow-along of Hazel but has since grown well past that scope into a full ECS-driven engine with a physically-based OpenGL 4.6 renderer, 2D/3D physics, dual C#/Lua scripting, networking, navigation, procedural terrain and environmental systems, a gameplay/AI stack, and an ImGui editor.

Screenshots

Metallic and dielectric PBR spheres (a roughness sweep) reflecting a procedural star-nest sky:

PBR model	Animated models	3D physics	FFT ocean

Table of contents

• Repository layout
• Getting started
• Building & running
• Features
• Testing
• Continuous integration
• Tooling
• Dependencies
• Code style & pre-commit hooks
• Documentation
• Influences & references

Repository layout

Target / directory	What it is
OloEngine/	The engine static library (OloEngine). All subsystems live under src/OloEngine/<Subsystem>/; platform glue under src/Platform/.
OloEditor/	ImGui-based editor (OloEditor). Panels under src/, runtime assets under assets/, a sample game under SandboxProject/.
OloRuntime/	Standalone game runtime (OloRuntime) that loads what the editor builds.
OloServer/	Headless dedicated server (OloServer) — the one target that also runs on WSL2.
OloEngine-ScriptCore/	C# scripting runtime library (Windows only, Visual Studio generator).
OloEngine-LuaScriptCore/	Lua scripting core (all platforms).
OloEngine/tests/	GoogleTest suite (OloEngine-Tests).
tools/	Build-time tooling, notably OloHeaderTool (code generation — see Tooling).
docs/	Design docs, ADRs, build/testing guides, and agent rules — see Documentation.

Getting started

Supported platforms

• Windows — Visual Studio 2026 (the default msvc preset) or Visual Studio 2022.
• Linux — GCC 14+.
• WSL2 — can compile every target and run OloServer, but not OloEditor: WSL2's software renderer only exposes OpenGL 4.5, and the editor requires a native OpenGL 4.6 GPU.

Requirements

• CMake 4.2+ — required by CMakePresets.json (the msvc preset's Visual Studio 18 2026 generator only exists in 4.2+). The root CMakeLists.txt itself only requires 3.25, so a plain cmake -B build -G "Visual Studio 17 2022" still works without presets.
• Python 3.10+ with the jinja2 package (needed to build glad2).
• Vulkan SDK — for SPIR-V shader compilation.

Clone

git clone https://github.com/drsnuggles8/OloEngineBase

All third-party dependencies are fetched automatically at configure time via CMake FetchContent and CPM, and stored under OloEngine/vendor/ (never edit that directory — a CMake reconfigure wipes it). CMake also creates the build/ directory with the generated solution files.

Building & running

CMake presets (CMakePresets.json):

Preset	Generator / build dir	Purpose
msvc	Visual Studio 18 2026 → build/	Primary, default build dir
clangcl	Ninja Multi-Config → build-clang/	clang-cl warnings with the MSVC ABI
clangcl-asan	Ninja Multi-Config → build-clang/	Adds AddressSanitizer

# Generate the Visual Studio solution
scripts\Win-GenerateProjectVS2026.bat        # or Win-GenerateProjectVS2022.bat

# Build a target
cmake --build build --target OloEditor       --config Debug --parallel
cmake --build build --target OloEngine-Tests --config Debug --parallel
cmake --build build --target OloRuntime      --config Debug --parallel
cmake --build build --target OloServer       --config Debug --parallel

# ClangCL (configure once, then build)
cmake --preset clangcl
cmake --build build-clang --target OloEngine-Tests --config Debug --parallel

Working directory matters. OloEditor, OloRuntime, and OloServer resolve assets, shaders, and Mono assemblies relative to OloEditor/. Always run them with cwd = OloEditor/. The VS Code tasks already do this.

VS Code users — predefined tasks in .vscode/tasks.json wrap all of the above: build-oloeditor-debug, run-oloeditor-debug, build-tests-debug, run-tests-debug, configure-clangcl, etc. Run them from the Command Palette (Ctrl+Shift+P → Tasks: Run Task).

CLion users — open the repo folder, let CLion configure the CMake project, then set the working directory of the OloEditor run configuration to the OloEditor/ folder.

The full per-OS build matrix (including Linux and WSL specifics) lives in docs/ops/build.md.

Features

Core engine

• Entity-Component-System built on EnTT under a UUID-keyed Entity wrapper. The hottest update loops use EnTT owning groups for packed iteration.
• Deterministic gameplay scheduler — per-tick systems declare their read/write data flow and the execution order is derived by topological sort, with optional worker-thread parallelism (audited per system) and a physics-shadow phase that steps the physics world alongside game-thread systems.
• Multi-threaded asset system — async loading with hot-reload via filewatch; typed retrieval through AssetManager.
• Dual scripting — C# via Mono (Windows) and Lua via Sol2 (all platforms), with generated bindings.
• YAML serialization — scenes, entities, and prefabs. Trivial component (de)serialization, the ECS component tuple, save-game capture/restore lists, and add/remove handlers are all code-generated from the component definitions (see Tooling), so most new components round-trip with zero hand-written glue.
• Save games — component-level snapshot/restore with a versioned binary archive format.
• Custom memory management, threading, and task systems — custom allocators, RAII resources, a job/task scheduler, and async primitives.

Rendering

• Modern OpenGL 4.6 with Direct State Access and SPIR-V shader compilation.
• Stateless, layered, multi-threaded command queue (Molecular Matters' design) driven by a render-graph.
• Physically-based rendering — metallic-roughness workflow, image-based lighting (IBL).
• Deferred + forward paths with Hi-Z GPU occlusion culling and LOD.
• Post-processing & advanced lighting — SSAO, SSR, SSGI, contact shadows, all shadow types (incl. PCSS), TAA, volumetric fog + god rays, screen-space decals, order-independent transparency, and FSR/CAS upscaling.
• Unified 2D/3D pipeline — sprites and 3D meshes through one renderer.
• Skeletal animation — Assimp-imported skeletons, animation graphs and state machines, additive layers, and humanoid retargeting; secondary motion via spring bones and cloth.
• GPU-driven particles — compute-based particle simulation.
• Real-time particle fluids — GPU Position-Based Fluids solver (compute spatial hash + density-constraint solve) with screen-space fluid rendering, deterministic CPU fallback, and two-way Jolt rigid-body coupling.

Physics

• 3D — Jolt Physics for rigid bodies, joints, characters, and vehicles.
• 2D — Box2D for 2D mechanics.
• Custom collision layers for flexible filtering and detection.

Environmental & world systems

• Procedural terrain generation with LOD.
• Water / FFT ocean rendering.
• Weather & environment — wind, snow (with deformation), and precipitation systems.
• Streaming volumes, light-probe volumes, fog volumes, and navigation-mesh bounds as scene-level authored data.

Gameplay, AI & narrative

• AI — GOAP planner / action system and a perception system (sight / sound / awareness).
• Navigation — Recast/Detour nav-mesh generation with nav agents.
• Dialogue & quests, plus a localization system driving LocalizedTextComponent.
• Cinematic sequencer — timeline-driven cutscenes.

Networking

• Reliable UDP transport over GameNetworkingSockets, with encrypted transport (libsodium) and a protobuf wire format for snapshots / RPC. OloServer provides the headless dedicated-server target.

Audio & video

• 3D spatial audio (miniaudio) with source/listener ECS components and a SoundGraph / MetaSounds-style audio-graph.
• Video playback component.

UI system

• ECS-based UI — Canvas, RectTransform, Panel, Text, Image, Button, Slider, Checkbox, Toggle, Progress Bar, Input Field, Dropdown, Scroll View, Grid Layout, WorldAnchor, and more.
• Anchor layout — RectTransform-style anchoring, pivots, and auto-layout via grid containers; works in both 2D and 3D.
• Editor integration — a "Create UI" menu, per-component property panels, and editor-time preview.
• Full C# and Lua bindings for every UI component.

Editor & debugging

• ImGui editor — scene hierarchy, content/asset browser with drag-and-drop, gizmos and transform tools, and real-time scene manipulation.
• Play-in-editor — snapshot/restore around Play/Simulate.
• Profiling — Tracy integration plus custom renderer profiler and GPU/CPU memory tracking.
• Read-only MCP diagnostics server — inspect a live editor frame (screenshots, camera control, intermediate render targets, shader errors) from an external tool. See docs/guides/mcp-diagnostics-server.md.

Testing

The suite (OloEngine-Tests, GoogleTest) spans two independent axes:

1. A renderer testing pyramid (L1–L11 plus plumbing / culling-LOD / shader-pipe / integration layers) covering pixels, GL state, and shader math — including screenshot-based visual-regression tests that gate GPU-equipped runs and skip cleanly when no OpenGL 4.6 context is present.
2. A Functional / cross-subsystem axis ("Functional" tag) driving real Scene::OnUpdateRuntime ticks across Animation × Physics × Scripting × Networking × Audio × Asset × Nav × Save-game × Gameplay × AI seams.

# Run everything, or a single test
build\OloEngine\tests\Debug\OloEngine-Tests.exe
build\OloEngine\tests\Debug\OloEngine-Tests.exe --gtest_filter=SuiteName.TestName

The rationale, per-layer reference, classification rules, and anti-patterns live in docs/testing.md and docs/agent-rules/testing-architecture.md.

Continuous integration

Per-PR and per-push

These gate every change and run on GitHub-hosted runners.

Workflow	Status	Covers
Windows		MSVC build + full suite via CTest
Sanitizers		ASan (Windows/clang-cl), ASan+LSan / UBSan / TSan (Linux/Clang)
SonarCloud Scan		Static analysis (see sonarqube-review-alignment.md)
Pre-commit checks		Formatting, YAML, test-catalogue classification

Scheduled

Cron times are UTC — GitHub's scheduler does not observe DST, so local times shift by an hour across the year. Every one of these is also workflow_dispatch-able from the Actions tab. Scheduled runs may start tens of minutes late under load.

Workflow	Status	Cadence (UTC)	Runs on	Covers
GPU Conformance (AMD)		nightly 00:47	self-hosted Linux / AMD Navi 10	The renderer's visual, golden and perf layers against a real GPU — they skip everywhere else. See self-hosted-gpu-runner.md
Cross-Vendor Conformance		nightly 03:47	GitHub-hosted Windows	L1/3/5/6/8 against Mesa llvmpipe (software)
Fuzz Smoke		nightly 04:13	GitHub-hosted Windows	Parser / deserializer fuzzing
Flaky repro (#281)		nightly 07:00	GitHub-hosted Windows	Repeat-runs a known-flaky test to hunt issue #281
Video (FFmpeg backend)		weekly, Mon 06:00	GitHub-hosted matrix	OLO_VIDEO_FFMPEG=ON build + decode tests
reflection-status-check		monthly, 1st 09:07	GitHub-hosted Linux	Reminder to re-check C++26 reflection toolchain support

Hardware-GPU vendor coverage is AMD-only. The goldens in assets/tests/golden/ are baselined on NVIDIA, but only ever from a developer machine — there is no NVIDIA or Intel CI. llvmpipe is a third software implementation, not a second vendor, so it catches spec-compliance drift rather than driver divergence.

Tooling

OloHeaderTool (tools/OloHeaderTool/) scans OloEngine/src/ and generates, at build time (via the GenerateBindings target):

• C++ and C# scripting bindings from OLO_PROPERTY annotations.
• The ECS AllComponents type list, the save-game capture/restore lists, the OnComponentAdded/OnComponentRemoved no-op handlers, and per-component scene serialize/deserialize blocks — all derived from the struct *Component definitions.

This collapses what used to be several hand-maintained, easy-to-forget touch-points into codegen: an all-trivial component now round-trips through scenes, save-games, and scripting with little or no hand-written glue. See CLAUDE.md for the exact contract when adding or changing a component.

Dependencies

All dependencies are fetched automatically via FetchContent and CPM (CPM hosts Sol2, choc, nlohmann/json, ImGui, and ImGuizmo; FetchContent hosts the rest) into OloEngine/vendor/.

Core — entt (ECS) · glm (math) · spdlog (logging) · yaml-cpp (serialization) · nlohmann/json (tools / IPC) · choc (utilities) · atomic_queue (lock-free MPMC queue) · meshoptimizer

Rendering — glad · glfw · assimp · stb · zlib

Physics — Jolt Physics (3D) · box2d (2D)

Networking — GameNetworkingSockets · libsodium · protobuf

Navigation — recastnavigation

Audio — miniaudio

Scripting — sol2 · lua · Mono (C# runtime, manually integrated)

UI & editor — imgui · imguizmo

Development & profiling — tracy · googletest · filewatch

Code style & pre-commit hooks

We enforce a small set of formatting rules via pre-commit:

python -m pip install --user pre-commit
pre-commit install                 # enable the git hook (run in the repo root)
pre-commit run --all-files         # optional: apply across the whole repo

Included hooks: trailing-whitespace, end-of-file-fixer, and clang-format for C/C++ (uses the repo-root .clang-format). An .editorconfig mirrors the whitespace rules for editors. The hooks ignore vendor/, build/, and IDE metadata folders. A GitHub Action runs pre-commit on every push and PR.

Documentation

Everything under docs/ — start at docs/README.md for the full index. Highlights:

• docs/ops/build.md — full Windows / Linux / WSL build matrix.
• docs/testing.md — the canonical testing opinion doc.
• docs/guides/ — subsystem how-tos (AI/GOAP, perception, terrain, UI, localization, cinematics, video, MCP diagnostics).
• docs/adr/ — architecture decision records.
• CLAUDE.md — contributor/agent playbook: build, test, and the component cross-binding contract.

Influences & references

• Hazel — the foundation this engine started from (The Cherno's game-engine series).
• Lumos — ideas for the OpenGL renderer and engine architecture.
• Arc — ideas for the audio engine.
• Molecular Matters Blog — the multi-threaded render command queue architecture.