@aqian0/dsh-unity 0.0.0-stage → 0.1.0

package/skills/create-tile-palette-or-rule-tiles/scripts/CreatePaletteTemplate.cs

@@ -0,0 +1,148 @@
+// Code template for creating Tile Palettes using GridPaletteUtility.CreateNewPalette
+// Reference: Packages/com.unity.2d.tilemap/Editor/GridPaletteUtility.cs
+
+using UnityEngine;
+using UnityEditor.Tilemaps;
+
+namespace TilePaletteCreation
+{
+    public static class CreatePaletteTemplate
+    {
+        // CreateNewPalette signature:
+        // public static GameObject CreateNewPalette(
+        //     string folderPath,
+        //     string name,
+        //     GridLayout.CellLayout layout,
+        //     GridPalette.CellSizing cellSizing,
+        //     Vector3 cellSize,
+        //     GridLayout.CellSwizzle swizzle,
+        //     TransparencySortMode sortMode,
+        //     Vector3 sortAxis)
+
+        /// <summary>
+        /// Creates a rectangular tile palette with automatic cell sizing.
+        /// </summary>
+        public static GameObject CreateRectangularPalette(string folderPath, string paletteName)
+        {
+            return GridPaletteUtility.CreateNewPalette(
+                folderPath,
+                paletteName,
+                GridLayout.CellLayout.Rectangle,
+                GridPalette.CellSizing.Automatic,
+                new Vector3(1f, 1f, 0f),
+                GridLayout.CellSwizzle.XYZ,
+                TransparencySortMode.Default,
+                new Vector3(0f, 0f, 1f));
+        }
+
+        /// <summary>
+        /// Creates a hexagonal tile palette (point-top orientation).
+        /// Uses the standard hexagonal cell size.
+        /// </summary>
+        public static GameObject CreateHexagonalPalette(string folderPath, string paletteName)
+        {
+            return GridPaletteUtility.CreateNewPalette(
+                folderPath,
+                paletteName,
+                GridLayout.CellLayout.Hexagon,
+                GridPalette.CellSizing.Manual,
+                new Vector3(0.8659766f, 1f, 1f),
+                GridLayout.CellSwizzle.XYZ,
+                TransparencySortMode.Default,
+                new Vector3(0f, 0f, 1f));
+        }
+
+        /// <summary>
+        /// Creates an isometric tile palette with custom sort axis.
+        /// </summary>
+        public static GameObject CreateIsometricPalette(string folderPath, string paletteName)
+        {
+            return GridPaletteUtility.CreateNewPalette(
+                folderPath,
+                paletteName,
+                GridLayout.CellLayout.Isometric,
+                GridPalette.CellSizing.Manual,
+                new Vector3(1f, 0.5f, 1f),
+                GridLayout.CellSwizzle.XYZ,
+                TransparencySortMode.CustomAxis,
+                new Vector3(0f, 0f, 1f));
+        }
+
+        /// <summary>
+        /// Creates an isometric Z as Y tile palette.
+        /// Used when Z position should affect Y sorting.
+        /// </summary>
+        public static GameObject CreateIsometricZAsYPalette(string folderPath, string paletteName)
+        {
+            return GridPaletteUtility.CreateNewPalette(
+                folderPath,
+                paletteName,
+                GridLayout.CellLayout.IsometricZAsY,
+                GridPalette.CellSizing.Manual,
+                new Vector3(1f, 0.5f, 1f),
+                GridLayout.CellSwizzle.XYZ,
+                TransparencySortMode.CustomAxis,
+                new Vector3(0f, 0f, 1f));
+        }
+
+        /// <summary>
+        /// Creates a tile palette with fully customizable parameters.
+        /// </summary>
+        /// <param name="folderPath">Project-relative folder path (e.g., "Assets/Palettes")</param>
+        /// <param name="paletteName">Name of the palette asset</param>
+        /// <param name="layout">Grid cell layout type</param>
+        /// <param name="cellSizing">Automatic or Manual cell sizing</param>
+        /// <param name="cellSize">Size of each cell in the grid</param>
+        /// <param name="swizzle">Cell coordinate swizzle</param>
+        /// <param name="sortMode">Transparency sort mode for rendering</param>
+        /// <param name="sortAxis">Custom sort axis (used when sortMode is CustomAxis)</param>
+        /// <returns>The created palette GameObject, or null if creation failed</returns>
+        public static GameObject CreateCustomPalette(
+            string folderPath,
+            string paletteName,
+            GridLayout.CellLayout layout,
+            GridPalette.CellSizing cellSizing,
+            Vector3 cellSize,
+            GridLayout.CellSwizzle swizzle,
+            TransparencySortMode sortMode,
+            Vector3 sortAxis)
+        {
+            return GridPaletteUtility.CreateNewPalette(
+                folderPath,
+                paletteName,
+                layout,
+                cellSizing,
+                cellSize,
+                swizzle,
+                sortMode,
+                sortAxis);
+        }
+    }
+}
+
+// Parameter Reference:
+//
+// GridLayout.CellLayout:
+//   - Rectangle: Standard rectangular grid
+//   - Hexagon: Hexagonal grid
+//   - Isometric: Isometric grid
+//   - IsometricZAsY: Isometric grid where Z position affects Y sorting
+//
+// GridPalette.CellSizing:
+//   - Automatic: Cell size determined automatically from sprites
+//   - Manual: Cell size specified explicitly
+//
+// GridLayout.CellSwizzle:
+//   - XYZ: Standard coordinate system
+//   - XZY, YXZ, YZX, ZXY, ZYX: Various coordinate swizzles
+//
+// TransparencySortMode:
+//   - Default: Use default sorting
+//   - Perspective: Sort by perspective
+//   - Orthographic: Sort orthographically
+//   - CustomAxis: Sort along a custom axis
+//
+// Recommended Cell Sizes:
+//   - Rectangular: (1, 1, 0) with Automatic sizing
+//   - Hexagonal: (0.8659766, 1, 1)
+//   - Isometric: (1, 0.5, 1)

