Skip to content

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

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 own
this->app_->reset_elapsed_time();

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.

Inside the top state’s update, a state that owns a Scene steps it in four phases, in this order:

  1. 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.
  2. scene->resolve() finds every overlapping pair of collision objects and tells both participants, through on_contact. The list of contacts stays readable from scene->contacts() until the end of the tick, so a game or a test can see what touched what.
  3. 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() and end_tick().
  4. 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:

samples/linesweeper/states/play_state.cpp
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();

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.

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():

samples/minimal/states/hello_state.cpp
// 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();

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.

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.

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 fraction of 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 fraction of 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:

samples/linesweeper/presentation/particles.cpp
if (this->step_ != nullptr)
{
this->stepped_at_ = this->step_->step;
}
this->step_seconds_ = dt;

and draw() asks how far to carry each spark, which is nothing when the field was not updated on the latest step:

samples/linesweeper/presentation/particles.cpp
float ParticleField::lead() const
{
if (this->step_ == nullptr || this->step_->step != this->stepped_at_)
{
return 0.0f;
}
return this->step_->fraction * this->step_seconds_;
}

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.

Documentation for Labrador v0.4.0. Built from Labrador f525bc6 of 2026-11-17.

All documentation versions