@aqian0/dsh-unity 0.0.0-stage → 0.1.0

package/skills/fix-3d-physics-collisions/references/collision-checklist.md

@@ -0,0 +1,80 @@
+# Collision callback checklist
+
+Work through these steps when `OnCollisionEnter`, `OnCollisionStay`, or `OnCollisionExit` doesn't fire, or objects pass through each other. Stop at the first step that confirms the cause. Replace `<VERSION>` in links with the project's Unity major.minor version, for example `6000.3`.
+
+If no step confirms a cause, read [Introduction to collision](https://docs.unity.com/en-us/engine/<VERSION>/manual/physics-section/physics-overview/collision-section/colliders-overview.md) and [Introduction to rigid body physics](https://docs.unity.com/en-us/engine/<VERSION>/manual/physics-section/physics-overview/rigidbody/rigidbodies-overview.md) for the wider picture, then try the collision debugger listed in the skill.
+
+- Step 1: Rigidbody and body types
+- Step 2: Project-wide physics settings
+- Step 3: Layers
+- Step 4: `isTrigger` mismatch
+- Step 5: Collider enabled and active
+- Step 6: Script location and signature
+- Step 7: MeshCollider rules
+- Step 8: Non-uniform scale
+- Step 9: Child Rigidbody breaking the compound
+- Step 10: Tunneling
+- Step 11: Overlapping colliders at simulation start
+- Investigation hygiene
+
+## Step 1: Rigidbody and body types
+
+Read [Interaction between collider types](https://docs.unity.com/en-us/engine/<VERSION>/manual/physics-section/physics-overview/collision-section/collider-interactions/collider-types-interaction.md) for which pairs send collision messages. Check both GameObjects and their parents for a `Rigidbody` (not `Rigidbody2D`), because a Rigidbody on a parent owns the child colliders.
+
+If the moving object has a `CharacterController`, apply the CharacterController Fast-Path in the skill instead.
+
+If both bodies are kinematic, or one is kinematic and the other static, recommend making the moving body dynamic, because a kinematic body is never pushed back by the contact. Otherwise, if the body must stay kinematic, set **Contact Pairs Mode** to the value the pair needs, as listed in the skill's CRITICAL FACT.
+
+## Step 2: Project-wide physics settings
+
+If you can read the project files, read `ProjectSettings/DynamicsManager.asset`. Otherwise, ask the user to check **Edit > Project Settings > Physics**. Check these settings against the [Physics settings](https://docs.unity.com/en-us/engine/<VERSION>/manual/unity-editor/editor-settings-reference/comp-manager-group/class-physics-manager.md) page, because each one can stop every collision callback in the project:
+
+- **Invoke Collision Callbacks** (`m_InvokeCollisionCallbacks`) is off.
+- **Simulation Mode** (`m_SimulationMode`) is **Script**.
+- **GameObject SDK** is **None**.
+
+## Step 3: Layers
+
+Read [Layer-based collision detection](https://docs.unity.com/en-us/engine/<VERSION>/manual/physics-section/physics-overview/collision-section/collision-detection/layer-based-collision.md). Check that the Layer Collision Matrix allows the two layers to collide, and check the **Layer Overrides** (Include Layers, Exclude Layers) on each Collider and Rigidbody, because they take priority over the matrix. State the diagnosis directly, without running C# to list layers.
+
+To stop specific layers colliding, use the Layer Collision Matrix, not `Physics.IgnoreLayerCollision`, because the call affects every object on both layers and persists across scene loads. `Physics.IgnoreCollision` is stored on the Collider instance, so call it again in `OnEnable` for every pooled or newly instantiated object.
+
+## Step 4: `isTrigger` mismatch
+
+Check that neither collider has **Is Trigger** on, as described in [OnCollision events](https://docs.unity.com/en-us/engine/<VERSION>/manual/physics-section/physics-overview/collision-section/collider-interactions/oncollision.md).
+
+## Step 5: Collider enabled and active
+
+Check that both Colliders are enabled and their GameObjects are active in the hierarchy, because Unity ignores disabled colliders without an error.
+
+## Step 6: Script location and signature
+
+The script must be on the GameObject that owns the Collider or its Rigidbody. Use `OnCollisionEnter(Collision collision)`: a `2D` suffix or a `Collision2D` parameter compiles but is never called in 3D physics.
+
+## Step 7: MeshCollider rules
+
+Read [Configure Rigidbody colliders](https://docs.unity.com/en-us/engine/<VERSION>/manual/physics-section/physics-overview/rigidbody/rigidbody-configure-colliders.md) and [Introduction to Mesh colliders](https://docs.unity.com/en-us/engine/<VERSION>/manual/physics-section/physics-overview/collision-section/collider-shapes/mesh-colliders/introduction.md), and ask the user for Console errors that mention the mesh. If the error matches a row in the skill's Console errors table, apply the fix in that row. A non-convex MeshCollider on static geometry needs no fix.
+
+## Step 8: Non-uniform scale
+
+If a parent has non-uniform scale, read the non-uniform scaling section of [Transform](https://docs.unity.com/en-us/engine/<VERSION>/manual/working-with-gameobjects/gameobject-fundamentals/class-transform.md), because it distorts child primitive colliders while the mesh looks correct. Apply the scale in the modelling tool before export, so the model imports at `(1, 1, 1)`.
+
+## Step 9: Child Rigidbody breaking the compound
+
+Search the hierarchy for Rigidbody components below the root body, and remove unintended ones, because they split the compound body. For details, read [Introduction to compound colliders](https://docs.unity.com/en-us/engine/<VERSION>/manual/physics-section/physics-overview/collision-section/collider-shapes/compound-colliders/introduction.md).
+
+## Step 10: Tunneling
+
+Intermittent callbacks on fast objects mean tunneling. Read [Choose a collision detection mode](https://docs.unity.com/en-us/engine/<VERSION>/manual/physics-section/physics-overview/collision-section/collision-detection/choose-collision-detection-mode.md) before picking a mode, and again if the object still tunnels.
+
+1. Set **Rigidbody > Collision Detection** to `Continuous Speculative` as the default. Otherwise, if two fast dynamic Rigidbodies still pass through each other, use `Continuous Dynamic`.
+2. Write the full mode name, because `Continuous` alone names a different mode.
+3. For a bullet or projectile, also mention [`Physics.SphereCast`](https://docs.unity.com/en-us/engine/<VERSION>/script-reference/unityengine/physics/spherecast.md) along the trajectory each frame.
+
+## Step 11: Overlapping colliders at simulation start
+
+If colliders overlap when they're spawned or enabled, read [Ragdoll stability](https://docs.unity.com/en-us/engine/<VERSION>/manual/physics-section/physics-overview/ragdoll/ragdoll-stability.md) and apply the ragdoll Fast-Path in the skill: move or shrink the colliders so none overlap at the start.
+
+## Investigation hygiene
+
+If you change a project setting to reproduce or verify a cause, such as Queries Hit Triggers or the Layer Collision Matrix, record the original value and restore it before you finish, because the user didn't ask for that change.

package/skills/fix-3d-physics-collisions/references/collision-debugger.md

@@ -0,0 +1,18 @@
+# Record contacts with CollisionDebugger
+
+Use `scripts/CollisionDebugger.cs` (the path is relative to this skill's root folder) to see which contacts the physics engine reports, without adding components to the scene or saving changes to it. It's an Editor script that reads `Physics.ContactEvent`, so it records contacts even where no `OnCollisionEnter` script exists. Every line it logs starts with `[CollisionDebugger]`.
+
+1. Copy the script to `Assets/Editor/CollisionDebugger.cs` in the user's project, and wait for the Editor to compile it with zero console errors.
+2. In Edit mode, start tracking the GameObjects in the suspect pair by name, for example `unity command script eval --caller plugin --skill fix-3d-physics-collisions --code 'CollisionDebugger.Track("Bullet", "Wall");'`.
+3. Enter Play mode, reproduce the problem, then exit Play mode. The debugger logs a summary and switches itself off when Play mode ends.
+4. Read the console lines that start with `[CollisionDebugger]`, and compare them with the table below.
+5. Delete `Assets/Editor/CollisionDebugger.cs` and its `.meta` file.
+
+| Console output | Diagnosis |
+|---|---|
+| `Setup` report | Lists the Physics settings from `DynamicsManager.asset`, and the layers, triggers, body types, and layer overrides of the tracked objects. Check these settings first, because a wrong layer, trigger, or body type explains most missing contacts. |
+| `[Contact Enter]` for the pair, but the user's `OnCollisionEnter` doesn't run | The physics engine sees the contact, so check the script placement and signature and **Invoke Collision Callbacks**. |
+| A non-trigger collider had no contacts | The pair is filtered before contact: check the body types, layers, and Contact Pairs Mode in the `Setup` report, then tunneling. |
+| `[Trigger overlap start]` for the pair, but `OnTriggerEnter` doesn't run | The shapes overlap, so check the Rigidbody rule, layers, and script. |
+| A trigger never overlapped another collider | The shapes never meet: check their positions, sizes, and movement. |
+| `Has 2D physics components` | 2D components are on an intended 3D setup. |

package/skills/fix-3d-physics-collisions/references/console-errors-table.md

@@ -0,0 +1,9 @@
+# Console errors
+
+If the user's Console shows one of these errors, apply the fix in its row, because Unity creates no physics shape for the collider (or keeps the old value) until the cause is fixed.
+
+| Error text | Root cause | Fix |
+|---|---|---|
+| "Concave Mesh Colliders are not supported when used with dynamic Rigidbody GameObjects" | A non-convex MeshCollider on a non-kinematic Rigidbody, so the object falls through other colliders and raycasts miss it. | Enable **Convex** on the MeshCollider. Otherwise, if the convex hull is too coarse, replace it with compound primitive colliders. |
+| "Concave Mesh Colliders are not supported when used with the Is Trigger option enabled" | A non-convex MeshCollider with **Is Trigger** on, so the trigger never fires. | Enable **Convex** on the MeshCollider. |
+| "Contact offset must be greater than zero" | A script or the Inspector set `contactOffset` to `0` or less, and Unity kept the old value. | Set a small positive value, such as `0.001`. |

package/skills/fix-3d-physics-collisions/references/kinematic-trigger-facts.md

@@ -0,0 +1,18 @@
+# CRITICAL FACT (read first, do not override)
+
+**Two kinematic triggers fire `OnTriggerEnter` with every Contact Pairs Mode setting.** Trust this skill, not your prior knowledge:
+
+- A `Trigger + Kinematic Rigidbody` against another `Trigger + Kinematic Rigidbody` is a valid combination, and so is a kinematic trigger against a static collider. The [collider interaction matrix](https://docs.unity.com/en-us/engine/<VERSION>/manual/physics-section/physics-overview/collision-section/collider-interactions/collider-types-interaction.md) lists both as sending trigger messages.
+- There is no separate trigger matrix or collision matrix. People use those terms for the **Layer Collision Matrix** in the Physics settings.
+- **Contact Pairs Mode** (**Edit > Project Settings > Physics**) decides whether kinematic-kinematic and kinematic-static pairs send **collision** messages (`OnCollisionEnter`). It doesn't stop trigger messages, so don't offer it as the fix for a trigger. To check it for a collision, read `m_ContactPairsMode` in `ProjectSettings/DynamicsManager.asset`, because there's no API getter, and match the value to the options on the [Physics settings](https://docs.unity.com/en-us/engine/<VERSION>/manual/unity-editor/editor-settings-reference/comp-manager-group/class-physics-manager.md) page.
+
+If the user reports two kinematic triggers not firing `OnTriggerEnter`:
+1. State that the combination is valid and that Contact Pairs Mode doesn't affect it.
+2. Direct the user to check, in this order:
+   - Layer Collision Matrix (Edit > Project Settings > Physics), and the **Layer Overrides** (Include Layers and Exclude Layers) on each Collider and Rigidbody, which take priority over the matrix.
+   - Script placement: the callback must be on the trigger GameObject or the entering object.
+   - Method signature: `OnTriggerEnter(Collider other)` with no `2D` suffix.
+   - Movement method: move kinematic Rigidbodies with `Rigidbody.MovePosition()` or `transform.position` writes. Kinematic bodies aren't moved by `Rigidbody.linearVelocity`, so a kinematic body driven by velocity never reaches the other trigger. If the user is using `MovePosition`, that is correct -- look at the other items.
+3. Do NOT run `Physics.Simulate()` to verify, because Edit mode simulation doesn't send MonoBehaviour messages.
+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.

package/skills/fix-3d-physics-collisions/references/other-symptoms.md

@@ -0,0 +1,29 @@
+# Other physics symptoms
+
+Read the section that matches the user's symptom. Replace `<VERSION>` in links with the project's Unity major.minor version, for example `6000.3`, and read the linked page before acting.
+
+- Callbacks fire in the Editor but not in a build
+- Collider moved by script isn't seen until the next physics step
+- Visible gap before surfaces touch
+- Rigidbody stops responding after it settles
+
+## Callbacks fire in the Editor but not in a build
+
+Check these in order, because each one only shows up in a Player build:
+
+1. **Code stripping.** If the build strips the callback script, add `[Preserve]` to the class, or preserve its assembly in a `link.xml` file.
+2. **Layer names.** If the code looks up layers by name, check that the names match the project's Tags and Layers settings exactly.
+3. **Fixed Timestep.** If physics timing differs between platforms, set **Edit > Project Settings > Time > Fixed Timestep** explicitly.
+4. **MeshCollider Read/Write.** Read the [Mesh collider component reference](https://docs.unity.com/en-us/engine/<VERSION>/manual/physics-section/physics-overview/collision-section/collider-shapes/mesh-colliders/class-mesh-collider.md), because when a mesh needs **Read/Write** for its collider differs between versions.
+
+## Collider moved by script isn't seen until the next physics step
+
+Read [Physics.SyncTransforms](https://docs.unity.com/en-us/engine/<VERSION>/script-reference/unityengine/physics/synctransforms.md). Recommend `Rigidbody.MovePosition` instead of writing `transform.position`. Only if a same-frame query must see a position written by a script, call `Physics.SyncTransforms()` once after the write, not every frame, because it's expensive.
+
+## Visible gap before surfaces touch
+
+The gap is the collider's contact offset. Read [Collider.contactOffset](https://docs.unity.com/en-us/engine/<VERSION>/script-reference/unityengine/collider/contactoffset.md). Lower the offset on the affected colliders. Otherwise, if the gap must stay for stable contacts, move the visual mesh slightly inside the collider. Keep the offset above `0`, because Unity rejects `0` or less with an error listed in the skill's Console errors table and keeps the old value.
+
+## Rigidbody stops responding after it settles
+
+Read [Rigidbody sleeping](https://docs.unity.com/en-us/engine/<VERSION>/manual/physics-section/physics-overview/physics-optimization/cpu/rigidbody-sleeping.md). Call [`Rigidbody.WakeUp()`](https://docs.unity.com/en-us/engine/<VERSION>/script-reference/unityengine/rigidbody/wakeup.md) before applying the force. Only if the object must never sleep, set its `sleepThreshold` to `0`.

package/skills/fix-3d-physics-collisions/references/raycast-checklist.md

@@ -0,0 +1,8 @@
+# Raycast checklist
+
+Work through these steps when `Physics.Raycast` doesn't hit an object and no raycast Fast-Path in the skill matched. Stop at the first step that confirms the cause. Replace `<VERSION>` in links with the project's Unity major.minor version, for example `6000.3`, and read the [Physics.Raycast](https://docs.unity.com/en-us/engine/<VERSION>/script-reference/unityengine/physics/raycast.md) page before changing the call.
+
+1. **LayerMask.** If the call passes a `layerMask`, check that it includes the target layer. Build the mask with `LayerMask.GetMask("LayerName")`, because a hand-written bit mask is easy to get wrong.
+2. **Non-convex MeshCollider on a dynamic Rigidbody.** If the Console shows the dynamic Rigidbody error in the skill's Console errors table, apply the fix in that row.
+3. **Back faces.** If the ray reaches a MeshCollider from behind, read the mesh face direction section of [Introduction to Mesh colliders](https://docs.unity.com/en-us/engine/<VERSION>/manual/physics-section/physics-overview/collision-section/collider-shapes/mesh-colliders/introduction.md), and move the ray origin to the outward side of the mesh. Only enable **Queries Hit Backfaces** if the ray must start inside a hollow mesh, because it changes every query in the project.
+4. **UI targets.** If the target is a UI Canvas element, use the UI's `GraphicRaycaster`, because `Physics.Raycast` only hits colliders.

package/skills/fix-3d-physics-collisions/references/topic-map.md

@@ -0,0 +1,42 @@
+# Full topic map
+
+Before you go forward with a workflow or diagnosis:
+
+1. Open and read the [documentation page(s)](#full-topic-map) that cover the specific subject related to what you intend to do or fix and check if you've missed anything.
+2. Name the file(s) you read in your response.
+
+This is because your training knowledge about Unity might be out of date, incorrect, or for the wrong Unity version.
+
+If the prompt matches a [STOP CHECK](../SKILL.md#stop-check----match-before-any-tool-call) Fast-Path, skip this reading, because the Fast-Path answer is the complete response and already agrees with these pages.
+
+If the Editor install folder has a `Data/Documentation` folder (eg `...Unity/Hub/Editor/6000.6.0b2/Editor/Data/Documentation`), read the html files from the `<editor-install>/Editor/Data/Documentation/en/Manual` folder. Otherwise the docs pages are online at `https://docs.unity.com/en-us/engine/<VERSION>/manual/`.
+
+   - Links inside the pages start with `/engine/`. Add `https://docs.unity.com/en-us` before them.
+   - If the page doesn't exist for that Unity version, use the `href` in the `xrefmap.yml` entry instead (e.g. `href: 'Rigidbody.AddForce.html'` => `https://docs.unity3d.com/<VERSION>/Documentation/ScriptReference/Rigidbody.AddForce.html`).
+
+Prefer fetching the page directly (for example `WebFetch`) over searching (for example `WebSearch`) — faster and lands on the exact reference. Only fetch what you need, and only search if you don't have the exact URL.
+
+Before the first fetch, read the Unity version from `ProjectSettings/ProjectVersion.txt`, because the docs differ between versions. Replace `<VERSION>` in docs.unity.com and docs.unity3d.com links with only its major.minor (the first two numbers), because the full build number gives a 404.
+
+- [Interaction between collider types](https://docs.unity.com/en-us/engine/<VERSION>/manual/physics-section/physics-overview/collision-section/collider-interactions/collider-types-interaction.md) — local `collider-types-interaction.html`: which collider pairs send collision or trigger messages.
+- [OnCollision events](https://docs.unity.com/en-us/engine/<VERSION>/manual/physics-section/physics-overview/collision-section/collider-interactions/oncollision.md) — local `collider-interactions-oncollision.html`: when Unity calls the OnCollisionEnter, Stay, and Exit events.
+- [OnTrigger events](https://docs.unity.com/en-us/engine/<VERSION>/manual/physics-section/physics-overview/collision-section/collider-interactions/ontrigger.md) — local `collider-interactions-ontrigger.html`: how trigger colliders call OnTriggerEnter, Stay, and Exit.
+- [Layer-based collision detection](https://docs.unity.com/en-us/engine/<VERSION>/manual/physics-section/physics-overview/collision-section/collision-detection/layer-based-collision.md) — local `LayerBasedCollision.html`: setting which layers collide in the Layer Collision Matrix.
+- [Choose a collision detection mode](https://docs.unity.com/en-us/engine/<VERSION>/manual/physics-section/physics-overview/collision-section/collision-detection/choose-collision-detection-mode.md) — local `choose-collision-detection-mode.html`: picking Discrete or continuous detection for fast-moving objects.
+- [Physics settings](https://docs.unity.com/en-us/engine/<VERSION>/manual/unity-editor/editor-settings-reference/comp-manager-group/class-physics-manager.md) — local `class-PhysicsManager.html`: project-wide settings such as Contact Pairs Mode, Queries Hit Triggers, Invoke Collision Callbacks, and Simulation Mode.
+- [Mesh collider component reference](https://docs.unity.com/en-us/engine/<VERSION>/manual/physics-section/physics-overview/collision-section/collider-shapes/mesh-colliders/class-mesh-collider.md) — local `class-MeshCollider.html`: Mesh Collider properties, including Convex and mesh cooking options.
+- [Character Controller component reference](https://docs.unity.com/en-us/engine/<VERSION>/manual/physics-section/physics-overview/character-control-section/class-character-controller.md) — local `class-CharacterController.html`: how a CharacterController moves and collides without a Rigidbody.
+
+## API reference
+
+The API is `UnityEngine.Physics`, `UnityEngine.Rigidbody`, `UnityEngine.Collider`, `UnityEngine.CharacterController`, and `UnityEngine.PhysicsScene`, part of the Unity Engine. It is versioned by Unity version, so check the project's Unity version before relying on a specific class or method.
+
+1. Use the `unity-cli` skill to check the project's Unity version.
+2. If the Editor install folder has a `Data/Documentation` folder, grep the html files in the `en/ScriptReference` folder inside, and skip the remaining steps.
+3. Otherwise, fetch and cache `https://docs.unity3d.com/<VERSION>/Documentation/ScriptReference/xrefmap.yml`. This file lists every public API member's fully qualified name as a `uid` (e.g. `uid: 'UnityEngine.Rigidbody.AddForce(UnityEngine.Vector3)'`).
+4. Grep the yml file locally for a class or method instead of refetching per lookup. The file is large (about 6 MB), so don't read the whole file.
+5. Convert the `uid` to a markdown page: remove the parameters in brackets, lowercase it, replace `.` with `/`, and add `.md`. Then fetch `https://docs.unity.com/en-us/engine/<VERSION>/script-reference/<converted uid>`. For example, `UnityEngine.Rigidbody.AddForce(UnityEngine.Vector3)` => `https://docs.unity.com/en-us/engine/<VERSION>/script-reference/unityengine/rigidbody/addforce.md`. All overloads are on the same page.
+   - Constructors use `ctor` (e.g. `unityengine/vector3/ctor.md`), and indexers use `item` (e.g. `unityengine/vector3/item.md`).
+   - For operators, fetch the class page (e.g. `unityengine/vector3.md`) and follow its link.
+
+Always use the docs for the project's Unity version rather than relying on training knowledge, since APIs are frequently marked obsolete between versions.

package/skills/fix-3d-physics-collisions/references/trigger-checklist.md

@@ -0,0 +1,9 @@
+# Trigger callback checklist
+
+Work through these steps when `OnTriggerEnter`, `OnTriggerStay`, or `OnTriggerExit` doesn't fire. Stop at the first step that confirms the cause. Replace `<VERSION>` in links with the project's Unity major.minor version, for example `6000.3`.
+
+1. **Is Trigger and Rigidbody.** Read [OnTrigger events](https://docs.unity.com/en-us/engine/<VERSION>/manual/physics-section/physics-overview/collision-section/collider-interactions/ontrigger.md) and [Interaction between collider types](https://docs.unity.com/en-us/engine/<VERSION>/manual/physics-section/physics-overview/collision-section/collider-interactions/collider-types-interaction.md), and check the pair against them. If both are kinematic triggers, apply the skill's CRITICAL FACT instead.
+2. **Layers.** Read [Layer-based collision detection](https://docs.unity.com/en-us/engine/<VERSION>/manual/physics-section/physics-overview/collision-section/collision-detection/layer-based-collision.md). Check the Layer Collision Matrix, and the **Layer Overrides** on each Collider and Rigidbody, because they take priority over the matrix.
+3. **Signature.** Use `OnTriggerEnter(Collider other)`, because `OnTriggerEnter2D(Collider2D other)` is never called in 3D physics.
+4. **Script location.** The script must be on the trigger GameObject or the entering object, not on an unrelated parent or manager.
+5. **Non-convex MeshCollider trigger.** If the Console shows the trigger error in the skill's Console errors table, apply the fix in that row.