Skip to content

Collision

The collision sample puts a blue player in an arena with grey walls, a green trigger and a purple rectangle that deliberately rejects contacts. Move into a wall to stop and slide along it; walk through the trigger to count an entry. All the code below comes from the runnable collision sample. If a build fails after you bring some of it into your own game, Read a build error shows how to read the error.

The sample is in the engine’s folder, not in your game, and your game’s build does not make it. In the x64 Native Tools Command Prompt, these commands go to the engine’s folder in a starter project, configure and build there, and start the sample. From a clone, the first line is cd /d C:\dev\Labrador instead. Run the samples says how long each step takes, what it prints, and what each failure means.

Terminal window
cd /d C:\dev\mygame\external\labrador
cmake --preset x64-debug
cmake --build --preset x64-debug --target CollisionSample CollisionSampleTests
out\build\x64-debug\samples\collision\CollisionSample.exe

Use WASD, arrows or the left stick to move, R or gamepad Y to reset, and Escape or gamepad B to quit. The sample reads only the first gamepad slot, slot 0, so a pad Windows has put in another slot, as it can after another pad is unplugged, does nothing here; unplug every pad and plug the one in again, or use the keys. A single-player game accepts every slot shows how the starter reads all four instead. The content is copied beside the executable, so it can start from any working directory. The whole arena fits the window when it is resized.

Walk right through the purple rectangle, stop at the grey wall, then go around the wall into the green trigger. Gold means the player measured a wall contact this tick; green means it is overlapping the trigger. The HUD shows the current contact count and how many times the player has entered the trigger.

CollisionObject extends GameObject: it can update and draw, and also supplies its collision shape, layer, mask, tag and contact callback. bounds() is the broad-phase extent; shape() is the geometry the narrow phase measures. Here both come from the same rectangle, which is also the sprite destination:

samples/collision/body.cpp
RectangleF Body::bounds() const { return this->rectangle_; }
const Shape* Body::shape() const { return &this->rectangle_; }

A layer is one bit. A mask is the set of layers the object accepts. The engine does not name them for you:

samples/collision/body.h
constexpr labrador::CollisionLayer player_layer = 1u << 0;
constexpr labrador::CollisionLayer wall_layer = 1u << 1;
constexpr labrador::CollisionLayer trigger_layer = 1u << 2;
constexpr labrador::CollisionLayer decoration_layer = 1u << 3;

Both masks must agree. The player accepts walls, triggers and decoration, but decoration accepts nothing, so walking through purple produces no contact:

samples/collision/body.cpp
CollisionMask Body::mask() const
{
switch (this->kind_)
{
case BodyKind::player: return wall_layer | trigger_layer | decoration_layer;
case BodyKind::wall:
case BodyKind::trigger: return player_layer;
case BodyKind::decoration: return 0u;
}
return 0u;
}

tag() carries the sample’s BodyKind classification. Unlike a layer, the tag does not filter anything; the callback reads it to choose what a contact means.

The engine measures overlaps and calls both participants once with opposite normals. The normal points from this object towards the other. The sample moves the player away using separation(normal, penetration) and removes only the velocity component into the wall using slide(velocity, normal):

samples/collision/body.cpp
void Body::on_contact(const CollisionObject& other,
const Vector2F& normal, float penetration)
{
if (this->kind_ != BodyKind::player)
{
return;
}
if (other.tag() == static_cast<CollisionTag>(BodyKind::wall))
{
const Vector2F movement = separation(normal, penetration);
this->rectangle_.x += movement.x;
this->rectangle_.y += movement.y;
this->velocity_ = slide(this->velocity_, normal);
this->touching_wall_ = true;
}
else if (other.tag() == static_cast<CollisionTag>(BodyKind::trigger))
{
this->touching_trigger_ = true;
}
}

The wall ignores its callback. A trigger marks the player’s overlap without moving it or changing its velocity. These are game decisions: Scene::resolve does not automatically push every pair apart.

Body::update clears the contact flags before each sweep and moves its rectangle by velocity times dt. The same rectangle supplies collision and drawing, so there is no second position to synchronise.

The arena owns one Scene and keeps a borrowed pointer to its player. Scene::add takes ownership but defers admission until end_tick; the arena calls it once after adding its initial objects so the first frame can draw them.

Each step clamps the input direction, moves the objects, measures and responds to collisions, observes the results, and finishes the tick:

samples/collision/arena.cpp
void Arena::step(Vector2F direction, float dt)
{
constexpr float move_speed = 240.0f;
if (direction.length_squared() > 1.0f)
{
direction.normalize();
}
this->player_->set_velocity(direction * move_speed);
this->scene_.update(dt);
this->scene_.resolve();
this->contact_count_ = this->scene_.contacts().size();
this->hit_wall_ = this->hit_wall_ || this->player_->touching_wall();
const bool in_trigger = this->player_->touching_trigger();
if (in_trigger && !this->was_in_trigger_)
{
++this->trigger_entries_;
}
this->was_in_trigger_ = in_trigger;
this->scene_.end_tick();
}

The trigger-entry counter compares this tick’s overlap with the previous tick’s. Staying inside does not count again; leaving and returning does. Multiple triggers would need the game’s own per-trigger membership tracking.

Read Scene::contacts() before end_tick(). Its participant pointers are borrowed, and the list expires when the next resolve or end-tick begins. The HUD copies just a count; it never keeps a contact pointer for the next frame.

Scene::set_bounds gives the world an extent, and end_tick retires a collision object whose shape has left it. It does that in two steps: it calls set_for_deletion(true) on the object, then removes every object whose for_deletion() answers true. set_for_deletion does nothing by default, so a collidable that keeps the default is never retired, by the sweep or by anything else that calls it. It goes on updating, drawing and colliding outside the world, and nothing reports it.

That default is right for fixed geometry, which must not be lost that way, and for the sample’s bodies, whose scene sets no bounds: Body::for_deletion() answers false and Body does not override set_for_deletion. Anything that can leave the world, such as a projectile, keeps the flag:

bool Projectile::for_deletion() const { return this->for_deletion_; }
void Projectile::set_for_deletion(bool for_deletion) { this->for_deletion_ = for_deletion; }

An object flagged during a tick produces no further contacts in it, and the pointer Scene::add returned for it stops being valid when that tick ends.

Put collision in your game adds a wall and a box the keys move to the starter project, step by step.

Terminal window
cd /d C:\dev\mygame\external\labrador
ctest --preset x64-debug -R "^CollisionSampleTests$"
start /wait "" out\build\x64-debug\samples\collision\CollisionSample.exe --smoke-test
echo %errorlevel%

From a clone, the first line is cd /d C:\dev\Labrador. ctest ends 100% tests passed, 0 tests failed out of 1. The sample is a Windows program, so the prompt does not wait for it on its own: start /wait makes it wait, and the last line prints 0 when the smoke run passed and another number when it failed. It shows no window and takes a few seconds.

The tests run the sample’s own arena without creating a window or device. They check separation, preserved tangential velocity, two-sided filtering, trigger entry and exit, and the route around the wall. The finite smoke runs the real application hidden, loads its content, draws the scripted route and checks that the wall was hit and the trigger entered before exiting.

This is discrete collision, not continuous collision detection or rigid-body physics. At the sample’s 60 Hz fixed step, its 240-unit speed moves a 32-unit player four units per tick through this particular layout. A speed limit alone does not prove arbitrary diagonal corner crossings safe. Validate your movement and geometry together; faster objects, narrow obstacles and moving-body response need their own tested policy.

Documentation for Labrador v0.3.0. Built from Labrador 0f4f503 of 2026-11-03.

All documentation versions