package/skills/create-tile-palette-or-rule-tiles/scripts/ManualWorkflowExample.cs

@@ -0,0 +1,63 @@
+using System.Collections.Generic;
+using System.Linq;
+using UnityEngine;
+
+/// <summary>
+/// Example: Manual two-step workflow for more control over the analysis step.
+/// </summary>
+public static class ManualWorkflowExample
+{
+    public static void RunManualWorkflow(List<Sprite> sprites, RuleTile myRuleTile,
+        bool filterToKnownPatterns = true)
+    {
+        // Step 1: Run sprite-segment-3x3grid on each sprite, filter, and deduplicate
+        var seenPatterns = new HashSet<string>();
+        var uniquePatterns = new List<(string pattern, Sprite sprite)>();
+
+        foreach (var sprite in sprites)
+        {
+            // Apply sprite-segment-3x3grid analysis
+            string pattern = SpriteSegment3x3Grid.AnalyzeSpriteGrid(
+                sprite,
+                matchThreshold: 0.75f,
+                colorTolerance: 0.04f
+            );
+
+            // Discard patterns not in the known set
+            if (filterToKnownPatterns &&
+                !TilemapRuleTileCreateFromSegment.IsKnownPattern(pattern))
+            {
+                Debug.Log($"Sprite '{sprite.name}' skipped (unknown pattern: {pattern})");
+                continue;
+            }
+
+            // Skip duplicates
+            if (seenPatterns.Contains(pattern))
+            {
+                Debug.Log($"Sprite '{sprite.name}' skipped (duplicate pattern: {pattern})");
+                continue;
+            }
+
+            seenPatterns.Add(pattern);
+            Debug.Log($"Sprite '{sprite.name}' pattern: {pattern}");
+            uniquePatterns.Add((pattern, sprite));
+        }
+
+        // Step 2: Create TilingRules from unique patterns
+        var rules = new List<(RuleTile.TilingRule rule, int specificity)>();
+        foreach (var (pattern, sprite) in uniquePatterns)
+        {
+            var result = TilemapRuleTileCreateFromSegment.CreateTilingRuleFromPattern(pattern, sprite);
+            rules.Add(result);
+        }
+
+        // Sort by specificity
+        rules.Sort((a, b) => b.specificity.CompareTo(a.specificity));
+
+        // Apply to RuleTile
+        var sortedRules = rules.Select(r => r.rule).ToList();
+        TilemapRuleTileCreateFromSegment.ApplyRulesToTile(myRuleTile, sortedRules);
+
+        Debug.Log($"Created {sortedRules.Count} unique rules from {sprites.Count} sprites");
+    }
+}

