Presentation in UE5 is allowed to lie. That is its job: animation moves bones, suspension tilts a body, camera shake displaces a view, interpolation smooths a position, and a simulated visual mesh drifts from the logical one. All of that is correct, and all of it happens after the values gameplay should have used.
The failure is reading gameplay truth out of that layer. It produces bugs with a characteristic signature: the error is proportional to how much the decoration is moving, it is invisible when the scene is still, and it cannot be found by debugging the system that appears wrong. A fraction of a degree of cosmetic tilt at the origin becomes a large error at the target, and every hour spent tuning the system that reports the error is wasted, because the error was injected upstream.
The fix is not a code change. It is deciding, per quantity, which representation is authoritative — and then never letting the other one reach a decision.
Settle the authority contract first
- List the quantities gameplay decides on — origin and direction of anything spawned or traced, positions used by AI, distances used by rules, velocities used by prediction.
- For each, name one authoritative source, and write it down. If two sources exist and neither is named, code will pick the convenient one, which is almost always the cosmetic one because it is what the visuals already use.
- Classify every transform in the actor as authoritative or cosmetic. Anything an
animation, IK solver, spring, smoothing component, physics visual body, or camera modifier
can touch is cosmetic — even when it is currently equal to the authoritative value. See
references/authority-map.md. - Give gameplay its own attachment points when it needs a location on a moving actor, rather than reusing the visual ones. Two sockets that agree today is not the same thing as one socket; the second one is free and it cannot drift.
- Let presentation read simulation, never the reverse. One-way dependency. A cosmetic value that feeds back into a gameplay value creates an error that grows with visual intensity.
Load only what applies:
references/authority-map.md— building the per-quantity authority table, and how to classify a transform you are unsure about.references/leak-patterns.md— the six ways cosmetic values reach gameplay decisions, each with its failure signature.references/decoupling-recipes.md— keeping the visual effect while moving the decision back onto the authoritative source.
Required answer format
When this skill fires, return:
- Authority table — quantity | authoritative source | cosmetic representations that exist | who may read which.
- Spawn and trace origins — for anything spawned or traced, the exact transform used and why it is authoritative.
- Leaks found — every place a gameplay decision currently reads a cosmetic value, with the file and the expected error signature.
- Decoupling applied — what changed, and confirmation the visual result is unchanged.
- Residual coupling — anything still reading cosmetic values, with the reason it is acceptable and the magnitude bound.
- Not verified — quantities you could not trace to a source.
Hard rules
- Never spawn, trace, or aim from a transform that animation, IK, physics visuals, or a camera modifier can touch. If the only available attachment point is animated, add a gameplay-only one.
- Never read a camera transform for a gameplay direction. Camera carries shake, lag, and offset by design; whatever it is showing is not what the actor is doing.
- Never let a smoothed, interpolated, or lagged proxy feed a decision. Smoothing is a display filter, and a filtered value is by definition not current.
- Cosmetic amplitude must not change gameplay results. This is the testable form of the whole skill: increase every decorative motion and confirm outcomes are unchanged.
- Gameplay code must not reference presentation types. Enforce it at the module boundary —
this is the same one-way dependency
ue5-project-contextrecords. - If a value must cross from cosmetic to authoritative, that crossing is a design decision with a written bound on its magnitude, not an implementation detail.
Verification
The amplitude test. Multiply every decorative motion in the scene — animation, sway, suspension travel, camera shake, interpolation offsets — by a large factor, and run a seeded scenario. Authoritative results must be bit-identical. Any difference is a leak, and the size of the difference tells you how much authority the decoration currently has. Scale the amplitude to zero as the second half of the test: results must again be identical.
This is one of the highest-value checks available in a project with visual motion, because it
finds leaks without knowing where they are. Run it in a seeded headless batch via
ue5-deterministic-sim-tests and it costs seconds.
Static-scene check. A bug that vanishes when nothing is moving is an authority leak until proven otherwise. Reproduce with all decoration frozen before debugging the system that reports the error.
Scope
This skill decides which value a gameplay decision reads. It does not cover how a query is
configured once the source is right (ue5-collision-and-trace-contract), what frame the read
happens on or what it inherits (ue5-spawn-frame-and-inheritance), or which class owns the
authoritative state (ue5-gameplay-state-ownership).
It does not cover network authority, which is a different meaning of the word — that is about which machine decides, not which representation is true. The distinction here applies identically in a single-machine project.