Skip to content

Why Labrador?

Labrador is a 2D game engine for people who want to build games in ordinary C++ and be able to read everything underneath them. It is small, it has firm opinions, and it is young. This page sets out the four choices that define it, what each one buys and what each one costs, so you can tell quickly whether it suits the game you want to make.

It suits you if:

  • you want to write a 2D game in C++, and you are willing to build it from a command prompt: Get Started shows every step, for someone who has hardly programmed, though going beyond its first change means learning some C++;
  • you want to understand the engine your game runs on, and be able to read any part of it;
  • your game is played on one machine: alone, or with friends on a shared or split screen, with gamepads;
  • you would like to test your game’s rules the way you test any other code.

It does not suit you if you want a visual editor, a scripting language, 3D or online play. Those four are permanent decisions, explained below. It does not suit you yet if you need a platform beyond Windows and a desktop browser (phones among them): that one is provisional. And it is a small project, with no asset store and no years of answered questions.

A Labrador game is an ordinary C++20 program. It links the engine’s static libraries, its dependencies come from vcpkg, and its build file is plain CMake. Here is the whole build file of the minimal sample, comments included:

Show samples/minimal/CMakeLists.txt, 152 lines
samples/minimal/CMakeLists.txt
# --- MinimalSample — the minimal sample, and the new-project template ---
#
# The whole build file for a game on this engine, for building it and running
# it during development: name the sources, link the engine and the shared
# settings, mirror the content, put the rules in a library and register their
# tests and a start-up check, stage the release folder a player gets - and a
# branch for the same game in a browser.
# There is no project file format and no code generation (ARCHITECTURE.md,
# A game project).
#
# It is a permanent target rather than a documentation snippet because a
# second client is the only thing that keeps the engine/game boundary honest
# (PHILOSOPHY T1). It links LabradorEngine and no game's code, so if anything
# it uses ever moves out of the engine and into a game, this stops building.
set(minimal_sources
states/confirm_state.cpp
states/hello_state.cpp
)
# The game's rules, in a library that links the engine's maths and nothing else
# of it: LabradorMath and the settings carry no window, no device and no input, so
# MinimalTests below runs them with none of those (rules/motion.h says what
# moved there to make that true). samples/linesweeper's LineSweeperRules is
# the same wall around a whole game.
add_library(MinimalRules STATIC
rules/motion.cpp
)
target_link_libraries(MinimalRules PUBLIC
LabradorMath
labrador_settings
)
# The rules' tests, with doctest from vcpkg. One ctest entry however many cases
# it holds; a new test file is listed here beside the first.
find_package(doctest CONFIG REQUIRED)
add_executable(MinimalTests
tests/motion_tests.cpp
)
target_link_libraries(MinimalTests PRIVATE
MinimalRules
doctest::doctest
labrador_settings
)
add_test(NAME MinimalTests COMMAND MinimalTests)
# A browser build is a second entry point and a page, with the content packed
# into the module at the paths the Windows build copies it to.
if(EMSCRIPTEN)
# The tests run under Node, which reads no files here. The root's options
# for that come after this folder is added, because the page must not
# take them, so the test names the one it needs.
target_link_options(MinimalTests PRIVATE -sENVIRONMENT=node)
add_executable(MinimalSample main_web.cpp ${minimal_sources})
target_link_libraries(MinimalSample PRIVATE
MinimalRules LabradorEngine labrador_settings)
set_target_properties(MinimalSample PROPERTIES SUFFIX ".html")
# Neither the page nor the content is a source, so a change to either
# relinks only because it is named here.
set_property(TARGET MinimalSample APPEND PROPERTY LINK_DEPENDS
"${CMAKE_CURRENT_SOURCE_DIR}/web/shell.html"
"${CMAKE_CURRENT_SOURCE_DIR}/content/manifest.json"
"${CMAKE_CURRENT_SOURCE_DIR}/content/fonts/jetbrains_mono_bold_16.spritefont"
)
target_link_options(MinimalSample PRIVATE
"SHELL:--embed-file ${CMAKE_CURRENT_SOURCE_DIR}/content@/"
"SHELL:--shell-file ${CMAKE_CURRENT_SOURCE_DIR}/web/shell.html"
-sENVIRONMENT=web)
return()
endif()
# dpi_aware.manifest declares per-monitor DPI awareness, so Windows does not
# stretch the frame on a scaled display; the file says what that means.
add_executable(MinimalSample WIN32
main.cpp
${minimal_sources}
dpi_aware.manifest
)
target_link_libraries(MinimalSample PRIVATE
MinimalRules
LabradorEngine
labrador_settings
)
# The start-up check: the game hidden, a few frames drawn, and out (main.cpp,
# SmokeTest). It needs a graphics device, so a machine without one fails it,
# and its content is what the build copies below, so a missing file fails it
# naming the file. The timeout is for a loop that never draws.
add_test(NAME MinimalSmokeTests COMMAND MinimalSample --smoke-test)
set_tests_properties(MinimalSmokeTests PROPERTIES TIMEOUT 60)
# A relative manifest path resolves against the executable's directory, not
# the working directory, and the folders it names against the manifest
# (engine/app/content_root.h), so mirror the content beside the exe. It is a
# target of its own because a POST_BUILD on the exe only runs when the exe
# relinks, so an edited asset would never arrive.
# copy_directory_if_different adds and updates but never removes: a file
# deleted from content/ stays in the build folder until it is cleaned, so a
# required file goes on loading here and is missing only from a clean build,
# and an optional bank is never replaced by the silent one. A game with
# content it may delete lists its files instead (the assets guide, "Optional
# content and stale copies").
add_custom_target(sample_content ALL)
add_custom_command(TARGET sample_content POST_BUILD
COMMAND "${CMAKE_COMMAND}" -E copy_if_different
"${CMAKE_CURRENT_SOURCE_DIR}/content/manifest.json"
"$<TARGET_FILE_DIR:MinimalSample>/manifest.json"
VERBATIM
)
add_custom_command(TARGET sample_content POST_BUILD
COMMAND "${CMAKE_COMMAND}" -E copy_directory_if_different
"${CMAKE_CURRENT_SOURCE_DIR}/content/fonts"
"$<TARGET_FILE_DIR:MinimalSample>/fonts"
VERBATIM
)
add_dependencies(MinimalSample sample_content)
# The release folder a player gets, from the x64-release build:
# cmake --install out/build/x64-release --prefix <folder>
# The program, the DLLs it loads, its content and the notices of what it
# carries. A debug build loads the debug runtime, which may not be given away.
if(NOT CMAKE_BUILD_TYPE STREQUAL "Release")
install(CODE [[message(FATAL_ERROR "Install the x64-release build.")]])
endif()
install(TARGETS MinimalSample RUNTIME DESTINATION .)
# DirectXTK and the XAudio2 redistributable, which vcpkg built as DLLs.
install(FILES $<TARGET_RUNTIME_DLLS:MinimalSample> DESTINATION .)
# The MSVC runtime, copied beside the program from Visual Studio's redist
# folder, so a player needs no installer: CMake's list of its DLLs, which
# leaves out vcruntime140_threads.dll and vccorlib140.dll.
set(CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_SKIP TRUE)
include(InstallRequiredSystemLibraries)
install(PROGRAMS ${CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS} DESTINATION .)
install(FILES content/manifest.json DESTINATION .)
install(DIRECTORY content/fonts DESTINATION .)
# The licences of what the program carries: the engine, the libraries
# compiled into it and the DLLs beside it. The font's is fonts/OFL.txt.
get_target_property(labrador_engine_dir LabradorEngine SOURCE_DIR)
set(vcpkg_share "${VCPKG_INSTALLED_DIR}/${VCPKG_TARGET_TRIPLET}/share")
install(FILES "${labrador_engine_dir}/../LICENSE"
DESTINATION notices RENAME Labrador.txt)
# NOTICE: the code in the engine that is not Labrador's to license.
install(FILES "${labrador_engine_dir}/../NOTICE"
DESTINATION notices RENAME Labrador-NOTICE.txt)
install(FILES "${labrador_engine_dir}/../external/rapidjson/license.txt"
DESTINATION notices RENAME rapidjson.txt)
install(FILES "${vcpkg_share}/directxtk/copyright"
DESTINATION notices RENAME DirectXTK.txt)
install(FILES "${vcpkg_share}/directxmath/copyright"
DESTINATION notices RENAME DirectXMath.txt)
install(FILES "${vcpkg_share}/xaudio2redist/copyright"
DESTINATION notices RENAME XAudio2Redist.txt)

