Skip to content

States and the stack

A state is a screen or a mode of your game: a title screen, a match, a pause menu, a “Really quit?” box. Each is a class implementing State, and the engine keeps them on a stack, StateContext, which Application is. The stack is the only flow machinery the engine has. Where another engine would have a scene graph of menus or a state-machine asset, Labrador has states you push and pop from C++.

  1. You construct it, usually with std::make_unique, and hand it to the stack.
  2. The stack makes it live: it gives the state its context and calls init(), before the state’s first update() and before it is next drawn. Build what the state draws in init(): anything that resolves a resource by name needs the content loaded, and a game loads its content before app.run makes the first state live.
  3. Every step it is on top, it gets update(dt), and every frame it is visible it gets draw(renderer).
  4. When it is popped or replaced, the stack destroys it. Release what it set up in its destructor; the services it borrowed are still alive at that point, even when the application is shutting down.

All three are called on this->context() from inside a state:

Call What it does
transition_to(state) Replaces the top state. The first state is installed this way by app.run.
push(state) Puts a state above the current one, which is suspended: it stops being updated.
pop() Takes the top state off. The one below resumes.

They are safe to call from inside your own update(), which is where you will almost always call them. Replacing or popping a state destroys it, so taking effect immediately would destroy the object whose update() is still running. Instead the operation is queued and applied once that call returns. You can call pop() and then simply return.

A pushed state can hand a result back to whoever pushed it. The type is named at the push and checked at the pop. This is how the minimal sample asks before quitting:

samples/minimal/states/hello_state.cpp
void HelloState::ask_to_quit()
{
// Ask, rather than quit. The result type is named here and matched
// at the pop; the question knows nothing about this state, and the
// callback runs once, when it closes, rather than being a flag read
// on every frame until something sets it.
this->context()->push<bool>(
std::make_unique<ConfirmState>(this->app_, L"Really quit?"),
[this](const bool& quit)
{
if (quit)
{
this->app_->quit();
}
});
}

The question, ConfirmState, knows nothing about the screen below it. It answers by popping, with true here and false when B or Escape is pressed:

samples/minimal/states/confirm_state.cpp
if (confirm_requested)
{
this->context()->pop(true);
}

The callback runs once, after ConfirmState has been destroyed and HelloState has resumed. There is no flag to poll every frame and no pointer from the question back to its asker. Popping with a type the push did not ask for throws, rather than reinterpreting the value.

The result does not have to be a bool. LineSweeper’s pause menu answers with an enum class PauseChoice { resume, restart, quit }, and the play state’s callback is a switch. There is also a push(state, on_closed) for a screen whose only answer is that it closed.

Only the top state is updated. Whether the states below it are drawn depends on the top state’s covers_screen(), which is true by default. The stack finds the topmost state that covers the screen and draws from there upward, so a box over a running game says false:

samples/minimal/states/confirm_state.h
// A box over the screen, not a replacement for it - so the state below
// keeps drawing and this appears on top of it.
bool covers_screen() const override { return false; }

and then draws over whatever is already in the view:

samples/minimal/states/confirm_state.cpp
void ConfirmState::draw(Renderer& renderer) const
{
// The state below has already drawn into this view, and this draws over it.
// Nothing here has to know that, and it does not set the view count: the
// state that fills the screen decides how many views the frame has.
DrawList list = renderer.view(0);
this->prompt_->draw(list);
}

A state that is covered is told twice: on_suspend() when something is pushed above it, and on_resume() when that has popped. Not being updated stops a state’s simulation and nothing else, so these are where a game does the rest: pauses its music, stops a looping sound, dims itself. The minimal sample dims its greeting:

samples/minimal/states/hello_state.cpp
void HelloState::on_suspend()
{
this->greeting_->set_colour(labrador::Colour::dim_gray);
}

