Open-source project
amzeratul/halley avatar
amzeratul/halley

Halley Game Engine: a code-first C++17 engine that shipped Wargroove

A lightweight game engine written in modern C++

3,870 stars180 forksCApache-2.0

At a glance

What is it?
Halley is a lightweight C++17 game engine built around a true entity-component-system, with OpenGL, DX11, Metal and SDL plugins. It is code-first, which means no editor is required to generate anything, and it has shipped a commercial turn-based strategy game across five platforms.
Who is it for?
Adopt Halley if you are comfortable in C++17, want an ECS with systems operating on component families, and prefer building game structure in code rather than through an editor. Avoid it if you need a visual editor as the primary authoring surface, a stable scripting path today, or a large set of current samples: the README states the samples project was taken down for being too outdated.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly C, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • amzeratul/halley3,870 ★ · +13
Star history
Repository2026-09-242026-11-15
amzeratul/halley3.9k3.9k

13 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What Halley solves, and who it is aimed at

Most engines ask you to accept a scene format, an editor and a serialization layer before you write any gameplay. Halley takes the opposite position. Its README lists "Code-first: no reliance on editor to generate anything" as a design objective, alongside "Easy to maintain: games should be easy to keep working on long-term, after it has grown to a large project size". That is a maintenance claim, not a feature claim, and it tells you who the engine is for: teams that expect a project to live for years and would rather keep game structure in source control as C++ than in binary or YAML scene files.

The audience is narrower than "anyone making a game". You need a C++17 toolchain, CMake 3.10 or newer, and a willingness to wire up platform plugins yourself. In exchange, Halley is explicit about what it will not carry: "No legacy: don't bother supporting legacy systems, such as Windows XP or older Android/iOS devices". The README also states the engine has been used to ship Wargroove, a turn-based strategy game, on Windows, Mac (experimental), Nintendo Switch, Xbox One and PS4, with experimental Android and iOS ports described as WIP. That shipping record is the strongest evidence in the repository that the architecture survives contact with a real production schedule.

How Halley is structured: modules, plugins and the entity system

Halley is divided into sub-projects rather than shipped as one library. The engine side contains core (looper, API management, resources and graphics engine), audio, entity, utils, net and ui. Platform support arrives through plugins: asio for networking, dx11, opengl and an experimental metal plugin for video, sdl for System, Input and AudioOut, and winrt for System, Input, Platform and AudioOut/XAudio2. Tools are a separate group: editor, cmd, runner and tools. The runner is described in the README as providing "an entry point for execution and dynamic reloading" and is marked "Highly experimental" in the same list.

The entity module is the part the design guidelines lean on: "'True' entity system based, with components that store data and systems that operate on families of components". That is a specific architectural commitment. Components hold data and no behaviour; systems query families of components and act on them. It differs from an inheritance-heavy GameObject hierarchy, where behaviour lives in the object and adding a capability means changing a class. It also differs from engines where an editor owns the component list and the runtime merely deserializes it.

Graphics is the other stated priority: "Modern graphics pipelines, with first-class shader support". The repository layout reflects the split, with include/, src/, deps, gen/, shared_gen/ and shared_gen_src/ at the top level, plus a template/ directory and a halley_project/ directory, which suggests a project scaffold is generated rather than hand-written. The README does not explain what template/ contains, so treat that as something to inspect in the repository rather than something the documentation promises.

Installing Halley and running a first project

The README's installation section is short and assumes you already have a working C++ build environment. It lists CMake 3.10+, and a C++17 capable compiler: Visual C++ 15.9 (Visual Studio 2017), Clang 5 or GCC 7. Library dependencies are broken into two groups. The engine needs OpenGL, SDL 2.0.2 (2.0.7 recommended) and the Windows 10 SDK, all marked optional, which maps onto the plugin architecture: you only need the backend you actually build. Building the tools additionally requires Freetype 2.6.3 and yaml-cpp 0.5.3, and those are not optional if you want the editor.

The README's own build example passes include and library search paths to CMake before pointing at the parent directory. The backslashes are line continuations:

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

If you only want the engine, the README gives a second form that disables the tools and tests targets. This is the fastest way to find out whether your compiler and dependencies are correct, because it skips the Freetype and yaml-cpp requirement entirely:

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

The bracketed ellipsis is reproduced as the README shows it; it stands for the same include and library path arguments as above. Note that BUILD_HALLEY_TOOLS and BUILD_HALLEY_TESTS are the exact option names, and both are set to 0, not OFF.

Once the build succeeds, the README's next step is to run the editor against a project directory. The example it gives is the entity stress test:

bash
halley-editor tests/entity

The README then says to "Launch that project". So the expected sequence is: build, run halley-editor with a project path, and launch from inside the editor. For a project of your own, the README points at the template/ directory in the repository layout, and at a separate sample game repository (the Global Game Jam 2020 entry) for a worked example. The README does not document the editor's command-line flags beyond the project path argument, so do not assume there are more.

Where Halley is the wrong choice

The samples problem is the most visible one. The README states plainly: "(The samples project was taken down due to being too outdated, sorry about that!)". A new user therefore has no in-repository reference game to read. The README redirects to the ggj20 repository, which is a jam entry, not a production codebase, and to a wiki for full documentation. If you learn best by reading a complete, current game built on an engine, Halley makes that harder than engines that ship maintained samples.