package/skills/create-tile-palette-or-rule-tiles/scripts/RuleTileGenerator.cs

@@ -0,0 +1,61 @@
+using System.Linq;
+using UnityEditor;
+using UnityEngine;
+
+public class RuleTileGenerator : EditorWindow
+{
+    float m_MatchThreshold = 0.75f;
+
+    [MenuItem("Tools/Generate RuleTile from Sprites")]
+    static void ShowWindow()
+    {
+        GetWindow<RuleTileGenerator>("RuleTile Generator");
+    }
+
+    void OnGUI()
+    {
+        GUILayout.Label("Match Threshold", EditorStyles.boldLabel);
+        m_MatchThreshold = EditorGUILayout.Slider(m_MatchThreshold, 0.5f, 0.9f);
+
+        if (GUILayout.Button("Generate from Selected Texture"))
+            GenerateRuleTile();
+    }
+
+    void GenerateRuleTile()
+    {
+        var texture = Selection.activeObject as Texture2D;
+        if (texture == null)
+        {
+            Debug.LogError("Please select a Texture2D asset");
+            return;
+        }
+
+        // Get sprites from texture
+        string path = AssetDatabase.GetAssetPath(texture);
+        var sprites = AssetDatabase.LoadAllAssetsAtPath(path).OfType<Sprite>().ToList();
+
+        if (sprites.Count == 0)
+        {
+            Debug.LogError("No sprites found in texture. Ensure texture is sliced.");
+            return;
+        }
+
+        // Complete workflow: sprite-segment-3x3grid -> TilingRules
+        var rules = TilemapRuleTileCreateFromSegment.CreateRuleTileFromSprites(
+            sprites,
+            matchThreshold: m_MatchThreshold
+        );
+
+        // Create and save RuleTile asset
+        var ruleTile = ScriptableObject.CreateInstance<RuleTile>();
+        TilemapRuleTileCreateFromSegment.ApplyRulesToTile(ruleTile, rules);
+
+        string savePath = path.Replace(".png", "_RuleTile.asset")
+                              .Replace(".jpg", "_RuleTile.asset");
+        AssetDatabase.CreateAsset(ruleTile, savePath);
+        AssetDatabase.SaveAssets();
+
+        Debug.Log($"Created RuleTile with {rules.Count} rules at {savePath}");
+        Selection.activeObject = ruleTile;
+    }
+}

package/skills/create-tile-palette-or-rule-tiles/scripts/TilemapRuleTileCreateFromSegment.cs

