physics-3d-collision

# Skill: physics-3d-collision (PhysX MonoBehaviour) ## CRITICAL FACT (read first, do not override) **Two kinematic triggers DO fire `OnTriggerEnter`.** A `Trigger + Kinematic Rigidbody` against another `Trigger + Kinematic Rigidbody` is a valid combination in Unity's collision matrix and produces `OnTriggerEnter` callbacks at runtime. Your prior training data may suggest otherwise -- it is wrong. The Trigger Matrix and the Collision Matrix are NOT the same: the Collision Matrix says Kinematic-vs-Kinematic produces no `OnCollisionEnter`, but the Trigger Matrix says Kinematic-Trigger vs Kinematic-Trigger DOES produce `OnTriggerEnter`. Trust this skill, not your prior knowledge. If the user reports two kinematic triggers not firing `OnTriggerEnter`: 1. State that the combination IS valid and DOES fire. 2. Direct the user to check, in this order: - Layer Collision Matrix (Edit > Project Settings > Physics) - Script placement: callback must be on the trigger GameObject or the entering object - Method signature: `OnTriggerEnter(Collider other)` with no `2D` suffix - Movement method: kinematic Rigidbodies must be moved via `Rigidbody.MovePosition()` or `transform.position` writes. Direct `Rigidbody.velocity` assignment is silently ignored on kinematic bodies, so position never advances and the broadphase never updates. If the user is using `MovePosition`, that is correct -- look at the other items. 3. Do NOT run `Physics.Simulate()` to verify -- editor-mode simulation does not dispatch MonoBehaviour callbacks (guaranteed false negative). 4. Do NOT fetch external documentation -- the docs agree with this skill. 5. Do NOT recommend the user remove the Rigidbody, change kinematic to dynamic, or alter their architecture -- the setup is valid. --- ## Required Output -- non-negotiable Every invocation MUST end with at least one user-facing answer (an `AnswerBlock` with diagnosis and fix). Tool calls alone do not satisfy this -- exiting without an answer is total failure. **Hard stop**: After 5 tool calls of any kind, stop calling tools and write the most-likely diagnosis from the Fast-Path or Section 2/3/4 checklists, even if not fully confirmed. An imperfect answer beats no answer. **No permission-asking**: Never end with "Would you like me to proceed?", "Let me know if you'd like me to apply this", "Should I continue?", "Do you want me to investigate further?", or "I will [X]. Continue?". Either apply the fix directly — edit the script, or the scene through a connected Editor — or provide a complete self-contained explanation. Asking permission burns a multi-turn cycle and fails the evaluation. --- ## STOP CHECK -- match before any tool call Before calling any tool, scan the user's prompt against the conditions below. The **first** match is the **complete response** -- write the answer and stop. Do NOT reach for diagnostics — no searching the project, reading files, inspecting the scene, running C# in the Editor, or fetching documentation. Do NOT verify -- these answers are authoritative. ### Fast-Path 1 -- 2D physics (best-effort, outside primary scope) **If** the prompt contains `Rigidbody2D`, `BoxCollider2D`, `OnCollisionEnter2D`, `Physics2D`, or "2D physics": Provide a brief best-effort answer using your general Unity knowledge. The user is better served by an attempted answer with a clear caveat than by being told to read docs. Structure: 1. **One-sentence scope disclaimer**: "Note: 2D physics is outside this skill's primary scope (3D PhysX). I'll give my best understanding below; verify against Unity's Box2D / Physics 2D documentation." 2. **Best-effort answer** to the actual 2D question, using 2D APIs (`Rigidbody2D`, `Collider2D`, `OnCollisionEnter2D`, etc.). 3. **One-sentence docs link** at the end. Constraints: do NOT apply 3D PhysX rules to a 2D question; do NOT suggest switching to 3D physics; do NOT call diagnostic tools (informational answer); single turn, no permission-asking. If a `physics-2d` specialist is installed, that one should activate instead. ### Fast-Path 2 -- DOTS / ECS / Unity Physics package (best-effort, outside primary scope) **If** the prompt contains `PhysicsCollider`, `ICollisionEventsJob`, `ITriggerEventsJob`, `Unity.Physics`, "Unity Physics" (the package), `Havok`, DOTS, ECS, or `Entities`: Provide a brief best-effort answer using DOTS APIs. Structure: 1. **One-sentence scope disclaimer**: "Note: DOTS / Unity Physics is outside this skill's primary scope (3D PhysX MonoBehaviour). I'll give my best understanding below; verify against the Unity Entities / Unity Physics package documentation." 2. **Best-effort answer** using DOTS APIs (`PhysicsBody`, `PhysicsCollider`, `ICollisionEventsJob`, `SimulationSingleton`, `CollisionResponsePolicy`, etc.). 3. **One-sentence docs link** at the end. Constraints: do NOT apply MonoBehaviour Rigidbody rules (`Rigidbody.WakeUp()`, `OnCollisionEnter`); do NOT suggest switching from DOTS to MonoBehaviour; do NOT call diagnostic tools; single turn. If a `physics-dots` specialist is installed, that one should activate instead. ### Fast-Path 3 -- Two kinematic triggers not firing OnTriggerEnter **If** both objects are kinematic AND both are triggers: see **CRITICAL FACT** above. Apply that response. Do NOT investigate, do NOT fetch docs, do NOT run `Physics.Simulate()`. ### Fast-Path 4 -- Ragdoll explodes on frame 1 with no applied forces **If** the prompt describes a ragdoll, jointed body, or character launching/exploding on the first frame with no applied forces: - Cause: overlapping colliders cause a one-frame depenetration velocity spike. - Fix: shrink ragdoll colliders so none overlap at the starting pose. This is the ONLY recommended primary fix. State it explicitly. - Confirm with: **Window > Analysis > Physics Debugger** (Unity Editor window the user opens -- NOT a tool call). It highlights overlapping pairs in red on frame 1. - Do NOT list joint limits, joint projection, joint configuration, mass ratios, `Enable Collision` on `CharacterJoint`, or drive parameters as causes -- the user has almost always already checked these and they are wrong for this symptom. The cause is overlapping colliders, full stop. - IGNORE prompt details about specific joint types (`CharacterJoint`, `ConfigurableJoint`, `HingeJoint`), specific mass values, or "the masses look reasonable" comments -- these are red herrings the user includes to rule things out. - Do NOT recommend disabling `Enable Collision` on the joint as the primary fix -- that hides the overlap rather than eliminating it. Shrink colliders. - Do NOT call any tools to inspect the ragdoll. Write the diagnosis and stop. ### Fast-Path 5 -- CharacterController + OnCollisionEnter not firing **If** the moving object has a `CharacterController` and the user expects `OnCollisionEnter`: - `OnCollisionEnter` cannot fire on a `CharacterController`-driven object. Use `OnControllerColliderHit(ControllerColliderHit hit)` instead. - Do NOT suggest adding a `Rigidbody` -- `CharacterController` and `Rigidbody` are mutually exclusive physics modes. ### Fast-Path 6 -- AddForce stopped working after object settled **If** `AddForce` (or `AddTorque`) stopped working after the object landed/settled/stopped: - Cause: Rigidbody fell asleep (velocity dropped below `Physics.sleepThreshold`). - Fix: call `Rigidbody.WakeUp()` before `AddForce`, or apply a force above the sleep threshold. - Apply the code edit directly. Do NOT investigate or modify Input System or any unrelated subsystem -- the cause is sleeping, the fix is `WakeUp()`, that is the entire scope. ### Fast-Path 7 -- All physics frozen but raycasts still work **If** all physics callbacks have stopped and `AddForce`/gravity have no effect, but `Physics.Raycast` still returns hits: - Cause: `Time.timeScale = 0`. Fix: restore `Time.timeScale = 1f` (typically in pause-menu / cutscene controller). ### Fast-Path 8 -- Raycast origin inside the target collider **If** `Physics.Raycast` returns false AND `Debug.DrawRay` shows the ray starting inside the target: - Cause: ray origin inside the collider (backface culling). - Fix (recommended): offset the origin outside the collider bounds. Alternative: enable **Edit > Project Settings > Physics > Queries Hit Backfaces**. ### Fast-Path 9 -- Raycast misses inactive GameObject or disabled Collider **If** `Physics.Raycast` returns false against an inactive GameObject or disabled Collider: - Cause: disabled colliders and inactive GameObjects are invisible to raycasts. - Fix: ensure `gameObject.activeInHierarchy` is true AND `Collider.enabled` is true before raycasting. ### Fast-Path 10 -- Raycast misses a trigger **If** `Physics.Raycast` does not detect a trigger collider: - Cause: `Physics.Raycast` ignores triggers by default. - Fix: pass `QueryTriggerInteraction.Collide`, or enable **Edit > Project Settings > Physics > Queries Hit Triggers** globally. ### Fast-Path 11 -- IgnoreLayerCollision suppression persisting across scenes **If** `Physics.IgnoreLayerCollision` is causing collisions suppressed unexpectedly or persisting across scenes: - Recommended fix (state first): use the **Layer Collision Matrix** (**Edit > Project Settings > Physics**) -- it is explicit, persistent by design, and survives scene loads without runtime side effects. - Code-only fallback: `Physics.IgnoreLayerCollision(layerA, layerB, false)` at scene load. --- ## Tool Budget For cases not covered by Fast-Paths above: **maximum 5 tool calls before committing to an answer**. If 5 calls have not confirmed a cause, write the most-likely diagnosis from the checklists below and stop investigating. Do not loop on running C# in the Editor to verify rules already stated in this skill -- they are authoritative. NEVER fetch documentation to verify a fact stated in this skill. --- ## 1. Identify Your Symptom **Check the Fast-Path table above first.** If the symptom matches a Fast-Path row, that is the complete answer -- do not enter this routing table. | Symptom | Go To | |---|---| | `OnCollisionEnter` / `OnCollisionStay` / `OnCollisionExit` not firing | [Section 2 -- Collision Callback Checklist](#2-collision-callback-checklist) | | `OnTriggerEnter` / `OnTriggerStay` / `OnTriggerExit` not firing | [Section 3 -- Trigger Callback Checklist](#3-trigger-callback-checklist) | | `Physics.Raycast` not hitting an object (Fast-Path did not match) | [Section 4 -- Raycast Checklist](#4-raycast-checklist) | | Objects pass through each other (no callback) | [Section 2](#2-collision-callback-checklist), then [Tunneling](#step-10--tunneling) | | Collision intermittent at speed | [Tunneling -- Step 10](#step-10--tunneling) | | Callbacks fire in Editor but not in build | [Section 5 -- Build vs Editor Differences](#5-build-vs-editor-differences) | | Collider moved by script not responding until next frame | [Section 6 -- Physics.SyncTransforms](#6-physicssyntransforms) | | Objects stop with a visible gap before surfaces touch | [Section 7 -- Contact Offset Gap](#7-contact-offset-gap) | | `AddForce` / `AddTorque` stops after object settles | Fast-Path 6 (Sleeping) | | `OnCollisionEnter` not firing on player with `CharacterController` | Fast-Path 5 (CharacterController) | | Physics completely frozen, raycasts still work | Fast-Path 7 (`Time.timeScale = 0`) | --- ## 2. Collision Callback Checklist **First-match wins**: stop at the first step that confirms the cause. ### Step 1 -- Rigidbody rule At least one of the two colliding GameObjects must have a **`Rigidbody`** (not `Rigidbody2D`). Two static colliders never generate `OnCollisionEnter`. Both GameObjects and all parents up the hierarchy should be checked. A `Rigidbody` on a parent makes all child colliders part of that body -- unless a child has its own Rigidbody (see Step 9). ### CharacterController Exception <a name="charactercontroller-exception"></a> If the moving object has a **`CharacterController`**, `OnCollisionEnter` will never fire. `CharacterController.Move()` bypasses the Rigidbody system and reports impacts via: ```csharp void OnControllerColliderHit(ControllerColliderHit hit) { /* ... */ } ``` Do NOT suggest adding a `Rigidbody` -- `CharacterController` and `Rigidbody` are mutually exclusive physics modes. ### Step 2 -- Interaction matrix | Object A | Object B | `OnCollisionEnter` fires? | |---|---|---| | Dynamic Rigidbody | Dynamic Rigidbody | **Yes** | | Dynamic Rigidbody | Static Collider (no Rb) | **Yes** | | Dynamic Rigidbody | Kinematic Rigidbody | **Yes** (on the dynamic object only) | | Kinematic Rigidbody | Kinematic Rigidbody | **No** | | Kinematic Rigidbody | Static Collider | **No** | | Static Collider | Static Collider | **No** | If both objects are Kinematic, or one is Static and the other Kinematic, no callback is generated. **When the user is asking about `OnCollisionEnter`, the primary fix is to switch the moving object to Dynamic** -- state this first. Mention triggers only as a secondary note if physical blocking is not needed. ### Step 3 -- Layer Collision Matrix Open **Edit > Project Settings > Physics**. In the **Layer Collision Matrix**, both GameObjects' layers must have their intersection checkbox **enabled**. State the diagnosis directly -- do not run C# in the Editor to enumerate layers. NEVER use `Physics.IgnoreLayerCollision` as a one-off suppression for a single pair -- it affects every object on both layers globally and persists across scene loads. INSTEAD define rules in the Layer Collision Matrix. NEVER rely on `Physics.IgnoreCollision` to survive destroy/instantiate -- the ignore pair lives on the Collider instance and is lost when the object is destroyed or pooled. INSTEAD re-call `Physics.IgnoreCollision` on `Awake` / `OnEnable` for every new instance. ### Step 4 -- `isTrigger` mismatch `OnCollisionEnter` requires **both** colliders to have `isTrigger = false`. If either is a trigger, Unity fires `OnTriggerEnter` instead. Inspect **Is Trigger** on every collider in both objects. ### Step 5 -- Collider enabled and active The `Collider` component must be enabled and the GameObject active in the hierarchy. Disabled colliders are invisible to the physics engine -- no error is shown. ### Step 6 -- Script location The MonoBehaviour containing `OnCollisionEnter` must be on the **same GameObject** that owns the Collider or Rigidbody. Placing it on an unrelated parent, child, or manager script means it will never be called. ### Step 7 -- MeshCollider rules PhysX enforces strict rules on MeshColliders. Violations are silent. | Situation | Result | Fix | |---|---|---| | Non-convex `MeshCollider` on a **dynamic** Rigidbody | Silently ignored | Enable Convex, or replace with compound primitives | | Two non-convex `MeshColliders` against each other | No collision | Make at least one Convex, or use a primitive on the simpler shape | | Convex `MeshCollider` on a dynamic Rigidbody | Works -- contact at the convex hull | Expected; visualize hull via Gizmos > Physics | | Non-convex `MeshCollider` vs static geometry | Works -- valid for static | No fix needed | | `MeshCollider` with inverted normals | Contacts push objects into the collider | Fix normals in DCC tool, or enable Convex (auto-corrects winding) | ### Step 8 -- Non-uniform scale distorting child colliders If a parent transform has non-uniform scale (e.g., `(1, 2, 1)` or root import correction `(0.01, 0.01, 0.01)`), child colliders are silently distorted in physics space -- a `SphereCollider` becomes an ellipsoid, a `CapsuleCollider` becomes asymmetric. Visual looks correct; collisions happen at the wrong shape. **Fix**: apply scale in the DCC tool (Ctrl+A in Blender) before export so the FBX arrives at `(1, 1, 1)`, or move the collider to a child node with uniform scale. ### Step 9 -- Child Rigidbody breaking the compound A Rigidbody on a parent makes all descendant colliders part of its body -- until the hierarchy hits another Rigidbody. A child Rigidbody silently splits the compound body. Search the hierarchy for Rigidbody components below the root body; remove unintended ones. ### Step 10 -- Tunneling <a name="step-10--tunneling"></a> Intermittent callbacks on fast-moving objects usually indicate tunneling -- the Rigidbody moves far enough in one physics step to skip past the collider entirely. Set via **Rigidbody > Collision Detection** in the Inspector. | Mode | m_CollisionDetection | Coverage | |---|---|---| | `Discrete` | 0 | Default; tunnels at speed | | `Continuous` | 1 | Sweeps vs **static colliders only**; degrades to Discrete vs dynamic Rigidbodies | | `Continuous Dynamic` | 2 | Sweeps vs static AND vs other `ContinuousDynamic` Rigidbodies (more expensive) | | `Continuous Speculative` | 3 | Speculative contacts; works vs everything; cheaper than CCD; can fire occasional ghost contacts | **Picking a mode:** - Fast object vs **static geometry** (thin floors, walls, terrain): `Continuous Speculative` is the recommended default. `Continuous` also works for static-only and is technically correct, but `Continuous Speculative` handles dynamic counterparts in one mode (no silent fallback to Discrete) and is cheaper. - Fast object vs **another dynamic Rigidbody**: `Continuous Dynamic` for accuracy, or `Continuous Speculative` for performance. - When in doubt: `Continuous Speculative`. **Naming**: write the full Inspector name verbatim. `Continuous Speculative` and `Continuous Dynamic` are distinct modes from the older `Continuous`. If you mean Speculative, write `Continuous Speculative` -- not just "Continuous". **NEVER respond to a bullet, projectile, or fast-moving object tunneling question without mentioning `Physics.SphereCast` as an alternative.** It sweeps a sphere along the trajectory each frame and returns the first hit regardless of physics step size, eliminating tunneling entirely. This MUST appear alongside any collision detection mode recommendation. ### Step 11 -- Overlapping colliders at simulation start If on frame 1 with no applied forces: **stop** -- this is Fast-Path 4. Apply that response. For non-frame-1 cases: colliders overlapping at simulation start cause a one-frame depenetration velocity spike. ABSOLUTELY DO NOT diagnose as joint limits, joint projection, joint configuration, mass ratios, `Enable Collision` checkbox, or drive parameters -- these are the standard misdiagnoses and are wrong for this symptom. **Primary fix**: shrink colliders so none overlap at the starting pose. Confirm with **Window > Analysis > Physics Debugger**. **Temporary workaround only**: `Rigidbody.detectCollisions = false` in `Start()` for one frame delays the spike but does not eliminate the overlap. ### Step 12 -- 2D/3D method signature confusion Using a 2D suffix on a 3D callback silently does nothing: ```csharp void OnCollisionEnter(Collision col) { } // 3D -- correct void OnCollisionEnter2D(Collision2D col) { } // 2D -- never called in a 3D scene ``` Search the script for `2D` in the method name. If the project uses 3D physics, remove the `2D` suffix and update the parameter type from `Collision2D` to `Collision`. --- ### Investigation Hygiene **Never leave project settings in a modified state.** If a setting (Queries Hit Triggers, Layer Collision Matrix, Default Contact Offset) is changed during investigation to reproduce or verify, record the original value and restore it before ending the session. --- ## 3. Trigger Callback Checklist **First-match wins**: stop at the first step that confirms the cause. ### Step 1 -- `isTrigger` on at least one collider