/physics-3d-collision

name: physics-3d-collision
description: Diagnoses 3D PhysX collision and trigger problems. Use when OnCollisionEnter or OnTriggerEnter doesn't fire, objects pass through each other, raycasts miss, or a MeshCollider misbehaves. Also answers 2D and DOTS physics best-effort if no dedicated skill is available.

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