# Ue5 Collision And Trace Contract > Define what counts as a hit in a UE5 project before writing queries — which object channels and trace channels exist and what each one means, who is allowed to decide a hit, how the collision response matrix is agreed on as shared global state, and whether a line, sweep, or overlap is the correct query for the speed and size involved. Use before implementing hit detection, when fast objects pass through thin geometry, when a query returns nothing or too much, when adding a channel, or when two systems disagree about whether something was hit. - Skill: `lichamnesia/ue5-collision-and-trace-contract` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add lichamnesia/ue5-collision-and-trace-contract` - Raw SKILL.md: https://api.skillmd.com/api/skills/lichamnesia/ue5-collision-and-trace-contract/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: lichamnesia (https://skillmd.com/u/lichamnesia) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/lichamnesia/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`](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`](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`](references/hit-authority.md). Load only what applies: - [`references/channel-semantics.md`](references/channel-semantics.md) — object vs. trace channels, defining project channels, and the response matrix as a shared resource. - [`references/query-selection.md`](references/query-selection.md) — line, sweep, and overlap; tunnelling; complex vs. simple geometry; multi-hit handling. - [`references/hit-authority.md`](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.