It covers building the game, testing it, running it while you work on it and shipping it: the Windows half names the sources, puts the rules in a library with a test, links the engine and its settings, registers a start-up check and copies the content beside the program, and the EMSCRIPTEN branch builds the same game as a page with the content packed into it. The install rules at the end of the Windows half stage the folder a player gets: the program, the DLLs the engine uses on Windows, DirectXTK and the XAudio2 redistributable, the MSVC runtime, the content and the licence notices, and nothing from the build tree. Ship a Windows release explains them.

There is no project format and no code generator. The engine has no reflection macros, no second standard library beside std:: and no scripting language. Its headers contain classes, templates and the standard library, so reading the source is enough to know what it does (T12, the language over a dialect). Behaviour is written in C++ by everyone who writes it (T10), and your debugger, profiler and editor work on your game as they would on any other C++ program.

The cost. Every change to behaviour is a compile, and there is no hot reload. There is no visual editor and no property inspector, and nothing is serialised for you, because there is no reflection to do it with. Content (which textures and fonts, and in a larger game the levels and tuning) lives in JSON files read at startup, so changing it means restarting rather than rebuilding.

The engine meets your code at a few small interfaces: a State is a screen or mode of the game, a GameObject is anything that updates, draws and has bounds, and a CollisionObject is a game object that collides. What stands behind those interfaces is your choice. It can be a class per entity, as deep a hierarchy as you like, or one object standing for thousands of values.

