State
Generated from engine/core/state.h at f525bc6. The text under each declaration is the header's own comment, word for word. About the reference says how these pages are made.
Audience: game code.
#include "engine/core/state.h" · namespace labrador
class State
Section titled “class State”A screen or overlay owned by StateContext, normally Application. The context enters it when a push or transition takes effect: it assigns context(), then calls init() before the first update() or draw().
State · ~State
Section titled “State · ~State”virtual ~State() = default;update
Section titled “update”virtual void update(float dt) = 0;The seconds since the last update. Frame time is a parameter, not shared state (PHILOSOPHY, Services and lifetimes).
Only the top of the stack is updated. A state with something above it is suspended: see on_suspend().
const, and taking the renderer.
const is not decoration here. Every draw below this line runs on the same objects from every render worker at once, and this is the line where the compiler starts holding them to it: a draw helper that writes a member is a compile error rather than a race.
The state declares how many views this frame has and fills them; it does not submit. begin_frame / submit / end_frame belong to whoever owns the frame, which is the shell, and a state that calls any of them from draw() is outside this contract. A state that needs a frame of its own - a capture - takes it in update() (Renderer::read_back_buffer says how).
virtual void init() = 0;Called once when this state enters the stack, after context() is set and before its first update() or draw(). A push or transition issued inside another state's update() or init() waits until that call returns. Resuming a covered state calls on_resume(), not init().
covers_screen
Section titled “covers_screen”virtual bool covers_screen() const;Whether this state fills the frame on its own.
The stack draws from the topmost state that says yes, upward - so a pause menu, which is a box over a running match, says no and the match underneath keeps drawing. Everything else is a screen and the default is therefore true: a state that replaced the whole frame and forgot to say so would be drawn over a stale one below it, which is a bug you see; a state that covers the screen and pays for one hidden draw of what is under it is a bug you do not.
It is asked once per frame, before any drawing, so it is not on the per-object path and there is no T8 cost to it being virtual.
on_suspend
Section titled “on_suspend”virtual void on_suspend();Something was pushed above this state. It stops receiving update() and - unless the state above covers the screen - keeps receiving draw() until that thing pops.
This is where "quiet down while something is above me" goes, because not being updated cannot do it: a looping voice keeps playing precisely because the update that would have stopped it is the one being skipped.
on_resume
Section titled “on_resume”virtual void on_resume();Whatever was above this state popped, and it is the top again. Runs before the result callback the push was given, so the callback sees a stack that has already finished changing shape.
on_activated · on_deactivated
Section titled “on_activated · on_deactivated”virtual void on_activated();virtual void on_deactivated();The application got or lost the foreground: alt-tab, minimise, a power suspend, or coming back from any of them.
A DIFFERENT QUESTION FROM on_suspend. on_suspend means "something was pushed above me" and is asked of one state; these mean "nobody is looking at any of us", which is a fact about the window that no state can see. While the application is in the background the pad reader is suspended and answers "disconnected" for every slot, which is a neutral input that nothing downstream questions - so a match that is not told plays itself out with nobody in it: the characters standing still, the clock running down, and the music at full volume over whatever the player switched to.
EVERY STATE ON THE STACK IS TOLD, top down, not the top one alone. A match under a pause menu is not being updated and is still holding the music and a looping weapon voice, so the state that most needs to hear this is the one furthest from the top.
AN EDGE, so a state may pause here and resume there without keeping a bool of its own. Windows offers no such guarantee - deactivating and then minimising is two separate messages that both mean "not in front of the player" - and StateContext::notify_activation is where the sources collapse into one question, so it is where the edge is made. A state constructed while the application is already inactive missed the edge and is told nothing; it asks StateContext::active().
on_close_requested
Section titled “on_close_requested”virtual bool on_close_requested();A native window's X, Alt+F4 or equivalent close request. Only the top state is asked. Return true to allow immediate closure, or false to keep running, including while a game-owned confirmation is open. Stack changes wait until this callback returns. Application::quit() is final and bypasses this hook. Browser tab closure, navigation and forced process/session termination cannot be vetoed here.
set_context
Section titled “set_context”context (protected)
Section titled “context (protected)”Related types
Section titled “Related types”Named in the public declarations above: Renderer, StateContext.
In the samples and tests
Section titled “In the samples and tests”The files that include this header directly. A file can also reach it through another header.
samples/audio/audio_state.hsamples/collision/collision_state.hsamples/components/gallery_binding_tests.cpp,gallery_state.hsamples/linesweeper/states/pause_state.h,play_state.hsamples/linesweeper/web/pacing_state.hsamples/local_multiplayer/join_state.h,play_state.hsamples/minimal/main.cppsamples/minimal/states/confirm_state.h,hello_state.htests/app/application_loop_tests.cpp,application_order_tests.cpp,application_reveal_tests.cpp,application_scripted_pad_tests.cpp,startup_child.cpptests/scene/order_tests.cpp
Explained in
Section titled “Explained in”Documentation for Labrador v0.4.0. Built from Labrador f525bc6 of 2026-11-17.