Skip to content

What a game is to the engine

To Labrador, a game is a set of states plus content. There is no Game class to derive from and no IGame to implement. Your program constructs the engine’s Application, says what it needs before a window exists, loads the content its manifest names, and hands the engine a first state. This is the minimal sample’s main.cpp, from its options to its first state:

samples/minimal/main.cpp
options.window_class_name = L"MinimalSampleWindowClass";
// ASCII only: this file gets copied into new projects, and a wide
// literal's encoding depends on how the compiler was told to read the
// source.
options.window_title = L"Labrador - minimal sample";
options.resolution = ScreenResolution::s_1280_720;
// A smoke test gets the whole shell - window, device, services - with
// nothing on screen and no focus taken.
options.visible = !smoke_test;
// The hidden smoke still presents each frame. Request no display
// sync interval so this check can run on software-only CI.
options.vsync = !smoke_test;
// One pane, so one view's worth of recording state. The default is four
// - four-player split-screen, the widest layout the engine has a client
// for - and every view above what a frame draws is a deferred context
// and a dynamic vertex buffer created at startup and never used.
// A game that fans out says so here; this one does not.
options.view_capacity = 1;
#if defined(GAME_HAS_ICON_RESOURCE)
// CMake enables this block only when GAME_ICON_FILE selects your icon.
options.window_icon_resource = L"GAME_ICON";
#endif
Application app(std::move(options));
#if defined(LABRADOR_SAMPLE_PROCESS_OBSERVATIONS)
minimal_observation::ProcessReport process_report(&app, smoke_test,
LABRADOR_OBSERVATION_SOURCE_REVISION);
#endif
app.initialize();
// Everything this sample draws, named in content/manifest.json. A game
// with its own kinds of asset - levels, dialogue, whatever it has -
// teaches them to app.resource_loader() before this line.
//
// Beside the executable, wherever the executable was started from:
// a relative path here is relative to the game, not to the working
// directory (Application::load_manifest), and the build copies the
// content there.
app.load_manifest("./manifest.json");
std::unique_ptr<State> first_state = std::make_unique<HelloState>(&app);
if (smoke_test)
{
first_state = std::make_unique<SmokeTest>(&app, std::move(first_state));
}
return app.run(std::move(first_state));

run returns when the window closes. Everything between those lines (the window, the graphics device, the input devices, the frame loop) is the engine’s. The smoke_test lines are the game’s start-up check, which Test your game explains.

If the C++ declarations in these excerpts are unfamiliar, Reading the C++ in minimal explains inheritance, ownership, callbacks and the sample’s rendering vocabulary.

One rule decides what form each idea in the engine takes (Structural types):

Where Form Examples
The engine calls code it has never seen An interface you implement State, GameObject, CollisionObject
The engine provides machinery you drive A concrete class you use Application, Scene, the widgets, the resource tables
The idea is your game’s policy No type at all There is no Player, Level, Match or Team

The third row matters as much as the first two. The parts of “a player” that every game needs already exist as an input slot and a view, and everything else about one belongs to your game. A game’s level is a class of yours that owns a Scene and adds the rules.

State is a screen or mode: a title screen, a match, a pause menu. The engine calls its init() once, then update(dt) every step and draw(renderer) every frame, and tells it when something covers it. States and the stack covers the rest.

GameObject is anything a scene updates and draws. It has three obligations:

virtual void update(float dt) = 0; // change things here
virtual void draw(DrawList& draw_list) const = 0; // and only read them here
virtual labrador::RectangleF bounds() const = 0; // where it is, for culling

CollisionObject is a GameObject that also has a shape, a collision layer and mask, a tag the engine never interprets, and an on_contact callback. Its header, engine/collision/collision_object.h, has the details.

What stands behind those interfaces is up to you. A game can register one object per entity, with as deep a class hierarchy as its author likes, or one object that stands for thousands of values updated in a tight loop. The engine treats both the same: interface granularity is the dial you turn for performance.

That batching choice applies to ordinary values updated and drawn by a GameObject. Each CollisionObject supplies one Shape. For the scene to sweep independent geometry, register a separate collision object for each shape. A container of rectangles inside one game object is not automatically registered for collision, and Scene has no compound or batched-collider registration API.

LineSweeper turns it both ways in the same scene. Its board, its particle field and its game-over banner are one object each, and the particle field is ten thousand particles in one flat array, which costs three virtual calls a frame however many are alive. Beside them are two ordinary labels and the touch controls. All six are added to one scene in the play state’s init(), the first three like this:

samples/linesweeper/states/play_state.cpp
this->board_ = this->scene_->add(std::make_unique<BoardView>(
&this->world_, resources, &this->palette_));
// Register after the board so sparks draw over its cells. The field
// compares successive Worlds to find events and reads last_tick_ for
// the locked piece that compaction can hide. StepPosition supports
// const extrapolation between updates, including suspension detection.
this->particles_ = this->scene_->add(std::make_unique<ParticleField>(
&this->world_, &this->last_tick_,
resources->resolve_texture(block_texture_name),
&this->app_->step_position(), this->motion_, &this->palette_));
// The top-out message must draw over the burst on its first frame.
this->banner_ = this->scene_->add(
std::make_unique<TopOutBanner>(&this->world_, resources));

Each of those objects holds a pointer to the match, world_, and reads it. None of them can change it: the match is a value the play state owns, and the presentation code that draws it does not include the code that steps it.

There is no garbage collector and no object graph kept alive behind your back. Every allocation has exactly one owner (T11), and the API says which side owns what:

  • The application owns the services. app.renderer(), app.keyboard(), app.render_resources() and the rest return pointers you borrow. They are created once, in initialize(), and are never replaced, so a state may hold one for its whole life.
  • The scene owns what you add to it. Scene::add takes a std::unique_ptr and returns a plain pointer of the object’s own type, for the things your game still needs to speak to. The minimal sample keeps the greeting this way, to move it each frame. The pointer is a loan, valid while pending and after admission until that particular object is removed, retired or destroyed with the scene. Keeping it, including in a callback, does not extend the object’s lifetime. Independently registered colliders transfer ownership this same way; there is no borrowed-registration overload for elements in another owner’s vector.
  • States are owned by the stack. You construct one with std::make_unique and hand it over; the stack destroys it when it pops or is replaced.

The Scene::collision_objects() span is also borrowed: the next end_tick rebuilds it. Copied object pointers retain only their individual loans above. Contacts have a shorter inspection window: their span and copied participant pointers expire at the next resolve, end_tick or scene destruction.

This is not a promise that Labrador avoids the heap or virtual calls. The interfaces above are virtual, and containers own heap memory. The rule is about ownership, not about allocation.

What the engine provides, and what it leaves to you

Section titled “What the engine provides, and what it leaves to you”
The engine provides Your game provides
The window, the device, the frame loop and a fixed time step What happens each step
A scene that updates, collides, culls and draws what you add The objects, and what a contact means
Views and cameras, and drawing them in parallel Where the views go and what the cameras follow
Keyboard, mouse and four gamepads, with press edges and deadzones What each key and button does
A widget set with focus and directional navigation The menus
A manifest of named content, resolved to handles at load The content
The state stack The states

The engine routes on data it does not interpret: collision layers and masks, tags, names. Its headers contain no game nouns. If a file would have to change for your game to work, it is game code, and it belongs in your project rather than in the engine (The boundary).

Next: States and the stack.

Development documentation (unreleased). Built from Labrador aceb130 of 2026-11-20.

All documentation versions