@@ -0,0 +1,225 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using UnityEngine;
+
+/// <summary>
+/// Creates RuleTile TilingRules by first applying sprite-segment-3x3grid analysis,
+/// then converting the text patterns to neighbor configurations.
+/// </summary>
+public static class TilemapRuleTileCreateFromSegment
+{
+    /// <summary>
+    /// Grid position to Unity neighbor Vector3Int mapping.
+    /// Index 4 (center) is not included as it's not a neighbor.
+    /// </summary>
+    static readonly Dictionary<int, Vector3Int> k_GridIndexToPosition = new()
+    {
+        { 0, new Vector3Int(-1, 1, 0) },   // Top-Left
+        { 1, new Vector3Int(0, 1, 0) },    // Top
+        { 2, new Vector3Int(1, 1, 0) },    // Top-Right
+        { 3, new Vector3Int(-1, 0, 0) },   // Left
+        // 4 is center, skipped
+        { 5, new Vector3Int(1, 0, 0) },    // Right
+        { 6, new Vector3Int(-1, -1, 0) },  // Bottom-Left
+        { 7, new Vector3Int(0, -1, 0) },   // Bottom
+        { 8, new Vector3Int(1, -1, 0) },   // Bottom-Right
+    };
+
+    /// <summary>
+    /// The 47 known tile patterns from the Common Tile Patterns table.
+    /// Patterns not in this set are discarded by default.
+    /// </summary>
+    static readonly HashSet<string> k_KnownPatterns = new()
+    {
+        ". . . / . * . / . . .",  // Fully surrounded
+        "X . . / . * . / . . .",  // Top left corner missing
+        ". . X / . * . / . . .",  // Top right corner missing
+        ". . . / . * . / X . .",  // Bottom left corner missing
+        ". . . / . * . / . . X",  // Bottom right corner missing
+        "X . X / . * . / . . .",  // Top corners missing
+        ". . . / . * . / X . X",  // Bottom corners missing
+        "X . . / . * . / X . .",  // Left corners missing
+        ". . X / . * . / . . X",  // Right corners missing
+        "X . . / . * . / . . X",  // Top Left and Bottom Right diagonal
+        ". . X / . * . / X . .",  // Top Right and Bottom Left diagonal
+        "X . X / . * . / X . .",  // Top Left, Top Right, Bottom Left
+        "X . X / . * . / . . X",  // Top Left, Top Right, Bottom Right
+        "X . . / . * . / X . X",  // Top Left, Bottom Left, Bottom Right
+        ". . X / . * . / X . X",  // Top Right, Bottom Left, Bottom Right
+        "X . X / . * . / X . X",  // Cross Section
+        "X X X / . * . / . . .",  // Flat edge (Bottom)
+        ". . . / . * . / X X X",  // Flat edge (Top)
+        ". . X / . * X / . . X",  // Flat edge (Left)
+        "X . . / X * . / X . .",  // Flat edge (Right)
+        "X X X / . * . / . . X",  // L-Shape, Point Right
+        ". . X / . * X / X . X",  // L-Shape, Point Bottom
+        "X . . / . * . / X X X",  // L-Shape, Point Left
+        "X . X / X * . / X . .",  // L-Shape, Point Top
+        "X X X / . * . / X . .",  // L-Shape Inverse, Point Left
+        "X . . / X * . / X . X",  // L-Shape Inverse, Point Bottom
+        ". . X / . * . / X X X",  // L-Shape Inverse, Point Right
+        "X . X / . * X / . . X",  // L-Shape Inverse, Point Top
+        "X X X / . * . / X . X",  // T-Shape, face down
+        "X . X / . * . / X X X",  // T-Shape, face top
+        "X . X / . * X / X . X",  // T-Shape, face left
+        "X . X / X * . / X . X",  // T-Shape, face right
+        "X X X / . * . / X X X",  // Horizontal bridge
+        "X . X / X * X / X . X",  // Vertical bridge
+        "X X X / X * . / X . .",  // Corner piece, Bottom Right
+        "X X X / . * X / . . X",  // Corner piece, Bottom Left
+        ". . X / . * X / X X X",  // Corner piece, Top Left
+        "X . . / X * . / X X X",  // Corner piece, Top Right
+        "X X X / X * . / X . X",  // Edge end, Bottom Right
+        "X X X / . * X / X . X",  // Edge end, Bottom Left
+        "X . X / . * X / X X X",  // Edge end, Top Left
+        "X . X / X * . / X X X",  // Edge end, Top Right
+        "X X X / . * X / X X X",  // Single isolated tile, Left
+        "X X X / X * . / X X X",  // Single isolated tile, Right
+        "X . X / X * X / X X X",  // Single isolated tile, Top
+        "X X X / X * X / X . X",  // Single isolated tile, Bottom
+        "X X X / X * X / X X X",  // Center
+    };
+
+    /// <summary>
+    /// Creates a RuleTile from sprites by first running sprite-segment-3x3grid analysis.
+    /// This is the main entry point that implements the complete workflow.
+    /// Duplicate patterns are automatically removed (first sprite wins).
+    /// Patterns not in the known 47 Common Tile Patterns are discarded by default.
+    /// </summary>
+    /// <param name="sprites">Sprites to analyze and create rules for</param>
+    /// <param name="matchThreshold">Match threshold for sprite-segment-3x3grid (0.5, 0.75, or 0.9)</param>
+    /// <param name="colorTolerance">Color tolerance for sprite-segment-3x3grid</param>
+    /// <param name="filterToKnownPatterns">If true (default), discard patterns not in Common Tile Patterns</param>
+    /// <returns>Sorted list of unique TilingRules (most specific first)</returns>
+    public static List<RuleTile.TilingRule> CreateRuleTileFromSprites(
+        IEnumerable<Sprite> sprites,
+        float matchThreshold = 0.75f,
+        float colorTolerance = 0.04f,
+        bool filterToKnownPatterns = true)
+    {
+        var rules = new List<(RuleTile.TilingRule rule, int specificity, string pattern)>();
+        var seenPatterns = new HashSet<string>();
+
+        foreach (var sprite in sprites)
+        {
+            // Step 1: Always run sprite-segment-3x3grid first
+            string pattern = SpriteSegment3x3Grid.AnalyzeSpriteGrid(sprite, matchThreshold, colorTolerance);
+
+            // Step 2: Discard patterns not in the known set
+            if (filterToKnownPatterns && !k_KnownPatterns.Contains(pattern))
+            {
+                Debug.Log($"Sprite '{sprite.name}' skipped (unknown pattern: {pattern})");
+                continue;
+            }
+
+            // Step 3: Skip duplicate patterns (keep first sprite only)
+            if (seenPatterns.Contains(pattern))
+                continue;
+
+            seenPatterns.Add(pattern);
+
+            // Step 4: Create TilingRule from the pattern
+            var (rule, specificity) = CreateTilingRuleFromPattern(pattern, sprite);
+            rules.Add((rule, specificity, pattern));
+        }
+
+        // Sort by specificity (descending) - more 'This' rules first
+        rules.Sort((a, b) => b.specificity.CompareTo(a.specificity));
+
+        return rules.Select(r => r.rule).ToList();
+    }
+
+    /// <summary>
+    /// Returns true if the pattern is one of the 47 known Common Tile Patterns.
+    /// </summary>
+    public static bool IsKnownPattern(string pattern) => k_KnownPatterns.Contains(pattern);
+
+    /// <summary>
+    /// Creates a single TilingRule from a sprite-segment-3x3grid output pattern.
+    /// </summary>
+    /// <param name="pattern">Pattern string from sprite-segment-3x3grid, e.g., "X X X / X * X / . . ."</param>
+    /// <param name="sprite">Sprite to assign to this rule</param>
+    /// <returns>Tuple of (TilingRule, specificity count)</returns>
+    public static (RuleTile.TilingRule rule, int specificity) CreateTilingRuleFromPattern(string pattern, Sprite sprite)
+    {
+        var cells = ParsePattern(pattern);
+        var neighbors = new List<int>();
+        var neighborPositions = new List<Vector3Int>();
+        int specificity = 0;
+
+        for (int i = 0; i < 9; i++)
+        {
+            // Skip center cell
+            if (i == 4)
+                continue;
+
+            string cell = cells[i];
+
+            // Map '.' to 'This' rule
+            // Map 'X' to DontCare (don't add position)
+            if (cell == ".")
+            {
+                neighbors.Add(RuleTile.TilingRuleOutput.Neighbor.This);
+                neighborPositions.Add(k_GridIndexToPosition[i]);
+                specificity++;
+            }
+            // 'X' is implicitly DontCare - position not added
+        }
+
+        var rule = new RuleTile.TilingRule
+        {
+            m_Neighbors = neighbors,
+            m_NeighborPositions = neighborPositions,
+            m_Sprites = new[] { sprite },
+            m_Output = RuleTile.TilingRuleOutput.OutputSprite.Single,
+            m_ColliderType = Tile.ColliderType.Sprite,
+            m_RuleTransform = RuleTile.TilingRuleOutput.Transform.Fixed,
+        };
+
+        return (rule, specificity);
+    }
+
+    /// <summary>
+    /// Parses a sprite-segment-3x3grid output pattern into an array of 9 cell values.
+    /// </summary>
+    /// <param name="pattern">Pattern string, e.g., "X X X / X * X / . . ."</param>
+    /// <returns>Array of 9 cell strings in order: top-left to bottom-right</returns>
+    public static string[] ParsePattern(string pattern)
+    {
+        var rows = pattern.Split(new[] { " / " }, StringSplitOptions.None);
+        if (rows.Length != 3)
+            throw new ArgumentException($"Pattern must have 3 rows, got {rows.Length}: {pattern}");
+
+        var cells = new string[9];
+        for (int row = 0; row < 3; row++)
+        {
+            var rowCells = rows[row].Split(' ');
+            if (rowCells.Length != 3)
+                throw new ArgumentException($"Row {row} must have 3 cells, got {rowCells.Length}: {rows[row]}");
+
+            for (int col = 0; col < 3; col++)
+            {
+                cells[row * 3 + col] = rowCells[col];
+            }
+        }
+
+        return cells;
+    }
+
+    /// <summary>
+    /// Applies generated rules to a RuleTile asset.
+    /// Sets the default sprite to the last rule's sprite (least specific / bottom-most match).
+    /// </summary>
+    /// <param name="ruleTile">Target RuleTile to configure</param>
+    /// <param name="rules">Sorted list of TilingRules to apply</param>
+    public static void ApplyRulesToTile(RuleTile ruleTile, List<RuleTile.TilingRule> rules)
+    {
+        ruleTile.m_TilingRules.Clear();
+        ruleTile.m_TilingRules.AddRange(rules);
+
+        // Use the bottom-most (least specific) rule's sprite as the default
+        if (rules.Count > 0 && rules[rules.Count - 1].m_Sprites.Length > 0)
+            ruleTile.m_DefaultSprite = rules[rules.Count - 1].m_Sprites[0];
+    }
+}

