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:
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";
// A smoke test gets the whole shell - window, device, services - with // nothing on screen and no focus taken. options.visible = !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
#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");
if (smoke_test) { first_state = std::make_unique<SmokeTest>(&app, std::move(first_state)); } return app.run(std::move(first_state));samples/minimal/main.cpp, lines 110–156 at f525bc6
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.
Three kinds of type
Section titled “Three kinds of type”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.
The interfaces are small
Section titled “The interfaces are small”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 hereCollisionObject 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.
How big an object is, is your choice
Section titled “How big an object is, is your choice”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:
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));samples/linesweeper/states/play_state.cpp, lines 104–118 at f525bc6
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.
Ownership is explicit
Section titled “Ownership is explicit”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, ininitialize(), and are never replaced, so a state may hold one for its whole life. - The scene owns what you add to it.
Scene::addtakes astd::unique_ptrand 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_uniqueand 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.
Documentation for Labrador v0.4.0. Built from Labrador f525bc6 of 2026-11-17.