# Halley Game Engine: A Code-First C++17 ECS Engine That Shipped Wargroove

> Halley is an Apache 2.0 C++17 game engine built around an entity-component-system architecture, hot reloading, and a code-first design philosophy. It was used to ship Wargroove across PC, Nintendo Switch, Xbox One, and PS4.

**amzeratul/halley** — A lightweight game engine written in modern C++

- Repository: https://github.com/amzeratul/halley
- Website: https://discord.gg/T7qQqQJ
- Stars: 3,861 · Forks: 178
- Language: C
- License: Apache-2.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/amzeratul-halley

## A Proven Engine Built to Ship a Commercial Title

Halley's clearest credential is that it was used to ship Wargroove, a turn-based strategy game, across Windows, Mac (experimental), Nintendo Switch, Xbox One, and PS4. The README notes that Android and iOS ports are work in progress. For a small open-source engine, having a completed commercial release across five platforms is a concrete signal of the engine's actual production capabilities, not a theoretical design.

The engine is designed around a short list of explicit objectives stated in the README: modern graphics pipeline with first-class shader support, a 'true' entity-component system where components hold data and systems operate on families of components, high performance tuning, code-first design with no reliance on the editor to generate anything, cross-platform support for as many platforms as possible, hot reloading wherever possible, and optional Lua scripting. Each objective is stated as a design constraint, not a wish list.

The repository is licensed under Apache 2.0 and was last pushed on 2026-09-25. A changelog.md is present in the top-level directory, which provides a record of changes over time.

## Entity-Component-System as the Fundamental Architecture

Halley's entity module implements what the README describes as a 'true' entity system: components are pure data containers, and systems act on families of entities that hold specific combinations of components. This is the strict ECS interpretation where logic is not embedded in components.

The entity module is one of several sub-projects under the engine layer. The README lists the top-level engine modules as core (looper, API management, resources, graphics engine), audio, entity (the ECS framework), utils (utilities library), net (networking library), and ui (UI library). These are separate sub-projects in a modular layout, not a monolithic codebase.

The repository includes stress tests for both the entity system (tests/entity) and the networking system (tests/network), which gives some indication that those two subsystems are the most actively used paths. The test projects are also the recommended starting point when verifying a build, since the README's setup instructions end with the step 'Run halley-editor tests/entity (or whichever other project you want to test)'.

## Building Halley with CMake

Halley requires CMake 3.10 or later and a C++17-capable compiler. The README lists three supported compilers: Visual C++ 15.9 (Visual Studio 2017), Clang 5, and GCC 7.

Library dependencies depend on which build target is used. The engine itself requires OpenGL (optional), SDL 2.0.2 or later with 2.0.7 recommended (optional), and the Windows 10 SDK (optional). Building the tools additionally requires Freetype 2.6.3 and yaml-cpp 0.5.3.

The typical CMake invocation shown in the README:

```
cmake -DCMAKE_INCLUDE_PATH=path/to/headers \
      -DCMAKE_LIBRARY_PATH=path/to/libs \
      ..
```

To build the engine without the tools or tests:

```
cmake -DBUILD_HALLEY_TOOLS=0 -DBUILD_HALLEY_TESTS=0 [...]
```

The ellipsis in the engine-only command is the README's placeholder, indicating that the remaining path arguments from the full invocation still apply. After building, the README instructs running halley-editor against a project directory, such as tests/entity, and then launching that project.

All library dependencies must be set up before running CMake. The README does not describe a package manager workflow or a way to fetch dependencies automatically. This is a manual setup process.

## Plugin Architecture and Renderer Backends

Halley separates platform-specific behavior into plugins. The README lists four video plugins: dx11 for DirectX 11 on Windows, opengl for cross-platform OpenGL, metal for Metal on Mac (marked experimental), and sdl for SDL-based audio and input. For Windows there is also winrt, which provides WinRT system integration, WinRT input, and XAudio2 audio output.

This plugin layout means the renderer backend is selected at build time or load time through plugin configuration, not by recompiling the engine with a different graphics API baked in. The same engine core can target different hardware backends on different platforms.

The tools sub-project is split into four parts: editor (the editor UI), cmd (command-line interface to tools), runner (entry point for execution and dynamic reloading, marked as 'highly experimental'), and tools (asset and file generation tools). The runner's experimental status is significant: dynamic reloading is listed as a design goal, but the primary tool for it is not yet in a stable state according to the README.