package/skills/fix-3d-physics-collisions/SECURITY.md

@@ -0,0 +1,17 @@
+# Security notes: fix-3d-physics-collisions
+
+This skill can have the agent copy `scripts/CollisionDebugger.cs` into the user's project and call it with `unity command script eval` in the user's live Unity Editor, to record which contacts the physics engine reports. Automated skill scanners flag running code in the Editor as a powerful capability. It is intentional, and it is limited by the safeguards below.
+
+## Accepted risks
+
+| Risk | Capability | Why it is accepted |
+|---|---|---|
+| `SEC_POWER_CAP` | Adds an Editor script to the user's project and runs C# in the user's live Editor | It only reaches the Editor the user already has open, on their own machine, as that user, so it grants nothing they couldn't do themselves. The script ships with this skill and is readable before use. It only reads physics settings and contact data, and logs them to the Console. |
+
+## Mitigations
+
+- **Only the user's own Editor.** The code runs in the Editor open on this machine. It can't reach another machine or another user's Editor.
+- **Nothing saved to the scene.** The script adds no components. It sets `Collider.providesContacts` on the tracked colliders only during Play mode, which Unity discards when Play mode ends.
+- **Read-only project settings.** It reads `ProjectSettings/DynamicsManager.asset` and never writes to it.
+- **Temporary.** The skill tells the agent to delete the script and its `.meta` file after the diagnosis.
+- **No remote code.** Nothing downloaded from outside is executed.