LineSweeper, the falling-block sample, stands at the second end of that range twice. Its whole match is one 276-byte value with no pointers and nothing to destroy. Restarting is world = World{}, taking a snapshot is a copy, and comparing two matches is std::memcmp. Four compile-time checks keep it that way:

samples/linesweeper/rules/world.h
static_assert(std::is_trivially_copyable_v<World>,
"A World must be copyable by memcpy: restart is an assignment, and the "
"replay test compares two of them byte for byte.");
static_assert(std::is_trivially_destructible_v<World>,
"A World must own nothing. A member that needs a destructor is a "
"member that has an owner somewhere else.");
static_assert(std::has_unique_object_representations_v<World>,
"A World must have no padding bits and no floating-point members. "
"memcmp is only a defined comparison without padding, and this trait "
"is false for float - which is what keeps the rules integer-only and "
"the replay bit-exact on any compiler.");
static_assert(sizeof(World) == 276,
"The match is meant to stay small enough to copy without thinking "
"about it. If this fired because you added a member, read the number "
"and update it. If it fired because you reordered them, the padding "
"assert above is about to fire too.");

Its particle effect is ten thousand particles in one flat array behind one GameObject. That is three virtual calls a frame however many particles are alive, and one allocation when it is created. The sample’s design notes explain both decisions in detail.

The cost. The engine does not manage objects for you. There is no garbage collector, no entity-component system and no automatic serialisation, and ownership is explicit: Scene::add takes a std::unique_ptr and hands back a pointer you may use until the object is retired. Labrador is also not “stack-only” or free of virtual calls. The interfaces above are virtual, and containers own heap memory. The rule the engine follows is that every allocation has exactly one owner (T11), not that allocation is forbidden.

Labrador is for games played on one machine: single-player, side by side or split-screen. That focus shows up in three places.

  • Views. A Scene is drawn once per view: a rectangle of the window and a camera looking at the world. Split-screen is one view per player, refilled every tick as the cameras follow them. Drawing is const all the way down, so the views can be drawn on worker threads at the same time if a game asks for it.
  • Input. Four gamepad slots, with deadzones the game applies and press edges that ignore a pad that was not connected on both frames. Keyboard and mouse have the same shape, and a stick or a d-pad can be turned into menu directions with repeat.
  • Interface. A small widget set with focus and directional navigation, so menus work with a controller without a mouse.

samples/local_multiplayer starts with a two-player join screen: either keyboard half or any connected pad can claim a free player slot and choose READY. The sample owns those assignments and readiness. In the arena, each player reads its assigned input source and has a view with a following camera. Extending it beyond two players is game code. The local multiplayer guide walks through it, and the engine’s tests hold split-screen frames to reference images.

The cost. Online play is out of scope permanently: no netcode, replication or rollback will ever shape the engine’s design. 3D is permanently out of scope too. The math library is 2D by design, not by omission (Non-goals).

LineSweeper is built in three layers. rules/ is the whole game: piece movement, rotation, gravity, scoring. It is a static library that links nothing from the engine. presentation/ reads a match and draws it. states/ is the only layer that sees both, and it turns key presses into moves. Because the rules link nothing, the test suite can play complete matches with no window, no graphics device and no engine at all. This test records a match as a list of input bytes, replays it, and requires the two results to be identical byte for byte:

tests/linesweeper/replay_tests.cpp
SUBCASE("the recording is a vector of bytes and nothing else")
{
std::vector<std::uint8_t> recording;
World recorded;
for (std::uint32_t step = 0; step < 900; ++step)
{
const std::uint8_t input = scripted_input(step);
recording.push_back(input);
linesweeper::tick(recorded, input);
}
World replayed;
for (std::size_t index = 0; index < recording.size(); ++index)
{
linesweeper::tick(replayed, recording[index]);
}
CHECK(linesweeper::identical(recorded, replayed));
}