The X button, Alt+F4 and the native system menu ask the top state’s on_close_requested(). Its default answer is true, which closes immediately. Return false to keep running while your game asks a question or saves its work. The development minimal template uses the same question as Escape:

samples/minimal/states/hello_state.cpp
bool HelloState::on_close_requested()
{
this->ask_to_quit();
return false;
}

The stack keeps that state alive until the callback returns, then applies its pushes, pops and transitions. Later requests ask the new top; ConfirmState returns false so repeated X presses leave one question open. Recursive requests during the callback or its stack changes are ignored. Once the player answers yes, Application::quit() closes without asking again. Destruction also asks nothing.

This hook is for native close requests. It cannot veto browser tab closure, page navigation, session shutdown or forced termination. The browser game’s own Quit button still calls quit() and lets the host page decide what follows.

Alt-tab, minimising and the machine going to sleep are a different question from being covered. They mean nobody is looking at any state, so every live state is told, from the top down, through on_deactivated() and later on_activated(). The states below the top need this most: a match under a pause menu is not being updated, but it may still be holding a music track.

While the window is in the background, gamepads read as disconnected, which is a neutral input. A match that ignores on_deactivated() therefore keeps running with nobody playing it. Each change arrives once, however many separate Windows messages caused it, so a state can pause in one and resume in the other without keeping a flag. A state created while the window is already in the background asks context()->active() in its init(), because it missed the change. A minimised window is not drawn, but its states are still updated, at the same rate (The tick).

In a browser the background is a hidden tab. A click elsewhere on the page takes the keyboard and the mouse from the canvas and releases whatever they held, but the player may be on a pad and has not left, so the pads go on reading and no state is told.

  • A level is a state that owns a scene. The minimal sample, LineSweeper’s play state, the audio sample, the components gallery and the local-multiplayer sample do exactly this: the state owns a Scene, init() fills it, update() steps it, draw() draws it. The collision sample’s state owns an Arena that owns the scene, so its tests step the arena with no state at all. Add a screen to your game and Add a second level write such states in the starter project.
  • Menus are states. A main menu at the bottom of the stack, a match pushed above it, and a pause menu pushed above that. Leaving the match pops back to the menu, which was never destroyed.
  • One answer per question. If two screens need to report the same choice, give it a type (an enum class) and let each push name it.
  • Something that sees every frame is a root state that owns a stack. Only the top state is updated, so a developer console or a frame-time overlay that must run whatever is on top is not pushed. It is the one state on the application’s stack, and it owns a StateContext that holds the game’s: its update() runs its own code and then the game’s, its draw() draws the game and then draws over it, and it forwards activation and close requests. The engine’s own tests hold this shape, below.
tests/core/state_context_tests.cpp
class RootState : public State
{
public:
explicit RootState(std::vector<std::string>* log) : log_(log) {}
// Where the game's states go: push, pop and transition_to here, never
// on the Application.
StateContext& game() { return this->game_; }
void init() override
{
// Built while the application is in the background, the owned
// stack has to start out knowing it.
this->game_.notify_activation(this->context()->active());
}
void update(float dt) override
{
this->log_->push_back("root:before");
this->game_.update(dt);
// The game's update has finished, so this is where a capture goes.
this->log_->push_back("root:after");
}
void draw(Renderer& renderer) const override
{
this->game_.draw(renderer);
// And the overlay, over whatever the game drew.
this->log_->push_back("root:draw");
}
void on_activated() override { this->game_.notify_activation(true); }
void on_deactivated() override { this->game_.notify_activation(false); }
bool on_close_requested() override { return this->game_.notify_close_requested(); }
private:
std::vector<std::string>* log_ = nullptr;
StateContext game_;
};

The game’s states push and pop on the root’s stack through their own context(). That is what adopting the pattern late costs: every push and transition_to the game made on the application moves to the owned context, and so does anything that asked the application for its depth(), which stays 1 while the root runs.

Next: The tick.

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

All documentation versions