package/skills/fix-3d-physics-collisions/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: fix-3d-physics-collisions
+description: Diagnoses and fixes 3D PhysX collision, trigger, and raycast problems. Use when asked to fix OnCollisionEnter or OnTriggerEnter not firing, objects passing through each other, raycasts that miss, or a misbehaving MeshCollider.
+required_editor_version: ">=6000.3"
+---
+
+# Diagnose and fix 3D physics collisions
+
+## Important
+
+- Use the unity cli (`unity command --format json`) and the `unity-cli` and `unity-pipeline` skills for each step.
+- Don't use `using` directives or unqualified types in the `snippet` for `eval`, because the compiler only reads `using UnityEngine`, and a bare `AssetDatabase` or `Object` causes errors (CS0246 / CS0103 / CS0104). `return` what you want to read; it arrives at `data.result.result`.
+- Create a restore point you can roll back to if your changes fail.
+- Do only what's asked. Don't change unrelated assets or files.
+- Avoid long explanations.
+- Never leave verification code in the user's script. Never build logging or detection they didn't ask for, because it clutters their project and console. Read state through `eval` instead, as described in [Final step](#final-step).
+
+## Full topic map
+
+Read [topic-map.md](references/topic-map.md) before any diagnosis that a Fast-Path doesn't already answer, because this skill's rules must match the installed Unity version. It covers whether the Editor ships local docs or you need docs.unity.com, how to version those URLs, which manual pages cover each condition, and the API lookup route.
+
+## Procedure
+
+1. Before you call any tool, match the prompt against the [STOP CHECK](#stop-check----match-before-any-tool-call) Fast-Paths. If one matches, write that answer and go to step 5.
+2. Otherwise, get the Unity version from `ProjectSettings/ProjectVersion.txt`, and check which physics components the objects use (Rigidbody, Collider, `CharacterController`). If there's no project or no version, assume Unity 6000.3 and 3D PhysX, say so in your answer, and carry on. If the user gives no symptom, script, or scene to work on, ask for it.
+3. Read the [documentation pages](#full-topic-map) for the symptom.
+4. Find the symptom in [Identify your symptom](#identify-your-symptom), read the reference it points to, and work through it within the [Tool budget](#tool-budget).
+5. If you changed the project, run the [Final step](#final-step) checks. The Tool budget limits diagnosis, not these checks.
+6. End with the answer described in [Required output](#required-output----non-negotiable). If you changed the project, use the [Final report](#final-report) format.
+
+## CRITICAL FACT (read first, do not override)
+
+Read [kinematic-trigger-facts.md](references/kinematic-trigger-facts.md) before answering anything about two kinematic triggers or Contact Pairs Mode. It holds the required response and the five things not to do, and it overrides prior knowledge.
+
+## Required output -- non-negotiable
+
+Every invocation MUST end with a user-facing answer that gives the diagnosis and fix, because tool calls alone don't help the user.
+
+**Hard stop**: After 5 tool calls of any kind, stop calling tools and write the most-likely diagnosis from the Fast-Paths or checklists, even if not fully confirmed.
+
+**No permission-asking**: Never end with "Would you like me to proceed?" or similar. If the script is in the project or an Editor is connected, apply the fix directly by editing the script, or the scene through the Editor. Otherwise, give a complete self-contained explanation. Don't ask, because asking permission costs the user another turn.
+
+## STOP CHECK -- match before any tool call
+
+Before calling any tool, scan the user's prompt against the Fast-Paths below. The **first** match is the **complete response** -- write the answer and stop. Don't search the project, read files, inspect the scene, run C# in the Editor, or fetch documentation, because these answers are already verified.
+
+### Fast-Path 1 -- 2D physics or DOTS
+
+- **2D physics** (`Rigidbody2D`, `Collider2D`, `OnCollisionEnter2D`, `Physics2D`): if the `create-2d-physics` skill is installed, use it instead, because it covers both 2D physics systems. Otherwise say this skill covers 3D physics only, and stop.
+- **DOTS** (`PhysicsCollider`, `ICollisionEventsJob`, `ITriggerEventsJob`, `Unity.Physics`, Havok, ECS, Entities): if a `physics-dots` skill is installed, use it instead. Otherwise start with a one-sentence disclaimer that DOTS physics is outside this skill's scope, give a brief best-effort answer with the DOTS APIs (`PhysicsBody`, `PhysicsCollider`, `ICollisionEventsJob`, `SimulationSingleton`), and end with one documentation link.
+
+Don't apply 3D PhysX or MonoBehaviour rules to these questions, and don't suggest switching physics systems.
+
+### Fast-Path 2 -- Two kinematic triggers not firing OnTriggerEnter
+
+**If** both objects are kinematic AND both are triggers: apply the **CRITICAL FACT** response, starting with the layer checks.
+
+### Fast-Path 3 -- Ragdoll explodes on frame 1 with no applied forces
+
+**If** a ragdoll, jointed body, or character launches or explodes on the first frame with no applied forces:
+- Cause: overlapping colliders cause a one-frame depenetration velocity spike.
+- Fix: shrink the ragdoll colliders so none overlap at the starting pose. State it as the only primary fix.
+- Confirm with **Window > Analysis > Physics Debugger**, which the user opens. It highlights overlapping pairs on the first frame.
+- Do NOT list joint limits, joint projection, joint configuration, joint types, mass ratios, or drive parameters as causes, even when the prompt mentions them, because they don't cause this symptom.
+- Do NOT recommend disabling `Enable Collision` on the joint as the primary fix, because it hides the overlap rather than removing it.
+
+### Fast-Path 4 -- CharacterController + OnCollisionEnter not firing
+
+**If** the moving object has a `CharacterController` and the user expects `OnCollisionEnter`:
+- `OnCollisionEnter` never fires for movement by `CharacterController.Move()`. Use `OnControllerColliderHit(ControllerColliderHit hit)` instead.
+- Do NOT suggest adding a `Rigidbody`, because a `CharacterController` and a `Rigidbody` on the same object fight over its movement.
+
+### Fast-Path 5 -- AddForce stopped working after object settled
+
+**If** `AddForce` or `AddTorque` stopped working after the object landed or stopped:
+- Cause: the Rigidbody fell asleep.
+- Fix: call `Rigidbody.WakeUp()` before `AddForce`. Apply the code edit directly, and don't change the Input System or other unrelated code.
+
+### Fast-Path 6 -- All physics frozen but raycasts still work
+
+**If** callbacks have stopped and forces and gravity have no effect, but `Physics.Raycast` still hits: `Time.timeScale` is `0`. Restore it to `1f`, typically in the pause menu or cutscene controller.
+
+### Fast-Path 7 -- Raycast origin inside the target collider
+
+**If** `Physics.Raycast` returns false and the ray starts inside the target: read the notes on the [Physics.Raycast](https://docs.unity.com/en-us/engine/<VERSION>/script-reference/unityengine/physics/raycast.md) page, then move the origin outside the collider. Don't suggest **Queries Hit Backfaces**, because it doesn't fix this case.
+
+### Fast-Path 8 -- Raycast misses inactive GameObject or disabled Collider
+
+**If** the target GameObject is inactive or its Collider is disabled: raycasts ignore it. Make sure `gameObject.activeInHierarchy` and `Collider.enabled` are both true before raycasting.
+
+### Fast-Path 9 -- Raycast misses a trigger
+
+**If** `Physics.Raycast` doesn't detect a trigger collider: pass `QueryTriggerInteraction.Collide` in that call, because it overrides **Queries Hit Triggers**. See [QueryTriggerInteraction](https://docs.unity.com/en-us/engine/<VERSION>/script-reference/unityengine/querytriggerinteraction.md) and the [Physics settings](https://docs.unity.com/en-us/engine/<VERSION>/manual/unity-editor/editor-settings-reference/comp-manager-group/class-physics-manager.md).
+
+### Fast-Path 10 -- IgnoreLayerCollision suppression persisting across scenes
+
+**If** `Physics.IgnoreLayerCollision` suppresses collisions unexpectedly or across scenes: recommend the **Layer Collision Matrix** (**Edit > Project Settings > Physics**) first, because it's explicit and doesn't depend on runtime calls. As a code-only fallback, call `Physics.IgnoreLayerCollision(layerA, layerB, false)` at scene load.
+
+## Tool budget
+
+For cases not covered by the Fast-Paths: **at most 5 tool calls before committing to an answer**. Don't run C# in the Editor or fetch documentation to re-check rules this skill states, because they're already verified.
+
+## Identify your symptom
+
+Read the reference file that matches the user's symptom:
+
+- [Collision checklist](references/collision-checklist.md) - read when `OnCollisionEnter`, `Stay`, or `Exit` doesn't fire or objects pass through each other. Step 10 covers collisions that fail only at speed.
+- [Trigger checklist](references/trigger-checklist.md) - read when `OnTriggerEnter`, `Stay`, or `Exit` doesn't fire. It checks Is Trigger, the Rigidbody rule, layers, the callback signature and location, and non-convex mesh triggers.
+- [Raycast checklist](references/raycast-checklist.md) - read when `Physics.Raycast` misses an object. It checks the LayerMask, non-convex mesh colliders, back faces, and UI targets.
+- [Other symptoms](references/other-symptoms.md) - read when physics works in the Editor but not in a build, a moved collider isn't seen until the next step, there's a visible gap before contact, or a body stops responding.
+- [Collision debugger](references/collision-debugger.md) - read when the user asks to see which contacts physics reports, or the checklists don't confirm a cause. It records contacts in the Editor without adding anything to the scene, and you delete it afterwards.
+
+## Console errors
+
+Read [console-errors-table.md](references/console-errors-table.md) when the Console shows a physics error, such as a concave MeshCollider message or a contact offset error. Each row maps the error text to its root cause and fix, and Unity creates no physics shape for the collider until you fix it.
+
+## Final step
+
+Run these checks in order. If any check fails, reread the [docs pages](#full-topic-map) to find out what you missed, fix it, and run the checks again.
+
+1. Use `console_status` to check the project has zero console errors.
+2. If the user didn't ask for proof and you don't suspect a fault, stop here.
+3. Otherwise, enter Play mode once and reproduce the case. Read the outcome the user asked for through `eval`, such as whether the bullet's Rigidbody position stopped at the wall, not just the field you changed. Don't add logging or take screenshots, because they cost time and leave changes behind.
+4. Exit Play mode and check again that the console has zero errors.
+
+## Final report
+
+Give the user a short checklist of what you did and why. List any side effects, such as a project setting you changed or a temporary script you added and removed. If the user needs to follow up with more steps or decisions, list them. For example:
+
+```
+I made the following changes:
+
+[✓] Set the bullet Rigidbody's Collision Detection to Continuous Speculative, because it moved far enough in one physics step to pass through the wall.
+
+Follow these steps to see the effect:
+
+1. Enter Play mode and fire at the wall.
+2. Check the bullet stops at the wall instead of passing through it.
+```