Ue5 Collision And Trace Contract

Collision and Trace Contract

Collision configuration in UE5 has a property that makes it unusually easy to get wrong: it is global, shared, and mostly invisible from the code that depends on it. A query in one file behaves the way it does because of a channel definition in project settings and a response set on a component in a different asset. None of the three references the others, and all three have to agree.

The consequences are the two complaints that dominate hit-detection debugging — "the trace returns nothing" and "the trace hits things it should not" — and both are usually correct code running against a configuration nobody wrote down.

The second failure is worse and quieter: a fast object passing through thin geometry, which is not a configuration problem at all but a query-type problem, and which reproduces only at speed.

Settle the hit contract first

1. Define what a hit means for each interaction before choosing an API. What is being asked, what may answer, and what the answer authorizes. A trace is a question; most trace bugs are a well-formed answer to the wrong question.
2. Write down the channel semantics. Two different kinds of channel exist and they answer different questions — an object channel says what a thing is, a trace channel says what a query is looking for. Confusing them is the single most common configuration error. See references/channel-semantics.md.
3. Never reuse a general-purpose channel for a gameplay decision. Visibility and camera channels exist, are always available, and mean something else. Borrowing one couples your hit logic to rendering and camera concerns permanently.
4. Treat the response matrix as shared state with an owner. Every channel added is a column every existing object must have an opinion about. Changing one response can alter behavior in systems that never mention it.
5. Choose the query type from speed and size, not from convenience. A line has zero thickness and objects move in discrete steps; both facts produce misses that look like configuration bugs. See references/query-selection.md.
6. Name one system as the hit authority for each interaction. Two systems independently querying will eventually disagree, and the disagreement surfaces as an intermittent gameplay inconsistency. See references/hit-authority.md.

Load only what applies:

• references/channel-semantics.md — object vs. trace channels, defining project channels, and the response matrix as a shared resource.
• references/query-selection.md — line, sweep, and overlap; tunnelling; complex vs. simple geometry; multi-hit handling.
• references/hit-authority.md — one decider per interaction, and reconciling systems that need to know about the same hit.

Required answer format

When this skill fires, return:

1. Interaction table — interaction | what is asked | who may answer | what the answer authorizes.
2. Channels — every channel used, its type (object or trace), its project meaning, and its default response.
3. Matrix changes — any response altered, and which existing systems that affects.
4. Query choice — line / sweep / overlap per interaction, with the speed and size that justified it, including the computed per-step displacement.
5. Hit authority — the single system deciding each interaction, and how others learn.
6. Not verified — channels or responses you could not confirm in project settings.

Hard rules

• Never make a gameplay decision on a general-purpose visibility or camera channel. Define a project channel with a written meaning.
• A channel without a documented meaning does not exist as far as this project is concerned. Record it in the project context file or do not add it.
• Never use a line trace for an object whose per-step displacement exceeds the thickness of what it must not pass through. Compute the displacement; do not estimate it by eye.
• Both sides must agree. A response is a pair — changing one component's response to a channel without checking the other side produces an interaction that works in one direction only.
• Adding a channel is a project-wide change requiring a stated default for existing objects. It is never a local edit, however local the motivating bug was.
• One authority per interaction. Other systems observe the result; they do not re-query and form their own opinion.

Verification

Displacement check. For every fast-moving object, compute speed × step_size and compare it to the thinnest geometry it must not pass through. If displacement exceeds thickness, a line trace will miss — not intermittently, but whenever the step lands wrong. This is arithmetic, not a test, and it is the cheapest bug prevention in this skill.

Matrix snapshot. Keep the collision settings under version control and diff them on every change. A response flipped by accident is invisible in a code review and produces a bug in a system that was not touched.

Query census. Periodically list every query in the codebase with its channel and type. Two queries asking the same question with different channels is a contract violation that has not caused a visible bug yet.

Seeded hit-count assertion. In a seeded headless run (ue5-deterministic-sim-tests), assert that hit counts and hit identities are stable across runs. Collision non-determinism usually means multi-hit results are being consumed in an unstable order.

Scope

This skill covers what counts as a hit and how it is asked for. It does not cover physical response after contact — impulses, restitution, constraints — nor damage or effect application, which begins after the hit is decided.

It does not cover networked hit validation, where the question becomes which machine's answer counts. That is a different problem built on top of this one.