A project started from the minimal sample begins with the same split in miniature: its rules in a library that links only the engine’s maths, a test of them, and a start-up check, all in its ctest from the first build. Test your game shows how they work.

The engine’s own tests use hardware-free implementations: a renderer that records draw requests and an audio device that records playback requests. A consumer can inspect draws through the null renderer’s test-only internal interface at its engine pin. The draw-test guide shows the separate configure and a complete example. These recordings check requests and geometry; actual pixels and audible output have separate checks.

The cost. This separation is a design you choose and maintain. The engine makes it possible; it does not make it automatic, and a game that mixes its rules into its drawing code gets no help here. LineSweeper pays for its version with integer-only rules, durations counted in fixed ticks and tuning tables compiled into the code. Its design notes say what each of those cost.

Godot and Unreal are complete environments: an editor, an asset pipeline, an object model built around the editor, scripting (GDScript in Godot, Blueprint in Unreal) and export to many platforms. If you want to lay out levels visually, let designers change behaviour without compiling, or ship to many platforms, they are the better choice today.

Labrador gives those up to stay small enough to read. Your game is a C++ program you own rather than a project inside an environment. The engine’s object model is a few interfaces rather than a node tree or a reflected object graph, and nothing is collected behind your back. Unreal’s C++ is the comparison the design documents draw directly: its reflection macros and its own containers buy editor integration, serialisation, network replication and hot reload, and they mean reading the source is not enough to know what it does. Labrador has none of those features, and that is the trade.

These are libraries. They give you a window, input, drawing and sound, and leave the structure of your game to you. raylib in particular describes itself as programming without an editor or visual tools, so “no editor” is not what separates Labrador from them. What Labrador adds is the structure above the drawing calls:

  • a scene that owns your objects and runs each tick in order: update, collision, then the adds and removals that were requested during the tick, applied together at its end, so spawning something in the middle of an update is safe;
  • a state stack with typed results: push a “Really quit?” screen and receive a bool when it closes;
  • collision: layers and masks, a broad phase, a narrow phase that reports contact normals and depths, and resolution;
  • resources named in a manifest and resolved to handles once, at load;
  • views and cameras for split-screen, and a widget set with controller navigation.

The cost, measured against them: more structure to learn and accept, two platforms where they reach many (Windows, and a desktop browser through WebGL2), a far smaller community, and C++ only, with no bindings for other languages.

  • Five renderers behind one interface, chosen when you configure the build: Direct3D 11, Direct3D 12, OpenGL 3.3, Vulkan, and a null renderer for tests. The four that draw pixels are held to the same pixel tests and the same sixty-three reference images. CI runs those tests on both Direct3D renderers; OpenGL and Vulkan are checked on a machine with a graphics driver.
  • Warnings are errors, with no exceptions, and your game is compiled with the same settings as the engine.
  • The full CI sweep builds all five renderers.
  • Benchmarks check scaling, not stopwatch times: a step that is linear in the number of objects has to stay linear when the count quadruples, on any machine.

Labrador does not publish frame-time figures yet. Its low-end target is named (an integrated Radeon GPU at 1280×720, with the game held to four CPU cores) and has not been measured. When figures appear here, each will state the workload, the hardware, the configuration and how it was measured.

Labrador runs on Windows and in a desktop browser. The Windows build uses the tools in Get Started; its OpenGL renderer reaches the browser as WebGL2, through Emscripten. All six samples run there today. The full CI sweep loads each sample’s page in headless Chrome and quits it the sample’s own way, and LineSweeper has also been checked in Firefox. In Safari, only LineSweeper’s live demo has been tried: loaded and played briefly in Safari 27.0.1 on macOS.

Phones are a planned phase, not a supported platform. The browser build has touch controls and a layout for a phone held upright, but they have been played only under Chrome’s touch emulation, never on a real phone, so the hosted demo gives a phone a poster and a recording of the game to tap and watch, not the game itself, until real iPhone checks and the host page’s phone layout pass. Android remains unverified.

The Vulkan renderer exists because Vulkan is the graphics interface that reaches Android, Linux and, through MoltenVK, Apple’s platforms, but none of those are supported or built today. Treat Vulkan as the route to them, not as support for them.

The Android port plan is scoping: no Android port has been built. It places iOS after Android and ends at “the engine runs”, with packaging and store work outside its scope. There is no Linux or macOS port plan in this repository.

An additional native platform is called supported when all five conditions hold:

  • A game needs that platform.
  • A maintained build preset runs in CI.
  • A run on a real device is recorded.
  • A performance p99 is measured with its workload, device and configuration stated.
  • There is a path to package the game for players.

Documentation for Labrador v0.3.0. Built from Labrador 0f4f503 of 2026-11-03.

All documentation versions