The samples project was removed. The README includes the note: 'The samples project was taken down due to being too outdated, sorry about that!' This leaves the entity stress test as the only practical starting point for verifying a build.

## Platform Coverage and Current Gaps

The README documents three desktop platforms as tested: Windows 10 Professional 64-bit, Mac OS X 10.9.6, and Ubuntu 16.04. The note on Windows states it 'Might work on as low as XP 32-bit, but XP is no longer a tested target', which aligns with the design principle of not supporting legacy systems.

Console platforms (Nintendo Switch, Xbox One, PS4) are supported, since Wargroove shipped on them, but the README does not provide build instructions for console targets. Console builds likely require platform-specific SDKs under NDAs that cannot be distributed publicly. The Metal plugin for Mac is marked experimental.

Android and iOS are listed as work in progress. They are not described as supported or tested targets.

The full documentation is on the GitHub wiki rather than in the repository itself. The wiki URL is github.com/amzeratul/halley/wiki. For anyone evaluating the engine for a specific use case, checking the wiki before starting is necessary, because the README covers setup but not the engine API or workflow in depth.

## Where Halley Falls Short for Some Projects

The engine has no published GitHub releases. There are no version tags to pin a project to a stable snapshot; development happens on the 'develop' branch. The changelog.md provides a history, but without release tags, tracking what changed between any two points requires reading the commit log.

Lua scripting is listed as a design objective in the README, but the README does not document how to write or register Lua scripts, what the API surface looks like, or which parts of the engine are scriptable. A developer who wants Lua integration would need to investigate the wiki or source code.

The samples project is gone. This means a developer starting a new project cannot clone a working example and modify it. The entity stress test serves as the only practical baseline. Documentation relies entirely on the wiki, which is external to the repository and not pinned to any commit.

The README does not cover multiplayer or networking setup beyond listing 'net' as an engine module and 'asio' as a network plugin. The network stress test exists, but its structure and the underlying networking model are not described.

## Godot Engine as the Primary Open-Source Comparison

Godot is the other major open-source game engine in the same category. It uses a scene and node tree architecture where each node can have child nodes, custom scripts, and built-in behaviors. This is structurally different from Halley's component-only-data, systems-handle-logic ECS model. In Godot, logic is typically attached directly to nodes through scripts; in Halley, logic lives in systems that operate on groups of components.

Godot's primary scripting language is GDScript, a Python-like language designed for Godot, with C# support available. Halley supports Lua as a scripting option and is itself written in C++17; game code is C++. For teams comfortable with C++, Halley's code-first approach avoids the indirection of a visual scripting layer. For teams that prefer a visual editor and a higher-level scripting language, Godot is a more accessible starting point.

Godot has a large asset store, an active community, and extensive official documentation. Halley's documentation is a wiki maintained by a smaller team. The trade-off is simplicity and directness: Halley is a smaller codebase that stays close to the metal.

## Conclusion

Game developers who want a lightweight, code-first C++17 engine with a proven ECS architecture and hot reloading, and who can work through manual CMake dependency setup, will find Halley a viable foundation for commercial projects. Teams that need a fully documented visual editor, extensive scripting support, or a large third-party plugin library should evaluate alternatives. Before starting a project on Halley, read through the wiki documentation to confirm that the specific engine features you need are covered, since the samples project has been removed and the runner tool is marked as highly experimental.

## FAQ

### What commercial game was made with the Halley Game Engine?

The README states that Halley was used to ship Wargroove, a turn-based strategy game, on Windows, Mac (experimental), Nintendo Switch, Xbox One, and PS4.

### What platforms does the Halley Game Engine support?

The README documents tested support for Windows 10 Professional 64-bit, Mac OS X 10.9.6, and Ubuntu 16.04. Console targets (Switch, Xbox One, PS4) were used for Wargroove. Android and iOS ports are listed as work in progress.

### What build system does Halley use?

Halley builds with CMake 3.10 or later and requires a C++17-capable compiler. Visual C++ 15.9, Clang 5, and GCC 7 are listed as supported compilers in the README.

## Sources

- [amzeratul/halley on GitHub](https://github.com/amzeratul/halley)
- [Issues](https://github.com/amzeratul/halley/issues)
- [License: Apache-2.0](https://github.com/amzeratul/halley/blob/develop/LICENSE)
- [Project website](https://discord.gg/T7qQqQJ)
- [README](https://github.com/amzeratul/halley/blob/develop/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/amzeratul-halley