Platform maturity is uneven, and the README says so. Mac is labelled experimental, Android and iOS ports are WIP, and the Metal plugin is experimental. The tested configurations listed are Windows 10 Professional 64-bit, Mac OS X 10.9.6 and Ubuntu 16.04. Those are old reference points, and the README does not claim newer systems are validated, so you should treat current macOS, current Linux distributions and console SDK versions as unverified by the documentation.

Scripting is listed as an objective, not a delivered feature: "Support scripting in other languages, such as Lua" appears under design guidelines, and nothing in the README describes a Lua binding or a scripting API. If your team plans to keep gameplay logic out of C++, that plan is not supported by anything in the README. The runner, which would be the natural home for dynamic reloading of game code, is described as "Highly experimental". Hot reloading is listed as a goal ("Fast iteration time: hot-reloading wherever possible"), but the README does not document which parts reload and which do not.

How Halley differs from Godot and from a framework like SDL

The closest comparison in spirit is Godot, because both are open source and both target multiple platforms. The difference is where the project lives. Godot is editor-first: scenes and nodes are authored in the editor and saved as scene files, and GDScript is a first-class language. Halley is code-first by stated design, with an entity-component-system rather than a node tree, and the README describes the editor as a tool among tools rather than the source of truth. If your team wants designers authoring content in a GUI without touching C++, Godot's model fits that workflow and Halley's does not.

Against a lower-level framework such as SDL, the comparison is one of scope. Halley uses SDL as a plugin for System, Input and AudioOut, so it sits above it. Choosing SDL directly means you write your own entity system, resource management, graphics abstraction and tooling. Choosing Halley means you accept its entity module, its looper and resource model, and its plugin set in exchange for not building those. The trade is control for structure. Halley's design guidelines are openly opinionated about that structure, including the refusal to support legacy platforms, which is a deliberate constraint rather than an oversight.

Maintenance, licensing and the cost of upgrading

The repository is not archived, and its last push was on 2026-09-21, two days before this writing. The default branch is develop, not main or master, which matters when you pin a dependency: cloning the default branch gets you development work, and the README does not describe a release process or a stable branch policy. The repository has no published GitHub releases, so there is no version number to pin against and no changelog summary to rely on here, though a changelog.md file exists at the top level of the repository.

Upgrade cost is driven by the dependency list. The README specifies SDL 2.0.2 with 2.0.7 recommended, Freetype 2.6.3 and yaml-cpp 0.5.3. Those are pinned old versions, and the README does not state whether newer releases of those libraries work. A C++17 codebase with a custom build system also means ABI and compiler-version friction is your problem, not the engine's, particularly if you build for consoles where the toolchain is fixed by the platform holder.

Licensing is Apache 2.0, stated in the README and present as a LICENSE file at the top level, with a licences/ directory alongside it for third-party components. Apache 2.0 is permissive and includes an explicit patent grant, which is generally friendlier to commercial shipping than a copyleft licence would be. That is a description of the licence text, not legal advice; if you are shipping on consoles or distributing binaries, have your own counsel review the licences/ directory, since bundled dependencies may carry different terms than the engine itself.

Editorial conclusion

Adopt Halley if you are comfortable in C++17, want an ECS with systems operating on component families, and prefer building game structure in code rather than through an editor. Avoid it if you need a visual editor as the primary authoring surface, a stable scripting path today, or a large set of current samples: the README states the samples project was taken down for being too outdated. Before committing, verify that CMake 3.10+, a C++17 compiler and your platform's dependencies are in place, then build engine only with -DBUILD_HALLEY_TOOLS=0 -DBUILD_HALLEY_TESTS=0 and run halley-editor tests/entity to confirm the toolchain works end to end.

Frequently asked questions

What is the Halley Game Engine?

It is a lightweight game engine written in C++17, divided into engine modules (core, audio, entity, utils, net, ui), platform plugins such as opengl, dx11, metal, sdl and asio, and tools including an editor and a command-line interface. The README states it has been used to ship Wargroove on Windows, Mac, Nintendo Switch, Xbox One and PS4.

How do I install and build the Halley Game Engine?

You need CMake 3.10+ and a C++17 compiler (Visual C++ 15.9, Clang 5 or GCC 7), plus OpenGL, SDL 2.0.2 and the Windows 10 SDK as optional engine dependencies. The README's build step passes CMAKE_INCLUDE_PATH and CMAKE_LIBRARY_PATH to cmake, and you can build engine only with -DBUILD_HALLEY_TOOLS=0 -DBUILD_HALLEY_TESTS=0.

Does the Halley Game Engine need the editor to build a game?

No. The README lists "Code-first: no reliance on editor to generate anything" as a design objective, so game structure is written in C++ rather than generated by the editor. The editor is still useful for launching and testing a project, as in the README's example of running halley-editor tests/entity.

What are the dependencies for building the Halley editor and tools?

Building the tools additionally requires Freetype 2.6.3 and yaml-cpp 0.5.3, on top of the engine dependencies. That is why the README offers a separate engine-only CMake invocation that disables the tools and tests targets.

Which platforms does the Halley Game Engine support?

The README lists Windows (tested on Windows 10 Professional 64-bit), Mac OS X (tested on 10.9.6) and Linux (tested on Ubuntu 16.04). Mac support is described as experimental, the Metal plugin is experimental, and Android and iOS ports are described as WIP.

Official sources

  1. amzeratul/halley on GitHub
  2. Issues
  3. License: Apache-2.0
  4. Project website
  5. README
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/amzeratul-halley.svg)](https://hysenlabs.com/projects/amzeratul-halley)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/amzeratul-halley.svg)](https://hysenlabs.com/projects/amzeratul-halley)

Was this useful?