Architecture & Internals

The big picture

Module Architecture

Horizon Engine is built from cleanly separated modules. Each layer talks to the ones below through narrow interfaces, so a piece can be extended or replaced without touching the rest.

Entities are backed by an ECS registry; gameplay logic reaches the engine through the HE::api registry — one machine-readable table of engine functions that simultaneously powers the Lua and Python bindings, HorizonCode's Engine Call node and the HorizonCode→C++ code generator. Adding an engine function is one registry row; every frontend gets it at once.

16 milliseconds

Anatomy of a Frame

1. Input & events

   SDL events pump; the input snapshot updates; input actions fire into player classes and widgets.

2. Simulation

   Physics steps at a fixed timestep (accumulator), collision events dispatch to scripts, script onUpdate runs, HorizonCode latent flows resume, widgets tick. The always-on systems — animation, navigation, particles, weather — tick in editor and play mode alike.

3. Streaming

   Background asset loads complete and register on the main thread under a per-frame budget.

4. Extract

   The scene is flattened into a backend-agnostic RenderWorld: frustum culling, LOD selection, instancing batches, shadow cascade fitting, environment state.

5. Render & present

   The active backend draws the frame pipeline — shadow maps, sky and scene in HDR, post-processing, UI — and presents.

Content

Asset Infrastructure

Every asset is a .hasset file: a small chunked container whose chunks carry metadata, source data and cooked payloads (mesh vertex buffers, precompiled shaders, texture cook data, script language, graph JSON …). Assets are identified by UUID — references never break when files move.

• In the editor, a disk registry indexes loose assets by reading only their headers, so even huge projects resolve references without preloading.
• In a packaged game, assets live in the hpak archive and stream on demand, following the reference graph.
• Asynchronous loading runs on worker threads with main-thread registration under a frame budget.

When things go wrong

Diagnostics

• Profiler — the in-engine profiler measures per-pass GPU time and nested CPU scopes with zero cost while idle; F9 captures a benchmark to JSON in the dumps/ folder, in the editor and in exported games alike. UI: View ▸ Performance Profiler.
• Logging — HorizonEngine.log next to the executable, truncated per launch.
• Crash handler — on macOS/Linux, fatal signals write a he_crash_*.crash report (signal + stack trace) to the system temp directory before the OS core dump.
• Robust config — the editor's config.json is parsed defensively (a corrupt file resets instead of crash-looping) and written atomically.
• Debug drawing — scripts and graphs can draw lines, spheres and boxes in the viewport via the debug API group.

DIY

Building from Source

The engine builds with CMake (presets for Windows/MSVC+Ninja, macOS and Linux with clang ship in the repository). Dependencies — SDL3, glm, Lua 5.4, Jolt Physics, Recast/Detour, lz4/zstd, nlohmann-json, Dear ImGui — are fetched or found automatically; embedded CPython is optional and enables the Python backend.

# Configure a release build
cmake -B build -DCMAKE_BUILD_TYPE=Release

# Compile the engine and editor
cmake --build build --config Release

Main targets: HorizonEditor (the editor), HorizonGame (the game runtime), the module libraries, and tools like the shader compiler and the pak packer. Releases carry sky-themed codenames — the current line is Sunrise.