Contact
Generated from engine/collision/contacts.h at aceb130. 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/collision/contacts.h" · namespace labrador
struct Contact
Section titled “struct Contact”struct ContactOne overlapping pair, and the smallest translation that separates it.
The frame's contacts are a list the caller can look at before anything responds to them - which is the whole reason this is a value and not a callback fired from inside the sweep. A test can assert on the list, and a scene can hand it to the game after resolution instead of during it. Participant pointers are borrowed. The caller keeps each object alive through dispatch and any inspection; Scene expires the list at end_tick before destroying participants. This is the pre-response membership and measurement, not a record of which pairs dispatch actually delivered.
normal
Section titled “normal”Unit, pointing from a towards b.
penetration
Section titled “penetration”float penetration = 0.0f;Overlap along normal, always greater than zero.
find_contacts
Section titled “find_contacts” std::vector<Contact>& contacts,Fills contacts with every overlapping pair among objects, each pair once. Null entries are ignored. Pairs follow ascending input indices (i, j), i < j, with the earlier object as a. Exhaustive and broad-phase enumeration agree.
contacts is cleared first and reused, so a caller that keeps one vector across frames allocates nothing after the first busy frame - which is the point of taking it by reference rather than returning it.
Three filters, cheapest first: layer/mask, then the shapes' bounding boxes, then narrow_phase. Objects already flagged for deletion take part in nothing.
After clearing contacts, validates every non-null, non-retired object with CollisionObject::validate_finite_shape, before any pair is emitted. Invalid input throws std::invalid_argument even for a lone/masked object; contacts stays empty and objects are neither changed nor retired.
With no broad phase, the pair enumeration is all-pairs, O(n^2); broad_phase.h gives the measured cost. Pass one and it enumerates only the pairs whose bounding boxes overlap, in the same order.
The parameter is a pointer with a default rather than a required argument because the exhaustive sweep is the specification: it is what the grid is tested against (tests/collision/broad_phase_tests.cpp), and a caller with a handful of objects has no reason to build a grid.
broad_phase is borrowed, and it holds the buffers that make the steady state allocation-free, so a caller that wants that keeps one across frames - exactly as it does with contacts.
dispatch_contacts
Section titled “dispatch_contacts”Walks the supplied list in order. Each surviving pair is measured once immediately before dispatch, then calls a and b once each with that same measurement and opposite normals. The first response may mutate or retire either participant without suppressing the already-started second half or changing its measurement. A callback exception stops dispatch.
Two things a response does are accounted for here, because they are properties of dispatching a list rather than of any one response:
- A response can retire an object, and a retired object's remaining contacts are dropped. A projectile that hits a wall does not go on to hit the player behind it. The rule applies to both sides of every pair when it is reached, not between its two callback halves. - A response can move an object, so every pair is measured again immediately before it is dispatched, and a pair an earlier response has already separated is dropped. The depths in the list describe the frame before anything responded to it, which is what a caller inspecting the list wants and not what a caller acting on it does.
Each live pair is validated immediately before remeasurement. Invalid geometry throws std::invalid_argument; earlier callback effects remain. New overlaps created by responses are not added to this snapshot. The stored contacts are not rewritten when a pair is remeasured or skipped. Layer/mask filtering belongs to find_contacts; it is not reapplied here. The caller supplies non-null participants in each Contact and keeps them alive until dispatch returns. A copied participant pointer borrows its object's lifetime; normal references expire with the callback. Do not destroy participants or reenter dispatch here.
Related types
Section titled “Related types”Named in the public declarations above: BroadPhase, CollisionObject, Vector2F.
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.
tests/collision/broad_phase_tests.cpp,contacts_tests.cpp,finite_shape_tests.cpp,frame_allocation_tests.cpp
Explained in
Section titled “Explained in”No guide or concept page links to this header yet.
Development documentation (unreleased). Built from Labrador aceb130 of 2026-11-20.