The tick
A Labrador game advances in fixed steps and draws in frames. The two are separate: the simulation steps at the rate the game asks for, sixty times a second by default, and a frame is drawn whenever the window is free to draw one. This page follows one pass through the loop from the top.
flowchart TD
A["Window has no messages waiting"] --> B{"Is a step due?"}
B -- "yes, once per step owed" --> C["Read the keyboard, mouse and gamepads"]
C --> D["Top state's update(dt)"]
D --> E["Audio update"]
E --> B
B -- "no" --> F["Draw a frame: states draw their views, then present"]
F --> A
The step
Section titled “The step”ApplicationOptions::target_fps sets the step, and the engine’s clock runs update as many times
as wall-clock time says are owed, then draws a frame. On a display that refreshes at the step’s
rate that is usually once per frame. On a faster display, 120 or 144 Hz against the default 60,
most frames owe no step and draw the same one again, which
Drawing between steps below is about. After a slow frame it is
several times in a row, at full speed, before the next frame is drawn. At most a tenth of a
second is ever owed at once, so a game paused in a debugger does not run a minute of updates when
it resumes.
Because the step is fixed, the dt passed to every update is the same value: 1/60 of a second
at the default. Write movement against dt all the same, as the minimal sample does, so the code
does not depend on the rate. A game whose rules must be exact can count steps instead.
LineSweeper does: every duration in its rules is a number of ticks, and its main.cpp sets
target_fps to 60 as a rule of the game, not a preference.
When your game blocks on purpose (loading a level, say), call app.reset_elapsed_time()
afterwards. Otherwise the time spent loading is owed as steps, and the next frame runs them all
on a world nobody has seen yet. A state reaches the application through the pointer it keeps,
app_ in the starter’s states, so in a state’s update(), after the slow part:
this->load_next_level(); // a slow load, here a function of your ownthis->app_->reset_elapsed_time();Input is read first
Section titled “Input is read first”Each step begins by reading every input device, before any state’s update runs. A “pressed”
answer therefore means down now, and not down at the last step, measured across the same
boundary for every device: a key and a gamepad button pressed together report together. A key
pressed and released between two steps is not seen at all, which at sixty steps a second no
person can do. The input devices are services you borrow from the application, and you ask them
questions during update; the input guide covers them.
A scene’s four phases
Section titled “A scene’s four phases”Inside the top state’s update, a state that owns a Scene
steps it in four phases, in this order:
scene->update(dt)steps every object once: collision objects first, then the rest, each kind in the order its objects were added. An object added during the tick is first stepped on the next one.scene->resolve()finds overlapping pairs in collision registration order. Each live pair is remeasured before bothon_contacthalves receive that one overlap and opposite normals. A response may mutate either participant. A started pair finishes both halves. Earlier responses can separate or retire participants before later pairs. The pre-response snapshot atscene->contacts()includes pairs skipped during dispatch and stays readable until the next resolve or end of the tick. Callend_tickafter resolution to apply pending scene changes and destroy retired objects.- Your own phase, if you need one: anything that depends on where the contacts left things,
such as moving a held item to follow a body a contact just pushed. The engine has no function
for this. Write a loop between
resolve()andend_tick(). scene->end_tick()applies everything that waited for the tick to be over. Collision objects outside the scene’s bounds, if it has bounds, are flagged for deletion; every flagged collision object is destroyed; and every object added during the tick joins the scene.
A game with no collision skips phases 2 and 3. The minimal sample and LineSweeper do this; the collision guide runs all four. This is LineSweeper’s whole play-state update after its pause and restart checks:
this->last_tick_ = tick(this->world_, this->gate_.pass(this->read_input()));
this->controls_->set(this->arrangement_, controls_held(this->arrangement_, touch.points()), this->touch_seen_);
this->scene_->update(dt);this->scene_->end_tick();samples/linesweeper/states/play_state.cpp, lines 370–377 at aceb130
tick() is the game’s own rules, a function in the sample that steps the match by exactly one
step. The scene then steps the objects that draw it.
Why adds wait for the end of the tick
Section titled “Why adds wait for the end of the tick”Scene::add gives you a pointer to the new object straight
away, but the object does not join the scene until end_tick(). Objects are added in the middle
of a tick: a weapon fires, a piece spawns. If the add went straight into the list the scene is
walking, it could invalidate that walk. Waiting also means an object added this tick is first
collided with on the next one, so a shot does not hit something on the frame it leaves the
barrel.
The same rule explains a line the minimal sample and LineSweeper have after filling their scene in init():
// Every add is pending until a tick ends, so that a weapon firing mid-tick// cannot invalidate the loop walking the objects. Nothing has ticked yet// and the first frame is a real frame, so the first tick ends here.this->scene_->end_tick();samples/minimal/states/hello_state.cpp, lines 101–104 at aceb130
What is removed, and when
Section titled “What is removed, and when”A collision object leaves the scene at the end of the first tick, after the one it was added in,
in which its for_deletion() answers true, and the pointer add returned stops being valid then.
set_for_deletion(true), which a game calls and which the scene itself calls on an object that
has left its bounds, gets an object there only if the object records the request. The default
ignores it, as a wall’s should, so a collision object that keeps that default is never removed,
even outside the bounds; the
collision guide says what that means.
Any object, plain or collision, leaves when the game asks: scene.remove(object) takes it out
at the next end_tick, after the retirements and before the adds, so an object may remove itself
from its own update and one added and removed in the same tick is never admitted. The other
objects keep their order. Nothing else removes a plain GameObject; it stays until the scene is
destroyed. Removal is for the objects a game drops now and then, such as a score that has floated
away. Thousands of short-lived things are values inside one object, as LineSweeper’s particles
are.
Then a frame is drawn
Section titled “Then a frame is drawn”After the steps that were owed, the engine draws one frame: it begins the frame, asks the states to draw (from the topmost state that covers the screen upward, as States and the stack describes), submits what they recorded, and presents. Nothing is drawn before the first step has run.
A minimised window is the one case with steps and no frames. On Windows the steps go on at
their rate and nothing is drawn, and between steps the loop sleeps where it otherwise never
waits. A sleep can end late, and the steps then owed run together, as they do
after any slow frame. frame_timings() stands still until the window is restored. A window
that was created hidden, as a smoke test’s is, is not minimised and draws as usual.
Drawing reads what the steps wrote and changes nothing. That rule is what makes the frame safe to draw on several threads at once, and it is the subject of the next page.
Drawing between steps
Section titled “Drawing between steps”On a 144 Hz display a game stepping 60 times a second draws each step’s state on two or three
frames in a row. Anything that moves repeats a position and then jumps. That is judder, and it
is why a display faster than the step shows nothing smoother for anything drawn straight from
the last update.
Application::step_position() says where the frame falls. Its StepPosition has two members:
step, the number of updates run so far, and fraction, how far past that step the frame is as
a share of one step, at least 0 and less than 1. The engine moves nothing with it. Each drawable
chooses what to do:
- Draw where the last update left it. Everything does this unless it asks. It is the only right answer for something that must not be seen between places, such as a cell on a grid.
- Interpolate. Keep where it was one step back as well, and draw it
fractionof the way from there to where it is now. It never overshoots, and it is drawn up to one step late. - Extrapolate. Carry it on along its velocity by
fractionof a step. It is not late, and it can overshoot when the motion turns.
application.h sets one more rule: a state that was not updated must not use the fraction.
Only the top state is updated. A match drawn under a pause menu has stopped, while the fraction
goes on cycling every step, so a drawable that used it there would shimmer back and forth. That
is what step is for: record it in update(), and in draw() use the fraction only if it is
unchanged. LineSweeper’s sparks extrapolate this way. Their update() records the step:
if (this->step_ != nullptr){ this->stepped_at_ = this->step_->step;}this->step_seconds_ = dt;samples/linesweeper/presentation/particles.cpp, lines 146–150 at aceb130
and draw() asks how far to carry each spark, which is nothing when the field was not updated on
the latest step:
float ParticleField::lead() const{ if (this->step_ == nullptr || this->step_->step != this->stepped_at_) { return 0.0f; }
return this->step_->fraction * this->step_seconds_;}samples/linesweeper/presentation/particles.cpp, lines 393–401 at aceb130
On a display at the step’s own rate the fraction barely moves from one frame to the next, and
nothing drawn with it looks different. The starter’s greeting is drawn where update puts it;
Smooth movement on a fast display
interpolates it.
Next: Drawing, views and cameras.
Development documentation (unreleased). Built from Labrador aceb130 of 2026-11-20.