@aqian0/dsh-unity 0.0.0-stage → 0.1.0

package/skills/create-tile-palette-or-rule-tiles/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: create-tile-palette-or-rule-tiles
+description: Creates a 2D tile palette from sprites or textures, or makes tiles change based on their neighbours. Use when the user wants a tile palette or tiles that connect to their neighbours as they paint, even when they don't name them.
+required_packages:
+  com.unity.2d.tilemap: ">=1.0.0"
+  com.unity.2d.tilemap.extras: ">=4.0.0"
+---
+
+# Create tile palettes and RuleTiles
+
+## Important
+
+- Use the unity cli (`unity command --format json`) and the `unity-cli` and `unity-pipeline` skills for each step.
+- Before making changes, establish a baseline of the current behavior so you can tell whether a later result is actually caused by your change.
+- 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.
+- Never leave verification code in the user's script. Never build logging or detection they didn't ask for. See [Final step](#final-step).
+- Avoid long explanations.
+
+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.
+
+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. Replace `<VERSION>` with the following before fetching:
+
+- **docs.unity3d.com**: The Unity version, eg `6000.6`
+- **Package on docs.unity3d.com**: The package version, eg `@6.6` or `@2.0`. Check the package version if unsure.
+- **Engine on docs.unity.com**: The Unity version, eg `6000.3`
+
+Read the Unity version from `ProjectSettings/ProjectVersion.txt`. For package docs, use the package's major.minor from `Packages/packages-lock.json`, eg `1.0` for `com.unity.2d.tilemap` or `6.0` for `com.unity.2d.tilemap.extras`.
+
+## Full topic map
+
+Engine Manual 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 `en/Manual` folder. Otherwise the docs pages are online at `https://docs.unity.com/en-us/engine/<VERSION>/manual/unity2d/tilemaps.md`.
+
+- **Create a tile palette** — local `en/Manual/tilemaps/tiles-for-tilemaps/create-tile-assets.html`, online `https://docs.unity.com/en-us/engine/<VERSION>/manual/unity2d/tilemaps/create-tile-palette/assets.md` — the palette asset, its settings sub-asset, and adding tiles.
+- **Tile Palette window reference** — local `en/Manual/tilemaps/tile-palettes/tile-palette-editor-reference.html`, online `https://docs.unity.com/en-us/engine/<VERSION>/manual/unity2d/tilemaps/create-tile-palette/tile-palette-editor-reference.md` — Cell Size, Sort Mode and Sort Axis settings.
+
+Package manual pages: the docs pages are local markdown conversions of the Unity Manual, stored at `<project-folder>/Library/PackageCache/com.unity.2d.tilemap.extras@*/`. Read only the .md files in that specific `PackageCache` subfolder. You must not look at non-.md files, or look outside at other Library or PackageCache folders, otherwise it takes too much time. If that folder has no `.md` files, use the online pages at `https://docs.unity3d.com/Packages/com.unity.2d.tilemap.extras@<VERSION>/manual/`, because some packages don't ship their docs.
+
+- **Rule Tile** — `Documentation~/RuleTile.md` — how Rule Tiles match neighbours, rule order, and the Default Sprite.
+
+### API reference
+
+The APIs are `UnityEditor.Tilemaps` (`GridPaletteUtility`) in the `com.unity.2d.tilemap` package, `RuleTile`, `HexagonalRuleTile` and `IsometricRuleTile` in the `com.unity.2d.tilemap.extras` package, and `AssetDatabase` in the Unity Engine. Package APIs are versioned by package version and Engine APIs by Unity version, so check both before relying on a specific class or method, because APIs are frequently marked obsolete between versions.
+
+1. Use the `unity-cli` skill to check the project's Unity version and installed package versions.
+2. For package APIs, fetch and cache `https://docs.unity3d.com/Packages/<package-name>@<version>/xrefmap.yml` (eg `com.unity.2d.tilemap.extras@6.0`). It maps each public member's fully qualified name to its docs page `href` (eg `href: api/UnityEngine.RuleTile.TilingRule.html` => `https://docs.unity3d.com/Packages/com.unity.2d.tilemap.extras@6.0/api/UnityEngine.RuleTile.TilingRule.html`). Grep it locally instead of refetching per lookup; don't read the whole file. Start with `GridPaletteUtility.CreateNewPalette`, `RuleTile.TilingRule` (`m_Neighbors`, `m_NeighborPositions`, `m_RuleTransform`) and `RuleTile.TilingRuleOutput.Neighbor` (`This`, `NotThis`).
+3. For Engine APIs, if the Editor install folder has a `Data/Documentation` folder, grep the html files in its `en/ScriptReference` folder and skip the rest of this step. Otherwise fetch and cache `https://docs.unity3d.com/<VERSION>/Documentation/ScriptReference/xrefmap.yml` (about 6 MB, so grep it, don't read it) and convert the `uid` to a markdown page: remove the parameters in brackets, lowercase it, replace `.` with `/`, add `.md`, and fetch `https://docs.unity.com/en-us/engine/<VERSION>/script-reference/<converted uid>`. For example, `UnityEditor.AssetDatabase.LoadAllAssetsAtPath(System.String)` => `https://docs.unity.com/en-us/engine/6000.3/script-reference/unityeditor/assetdatabase/loadallassetsatpath.md`. If that page doesn't exist, use the entry's `href` under `https://docs.unity3d.com/<VERSION>/Documentation/ScriptReference/`.
+
+## Glossary
+
+The reference files write RuleTile rules as 3x3 text grids, read from the top row to the bottom row:
+
+| Symbol | Meaning | In the API | In the Rule Tile Inspector |
+|--------|---------|------------|----------------------------|
+| `.` | The neighbour must be this RuleTile | `RuleTile.TilingRuleOutput.Neighbor.This` | Green arrow |
+| `X` | Any neighbour (don't care) | Position left out of `m_Neighbors` and `m_NeighborPositions` | Empty cell |
+| `*` | The tile itself | Not stored | Centre cell |
+
+Don't read `X` as `NotThis`, because the Inspector draws `NotThis` as a red X, which means the opposite: the neighbour must not be this RuleTile.
+
+## Workflow
+
+Pick the matching reference doc based on what the user wants, then follow it:
+
+- **Tile Palette** — [references/palette-create.md](references/palette-create.md) — when the user wants to organize tiles for 2D level design or create a new rectangular, hexagonal, isometric, or isometric Z as Y grid layout.
+- **Blank/empty RuleTile** (no sprites provided) — [references/ruletile-createempty.md](references/ruletile-createempty.md) — when the user wants a blank RuleTile (rectangular grid), HexagonalRuleTile, or IsometricRuleTile for custom rule configuration and has not provided or referenced any sprites.
+- **RuleTile built from existing sprites** (sprites, terrain art, edge tiles provided) — [references/ruletile-createfromsegment.md](references/ruletile-createfromsegment.md) — when the user wants tiles that autotile as they paint, or a RuleTile built from existing terrain or edge sprites so tiles connect correctly.
+
+## Final step
+
+Do the following checks:
+
+1. Check the project has zero console errors. Use `console_status` for counts.
+2. Read the assets back with `eval` (fully qualified), because an asset can exist without its settings having stuck:
+   - If you created a tile palette, check that `AssetDatabase.LoadAllAssetsAtPath` on the palette returns a `GridPalette` sub-asset, and that the `Grid` on the palette's root GameObject has the `cellLayout` and `cellSize` you chose.
+   - If you created a RuleTile, check that `AssetDatabase.LoadAssetAtPath` with the RuleTile type you created returns the asset, that `m_TilingRules.Count` equals the number of rules you created, and that each rule's `m_Sprites` has exactly one entry: `null` for an empty RuleTile, or the assigned sprite for one built from sprites.
+3. If you built a RuleTile from sprites, check that it picks the right sprite as it's painted, because correct fields don't prove the rules match the art. Open a temporary scene with `EditorSceneManager.NewScene(NewSceneSetup.EmptyScene, NewSceneMode.Additive)`, add a Grid with a Tilemap, use `Tilemap.SetTile` to paint a 3x3 block of the RuleTile, and check that `Tilemap.GetSprite` at each cell returns the sprite of the rule that matches that cell's neighbours. For example, the centre cell gets the fully surrounded rule's sprite, if the RuleTile has that rule. Then close the scene with `EditorSceneManager.CloseScene(scene, true)` without saving it.
+4. If a value doesn't match, fix the asset and repeat the check.
+5. Stop there unless the user asked you to prove it works or you suspect a specific fault. If you do enter Play mode, do it once only to chase a fault you already suspect. Read the world through `eval` rather than adding logging. Take no screenshots, because they take too much time.
+
+If a check fails, go back and reread the [docs pages](#full-topic-map) to find out what you missed.
+
+## Final report
+
+Report the following, in order:
+
+1. What changed: each asset you created, with its path and type, and the settings you used (grid type, cell size, sort axis, or number of tiling rules).
+2. Side effects: any other file or scene you created or changed, such as an editor script copied from `scripts/` into `Assets`, so the user can remove it.
+3. The verification results from the final step.
+4. Follow-up the user must do, such as assigning sprites to an empty RuleTile or adding the RuleTile to a tile palette.

package/skills/create-tile-palette-or-rule-tiles/references/hexagonalruletile.md

@@ -0,0 +1,71 @@
+# Hexagonal RuleTile template
+
+This file provides a template and logic for creating complex `HexagonalRuleTiles`. Use this to programmatically generate or manually configure new Hexagonal RuleTiles for pointy-top hex grids.
+
+## Hexagonal Tile Rule Pattern (Pointy Top)
+
+A Hexagonal RuleTile uses 6 possible neighbor directions. These neighbors are defined as follows:
+
+### Neighbor Directions and Coordinate Mappings
+
+For a tile at `(x, y, 0)`, the 6 neighbors are at:
+1.  **North-West (NW)**: `(-1, 1, 0)`
+2.  **North (N)**: `(0, 1, 0)`
+3.  **East (E)**: `(1, 0, 0)`
+4.  **South-West (SW)**: `(-1, -1, 0)`
+5.  **South (S)**: `(0, -1, 0)`
+6.  **West (W)**: `(-1, 0, 0)`
+
+### Legend:
+- `.`: **This** (Type 1)
+- `X`: **Any** (Type 0)
+- **Fixed**: Rule is applied exactly as defined.
+- **MirrorX**: Rule is applied as defined and mirrored across the X-axis.
+
+## Full Tiling Rules Template
+
+The hexagonal tile set uses **MirrorX** and **Fixed** transforms. **Rotated** is not used in this specific set.
+
+| Rule ID | Neighbor Configurations (Pos: Type) | Transform | Description |
+|:--------|:------------------------------------| :--- | :--- |
+| 0       | NW:., N:., E:., SW:., S:., W:.      | Fixed | Full 6-neighbor surrounded |
+| 1       | NW:., W:., SW:., S:., E:.           | MirrorX | 5-neighbor surrounded |
+| 2       | NW:., W:., E:., SW:., N:.           | MirrorX | 5-neighbor surrounded variant |
+| 3       | N:., NW:., W:., SW:., S:.           | MirrorX | 5-neighbor surrounded variant |
+| 4       | W:., SW:., S:., E:.                 | Fixed | 4-neighbor connectivity |
+| 5       | W:., NW:., N:., E:.                 | Fixed | 4-neighbor connectivity |
+| 6       | NW:., W:., SW:., S:.                | MirrorX | 4-neighbor corner/edge |
+| 7       | NW:., W:., SW:., N:.                | MirrorX | 4-neighbor corner/edge |
+| 8       | NW:., SW:., W:., E:.                | MirrorX | 4-neighbor bridge |
+| 9       | NW:., W:., E:., S:.                 | MirrorX | 4-neighbor connectivity |
+| 10      | NW:., SW:., S:., E:.                | MirrorX | 4-neighbor connectivity |
+| 11      | NW:., N:., S:., SW:.                | Fixed | 4-neighbor vertical-ish |
+| 12      | N:., NW:., W:., S:.                 | Fixed | 4-neighbor horizontal-ish |
+| 13      | W:., SW:., S:.                      | MirrorX | 3-neighbor corner |
+| 14      | NW:., W:., SW:.                     | MirrorX | 3-neighbor flat edge |
+| 15      | W:., NW:., N:.                      | MirrorX | 3-neighbor corner |
+| 16      | NW:., N:., S:.                      | MirrorX | 3-neighbor T-junction |
+| 17      | W:., SW:., E:.                      | MirrorX | 3-neighbor T-junction |
+| 18      | W:., N:., SW:.                      | MirrorX | 3-neighbor wide corner |
+| 19      | E:., NW:., SW:.                     | MirrorX | 3-neighbor wide corner |
+| 20      | NW:., W:., E:.                      | MirrorX | 3-neighbor wide corner |
+| 21      | SW:., S:., NW:.                     | MirrorX | 3-neighbor variant |
+| 22      | W:., NW:., S:.                      | MirrorX | 3-neighbor variant |
+| 23      | NW:., W:.                           | Fixed | 2-neighbor edge |
+| 24      | W:., SW:.                           | Fixed | 2-neighbor edge |
+| 25      | SW:., S:.                           | Fixed | 2-neighbor edge |
+| 26      | E:., S:.                            | Fixed | 2-neighbor edge |
+| 27      | N:., E:.                            | Fixed | 2-neighbor edge |
+| 28      | NW:., N:.                           | Fixed | 2-neighbor edge |
+| 29      | W:., E:.                            | MirrorX | 2-neighbor opposite bridge |
+| 30      | N:., SW:.                           | MirrorX | 2-neighbor long bridge |
+| 31      | W:., S:.                            | MirrorX | 2-neighbor acute corner |
+| 32      | E:., NW:.                           | MirrorX | 2-neighbor long bridge variant |
+| 33      | N:., S:.                            | MirrorX | 2-neighbor vertical bridge |
+| 34      | N:.                                 | MirrorX | Single neighbor North |
+| 35      | E:.                                 | MirrorX | Single neighbor East |
+| 36      | S:.                                 | MirrorX | Single neighbor South |
+| 37      | all 6 surrounding positions: X    | Fixed | Default / No-neighbor |
+
+#### Usage
+When applying this template to a new texture set, first ensure the texture is sliced into sprites matching these 38 logical configurations. Then, run a script using the description to map the sprites to each rule. Ensure that HexagonalRuleTile has all 38 TilingRules listed in the template.

package/skills/create-tile-palette-or-rule-tiles/references/palette-create.md

@@ -0,0 +1,38 @@
+# Tilemap Palette Creation
+
+Requires package: `com.unity.2d.tilemap` >=1.0.0
+
+## Workflow
+
+### Step 1: Parameter Gathering
+WAIT for the user to specify the following parameters if not already provided, because the name sets the asset file name and the grid type sets the palette's cell layout and cell size:
+- **Palette Name**: The name of the asset.
+- **Grid Type**: Rectangular, Hexagonal, Isometric, or Isometric Z As Y.
+- **Cell Size**: Optional (defaults based on Grid Type).
+- **Sort Axis**: Required for Isometric palettes.
+
+### Step 2: Asset Creation
+Utilise `UnityEditor.Tilemaps.GridPaletteUtility.CreateNewPalette` to create the Tile Palette asset.
+
+## Branching Logic (Grid Types)
+
+### Path A: Rectangular
+- Use **Automatic** cell sizing with a `cellSize` of `(1, 1, 0)`, as `CreatePaletteTemplate.cs` does, because square tiles then fill one cell each.
+
+### Path B: Hexagonal
+- Use cell size: `(0.8659766, 1, 1)`, because a hexagon's width is about 0.866 of its height, so neighbouring hex tiles meet without gaps.
+
+### Path C: Isometric
+- Use cell size: `(1, 0.5, 1)`, because isometric tiles are diamonds twice as wide as they are tall.
+- Use a **Custom Sort Axis** with value `(0, 0, 1)`, because overlapping isometric tiles must draw in a fixed order or the palette shows them in front of each other wrongly.
+
+### Path D: Isometric Z As Y
+- Use cell size: `(1, 0.5, 1)`, for the same reason as Path C.
+- Use a **Custom Sort Axis** with value `(0, 0, 1)`, for the same reason as Path C.
+
+## Post-Creation
+Ensure that there is a `GridPalette` as a sub-asset of the Tile Palette asset, because the Tile Palette window can't use the palette without that sub-asset. Check with `AssetDatabase.LoadAllAssetsAtPath`.
+
+## References
+
+Code Template: "../scripts/CreatePaletteTemplate.cs"

package/skills/create-tile-palette-or-rule-tiles/references/ruletile-createempty.md

@@ -0,0 +1,37 @@
+# Tilemap RuleTile Create Empty
+
+Links in this file are relative to this `references/` folder; `..` resolves to the skill directory.
+
+Use ONLY when the user wants a blank RuleTile, HexagonalRuleTile, or IsometricRuleTile for custom rule configuration AND has not provided or referenced any sprites. If the user mentions existing sprites, terrain art, edge tiles, or a tiles folder, use [ruletile-createfromsegment.md](ruletile-createfromsegment.md) instead, never this.
+
+Requires packages: `com.unity.2d.tilemap` >=1.0.0, `com.unity.2d.tilemap.extras` >=4.0.0
+
+## Workflow
+
+### Step 1: Verify No Sprite Inputs
+**WAIT** - Confirm that no Sprites or Spritesheets were specified by the user. This skill is only for empty RuleTiles, because it leaves every rule's sprite empty. If there are Sprites or Spritesheets specified by the user, use [ruletile-createfromsegment.md](ruletile-createfromsegment.md) instead.
+
+### Step 2: Determine RuleTile Type
+Identify which RuleTile type to create based on user request:
+- **RuleTile**: Standard rectangular grid
+- **HexagonalRuleTile**: Hexagonal grid layout
+- **IsometricRuleTile**: Isometric grid layout
+
+### Step 3: Create Empty TilingRules
+For each TilingRule, ensure the Sprite array has one `null` entry, because each rule outputs a single sprite and the user assigns it later.
+
+## Branching Logic (RuleTile Types)
+
+### Path A: RuleTile
+- Use the rule pattern from [ruletile.md](ruletile.md). Skip its Usage steps that slice the texture and map sprites, because an empty RuleTile leaves every sprite `null` (Step 3).
+
+### Path B: HexagonalRuleTile
+- Use the rule pattern from [hexagonalruletile.md](hexagonalruletile.md). Skip its Usage steps that map sprites, because an empty RuleTile leaves every sprite `null` (Step 3).
+
+### Path C: IsometricRuleTile
+- Use the rule pattern from [ruletile.md](ruletile.md), because `IsometricRuleTile` uses the same 8 neighbor positions as `RuleTile`, from `(-1, 1, 0)` to `(1, -1, 0)`. Only the on-screen direction of each position differs. Skip the Usage steps that slice the texture and map sprites, because an empty RuleTile leaves every sprite `null` (Step 3).
+
+## Important Notes
+
+- **TilingRuleOutput.Neighbor.This**: Use to identify RuleTiles that are the same (matching neighbors).
+- **TilingRuleOutput.Neighbor.NotThis**: Do NOT use unless explicitly specified by the user to ignore a Tile at a certain position, because a `NotThis` condition makes the rule fail whenever that neighbour is this RuleTile, which the templates don't expect.

package/skills/create-tile-palette-or-rule-tiles/references/ruletile-createfromsegment.md

@@ -0,0 +1,219 @@
+# Tilemap RuleTile Create From Segment
+
+Links in this file are relative to this `references/` folder; `..` resolves to the skill directory.
+
+## Contents
+
+Purpose, Workflow, Step 1, Step 2, Pattern Filtering, Deduplication, Rule Sorting, Sprite Assignment, Algorithm Summary, Scripts, Common Tile Patterns, Notes, Prerequisites, See Also.
+
+Use when the user wants tiles that auto-tile (autotile) as they paint, wants a RuleTile built from existing terrain or edge sprites, or asks to make sprites "tile correctly" or "connect properly". Also converts sprite-segment-3x3grid output patterns into Unity RuleTile TilingRules: 3x3 grid text patterns (X, ., *) become TilingRule neighbor configurations, mapping '.' to 'This' rules and 'X' to 'DontCare', sorted by specificity (more 'This' rules first). Sprites must be provided as input.
+
+Requires packages: `com.unity.2d.tilemap` >=1.0.0, `com.unity.2d.tilemap.extras` >=4.0.0
+
+## Purpose
+
+This skill creates Unity RuleTile TilingRules by first analyzing sprites using the `sprite-segment-3x3grid` skill, then converting the resulting text patterns into neighbor rule configurations. The user must specify Sprites or a Spritesheet input.
+
+## Workflow
+
+```
+Step 1: sprite-segment-3x3grid    Step 2: Create TilingRules
++--------------------------+      +--------------------------+
+|  Analyze each Sprite     |      |  Parse text patterns     |
+|  using color matching    |  ->  |  Map to neighbor rules   |
+|  Output: text pattern    |      |  Sort by specificity     |
++--------------------------+      +--------------------------+
+```
+
+**CRITICAL**: Always run the `sprite-segment-3x3grid` skill first on each Sprite to generate the text pattern.
+
+## Step 1: Apply sprite-segment-3x3grid (Required)
+
+For each Sprite in your texture, analyze it with `sprite-segment-3x3grid`:
+
+```csharp
+string pattern = SpriteSegment3x3Grid.AnalyzeSpriteGrid(sprite, matchThreshold: 0.75f);
+```
+
+### Pattern Output Format
+
+Single-line text pattern: `[TopRow] / [MiddleRow] / [BottomRow]`
+
+Each row contains 3 characters separated by spaces:
+- `X` - Cell does NOT meet match threshold
+- `.` - Cell MEETS match threshold (matches center color)
+- `*` - Center cell (the tile itself)
+
+Example: `X X X / X * X / . . .`
+
+## Step 2: Create TilingRules from Patterns
+
+### Symbol to Rule Mapping
+
+| Symbol | RuleTile Neighbor | Value | Behavior                                      |
+|--------|-------------------|-------|-----------------------------------------------|
+| `.`    | `This`            | 1     | Neighbor must be an instance of this RuleTile |
+| `X`    | `DontCare`        | 0     | Position not added to neighbors list          |
+| `*`    | (center)          | N/A   | Ignored - represents the tile itself          |
+
+**Note**: "DontCare" is not an explicit constant. A position is "don't care" when it is simply not included in the `m_Neighbors` and `m_NeighborPositions` lists.
+
+### Neighbor Position Mapping
+
+```
+Grid Layout:              Unity Vector3Int positions:
+[0] [1] [2]  (Top)        (-1,1,0)  (0,1,0)  (1,1,0)
+[3] [*] [5]  (Middle)     (-1,0,0)    ---    (1,0,0)
+[6] [7] [8]  (Bottom)     (-1,-1,0) (0,-1,0) (1,-1,0)
+```
+
+| Index | Position     | Vector3Int     |
+|-------|--------------|----------------|
+| 0     | Top-Left     | `(-1, 1, 0)`  |
+| 1     | Top          | `(0, 1, 0)`   |
+| 2     | Top-Right    | `(1, 1, 0)`   |
+| 3     | Left         | `(-1, 0, 0)`  |
+| 4     | Center       | (skipped)      |
+| 5     | Right        | `(1, 0, 0)`   |
+| 6     | Bottom-Left  | `(-1, -1, 0)` |
+| 7     | Bottom       | `(0, -1, 0)`  |
+| 8     | Bottom-Right | `(1, -1, 0)`  |
+
+## Pattern Filtering
+
+Discard detected patterns that don't match an entry in the Common Tile Patterns table, and keep only the 47 known patterns, because unexpected or noisy patterns add rules the user didn't draw art for. `CreateRuleTileFromSprites` does this by default.
+
+If the user explicitly asks to keep non-standard patterns, set `filterToKnownPatterns: false` to skip this filter.
+
+## Deduplication
+
+Remove TilingRules that have identical neighbor configurations. When several sprites produce the same pattern, keep the first sprite, because the first matching rule wins and a duplicate rule is never reached.
+
+## Rule Sorting
+
+Sort rules by specificity (number of `This` neighbors), most specific first, because the RuleTile uses the first rule that matches, so a less specific rule placed earlier hides the rules after it.
+
+| This Count | Example Pattern                 | Priority |
+|------------|---------------------------------|----------|
+| 8          | `. . . / . * . / . . .`        | First    |
+| 5          | `. . . / . * . / X X X`        | ...      |
+| 3          | `X X X / X * X / . . .`        | ...      |
+| 0          | `X X X / X * X / X X X`        | Last     |
+
+## Sprite Assignment
+
+Assign at most 1 sprite to each TilingRule:
+- Set `m_Output` to `TilingRuleOutput.OutputSprite.Single`
+- Assign the sprite to `m_Sprites[0]`
+
+Set the RuleTile's `m_DefaultSprite` to the sprite from the least specific rule, which is the last rule in the sorted list, because the RuleTile shows the default sprite when no TilingRule matches.
+
+## Algorithm Summary
+
+1. **For each Sprite**: Run `sprite-segment-3x3grid` and store the pattern
+2. **Filter**: Discard patterns not in Common Tile Patterns (unless user opts out)
+3. **Deduplicate**: Remove duplicate patterns (first sprite wins)
+4. **Parse**: Split by ` / ` for rows, then by space for cells
+5. **Extract Neighbors**: `.` -> add position with `This` (1); `X` -> skip
+6. **Create TilingRule**: Populate `m_Neighbors` and `m_NeighborPositions`
+7. **Assign Sprite**: Set single sprite output
+8. **Sort**: Order by specificity descending
+9. **Apply**: Add sorted rules to RuleTile asset
+10. **Default Sprite**: Set `m_DefaultSprite` to the last (least specific) rule's sprite
+
+## Scripts
+
+Implementation and usage examples are in the `scripts/` folder:
+
+| File | Description |
+|------|-------------|
+| [`TilemapRuleTileCreateFromSegment.cs`](../scripts/TilemapRuleTileCreateFromSegment.cs) | Core implementation with `CreateRuleTileFromSprites`, `CreateTilingRuleFromPattern`, `ParsePattern`, and `ApplyRulesToTile` |
+| [`RuleTileGenerator.cs`](../scripts/RuleTileGenerator.cs) | Editor window example (`Tools > Generate RuleTile from Sprites`) |
+| [`ManualWorkflowExample.cs`](../scripts/ManualWorkflowExample.cs) | Manual two-step workflow for finer control over analysis |
+
+### Quick Usage
+
+```csharp
+// Get sprites and create rules in one call
+var rules = TilemapRuleTileCreateFromSegment.CreateRuleTileFromSprites(
+    sprites, matchThreshold: 0.75f, colorTolerance: 0.04f);
+
+// Apply to RuleTile
+var ruleTile = ScriptableObject.CreateInstance<RuleTile>();
+TilemapRuleTileCreateFromSegment.ApplyRulesToTile(ruleTile, rules);
+```
+
+## Common Tile Patterns
+
+| Tile Type                                            | Pattern                          | This Count |
+|------------------------------------------------------|----------------------------------|------------|
+| Fully surrounded (inner tile)                        | `. . . / . * . / . . .`          | 8          |
+| Top left corner missing                              | `X . . / . * . / . . .`          | 7          |
+| Top right corner missing                             | `. . X / . * . / . . .`          | 7          |
+| Bottom left corner missing                           | `. . . / . * . / X . .`          | 7          |
+| Bottom right corner missing                          | `. . . / . * . / . . X`          | 7          |
+| Top corners missing                                  | `X . X / . * . / . . .`          | 6          |
+| Bottom corners missing                               | `. . . / . * . / X . X`          | 6          |
+| Left corners missing                                 | `X . . / . * . / X . .`          | 6          |
+| Right corners missing                                | `. . X / . * . / . . X`          | 6          |
+| Top Left and Bottom Right diagonal corners missing   | `X . . / . * . / . . X`          | 6          |
+| Top Right and Bottom Left diagonal corners missing   | `. . X / . * . / X . .`          | 6          |
+| Top Left, Top Right and Bottom Left corners missing  | `X . X / . * . / X . .`          | 5          |
+| Top Left, Top Right and Bottom Right corners missing | `X . X / . * . / . . X`          | 5          |
+| Top Left, Bottom Left and Bottom Right corners missing | `X . . / . * . / X . X`        | 5          |
+| Top Right, Bottom Left and Bottom Right corners missing | `. . X / . * . / X . X`       | 5          |
+| Cross Section                                        | `X . X / . * . / X . X`          | 4          |
+| Flat edge (Bottom)                                   | `X X X / . * . / . . .`          | 5          |
+| Flat edge (Top)                                      | `. . . / . * . / X X X`          | 5          |
+| Flat edge (Left)                                     | `. . X / . * X / . . X`          | 5          |
+| Flat edge (Right)                                    | `X . . / X * . / X . .`          | 5          |
+| L-Shape, Point Right                                 | `X X X / . * . / . . X`          | 4          |
+| L-Shape, Point Bottom                                | `. . X / . * X / X . X`          | 4          |
+| L-Shape, Point Left                                  | `X . . / . * . / X X X`          | 4          |
+| L-Shape, Point Top                                   | `X . X / X * . / X . .`          | 4          |
+| L-Shape Inverse, Point Left                          | `X X X / . * . / X . .`          | 4          |
+| L-Shape Inverse, Point Bottom                        | `X . . / X * . / X . X`          | 4          |
+| L-Shape Inverse, Point Right                         | `. . X / . * . / X X X`          | 4          |
+| L-Shape Inverse, Point Top                           | `X . X / . * X / . . X`          | 4          |
+| T-Shape, face down                                   | `X X X / . * . / X . X`          | 3          |
+| T-Shape, face top                                    | `X . X / . * . / X X X`          | 3          |
+| T-Shape, face left                                   | `X . X / . * X / X . X`          | 3          |
+| T-Shape, face right                                  | `X . X / X * . / X . X`          | 3          |
+| Horizontal bridge                                    | `X X X / . * . / X X X`          | 2          |
+| Vertical bridge                                      | `X . X / X * X / X . X`          | 2          |
+| Corner piece, Bottom Right                           | `X X X / X * . / X . .`          | 3          |
+| Corner piece, Bottom Left                            | `X X X / . * X / . . X`          | 3          |
+| Corner piece, Top Left                               | `. . X / . * X / X X X`          | 3          |
+| Corner piece, Top Right                              | `X . . / X * . / X X X`          | 3          |
+| Edge end, Bottom Right                               | `X X X / X * . / X . X`          | 2          |
+| Edge end, Bottom Left                                | `X X X / . * X / X . X`          | 2          |
+| Edge end, Top Left                                   | `X . X / . * X / X X X`          | 2          |
+| Edge end, Top Right                                  | `X . X / X * . / X X X`          | 2          |
+| Single isolated tile, Left                           | `X X X / . * X / X X X`          | 1          |
+| Single isolated tile, Right                          | `X X X / X * . / X X X`          | 1          |
+| Single isolated tile, Top                            | `X . X / X * X / X X X`          | 1          |
+| Single isolated tile, Bottom                         | `X X X / X * X / X . X`          | 1          |
+| Center                                               | `X X X / X * X / X X X`          | 0          |
+
+## Notes
+
+- Always run `sprite-segment-3x3grid` first -- this skill depends on its output
+- Rules are evaluated in order; first matching rule wins
+- A rule with 0 `This` conditions matches any configuration (use as fallback)
+- The center cell (`*`) is always ignored in neighbor calculations
+- Unity's RuleTile supports up to 8 neighbors in a standard 3x3 grid
+- If the sprites are for an isometric grid, create an `IsometricRuleTile` with the same algorithm, because it uses the same 8 neighbor positions as `RuleTile`.
+- If the sprites are for a hexagonal grid, don't use this algorithm, because a hex tile has 6 neighbors that the 3x3 pattern can't describe. Instead, create a `HexagonalRuleTile` from the rule pattern in [hexagonalruletile.md](hexagonalruletile.md) and follow its Usage steps to map the sprites.
+
+## Prerequisites
+
+- **`sprite-segment-3x3grid` skill**: generates the input patterns. It ships in this
+  same plugin as `sprite-segment-3x3grid`, so it is always available — invoke
+  it rather than treating it as an unmet dependency.
+- **com.unity.2d.tilemap.extras package**: Required for RuleTile class
+
+## See Also
+
+- `sprite-segment-3x3grid` - required prerequisite; generates the input patterns
+- `RuleTile` API: look members up with the `com.unity.2d.tilemap.extras` `xrefmap.yml`, as the skill's API reference section describes, rather than reading the package's C# source.
+- Rule Tile manual: `<project>/Library/PackageCache/com.unity.2d.tilemap.extras@*/Documentation~/RuleTile.md` (read only .md files in that folder). If it isn't there, because some packages don't ship their docs, fetch `https://docs.unity3d.com/Packages/com.unity.2d.tilemap.extras@<VERSION>/manual/RuleTile.html`, replacing `<VERSION>` with the package's major.minor from `Packages/packages-lock.json`

package/skills/create-tile-palette-or-rule-tiles/references/ruletile.md

@@ -0,0 +1,95 @@
+# RuleTile template
+
+This file provides a template and logic for creating complex `RuleTiles`. Use this guide to programmatically generate or manually configure new RuleTiles that follow consistent connectivity patterns.
+
+## Rule Tile Rule Pattern
+
+The following rules define the connectivity for a standard 2D top-down layout. Each rule checks its 3x3 neighborhood for this RuleTile (`.`) or doesn't check the position at all (`X`).
+
+Pick one template:
+
+- If the sprite sheet has a separate sprite for each orientation of an edge, corner or end piece (for example, four flat-edge sprites), use the [Fixed template](#tiling-rules-template-for-fixed-rule-tiles), because each orientation needs its own rule and sprite.
+- If the sprite sheet has one sprite per shape for the RuleTile to rotate, or the user has no sprites yet and doesn't say, use the [Rotated template](#tiling-rules-template-for-rotated-rule-tiles), because one rotated rule covers all four orientations, so the user has fewer sprites to assign.
+
+## Legend
+- `.`: **This** (Tile must be present)
+- `X`: **Any** (Does not matter)
+- `*`: The tile itself (Center)
+
+### Tiling Rules Template for Fixed Rule Tiles
+
+| Rule ID | Neighbors (Top to Bottom, Left to Right) | Rule Transform | Description                                             |
+|:--------|:-----------------------------------------|:---------------|:--------------------------------------------------------|
+| 0       | `. . .` / `. * .` / `. . .`              | Fixed          | Fully surrounded (inner tile)                           |
+| 1       | `X . .` / `. * .` / `. . .`              | Fixed          | Top left corner missing                                 |
+| 2       | `. . X` / `. * .` / `. . .`              | Fixed          | Top right corner missing                                |
+| 3       | `. . .` / `. * .` / `X . .`              | Fixed          | Bottom left corner missing                              |
+| 4       | `. . .` / `. * .` / `. . X`              | Fixed          | Bottom right corner missing                             |
+| 5       | `X . X` / `. * .` / `. . .`              | Fixed          | Top corners missing                                     |
+| 6       | `. . .` / `. * .` / `X . X`              | Fixed          | Bottom corners missing                                  |
+| 7       | `X . .` / `. * .` / `X . .`              | Fixed          | Left corners missing                                    |
+| 8       | `. . X` / `. * .` / `. . X`              | Fixed          | Right corners missing                                   |
+| 9       | `X . .` / `. * .` / `. . X`              | Fixed          | Top Left and Bottom Right diagonal corners missing      |
+| 10      | `. . X` / `. * .` / `X . .`              | Fixed          | Top Right and Bottom Left diagonal corners missing      |
+| 11      | `X . X` / `. * .` / `X . .`              | Fixed          | Top Left, Top Right and Bottom Left corners missing     |
+| 12      | `X . X` / `. * .` / `. . X`              | Fixed          | Top Left, Top Right and Bottom Right corners missing    |
+| 13      | `X . .` / `. * .` / `X . X`              | Fixed          | Top Left, Bottom Left and Bottom Right corners missing  |
+| 14      | `. . X` / `. * .` / `X . X`              | Fixed          | Top Right, Bottom Left and Bottom Right corners missing |
+| 15      | `X . X` / `. * .` / `X . X`              | Fixed          | Cross Section                                           |
+| 16      | `X X X` / `. * .` / `. . .`              | Fixed          | Flat edge (Bottom)                                      |
+| 17      | `. . .` / `. * .` / `X X X`              | Fixed          | Flat edge (Top)                                         |
+| 18      | `. . X` / `. * X` / `. . X`              | Fixed          | Flat edge (Left)                                        |
+| 19      | `X . .` / `X * .` / `X . .`              | Fixed          | Flat edge (Right)                                       |
+| 20      | `X X X` / `. * .` / `. . X`              | Fixed          | L-Shape, Point Right                                    |
+| 21      | `. . X` / `. * X` / `X . X`              | Fixed          | L-Shape, Point Bottom                                   |
+| 22      | `X . .` / `. * .` / `X X X`              | Fixed          | L-Shape, Point Left                                     |
+| 23      | `X . X` / `X * .` / `X . .`              | Fixed          | L-Shape, Point Top                                      |
+| 24      | `X X X` / `. * .` / `X . .`              | Fixed          | L-Shape Inverse, Point Left                             |
+| 25      | `X . .` / `X * .` / `X . X`              | Fixed          | L-Shape Inverse, Point Bottom                           |
+| 26      | `. . X` / `. * .` / `X X X`              | Fixed          | L-Shape Inverse, Point Right                            |
+| 27      | `X . X` / `. * X` / `. . X`              | Fixed          | L-Shape Inverse, Point Top                              |
+| 28      | `X X X` / `. * .` / `X . X`              | Fixed          | T-Shape, face down                                      |
+| 29      | `X . X` / `. * .` / `X X X`              | Fixed          | T-Shape, face top                                       |
+| 30      | `X . X` / `. * X` / `X . X`              | Fixed          | T-Shape, face left                                      |
+| 31      | `X . X` / `X * .` / `X . X`              | Fixed          | T-Shape, face right                                     |
+| 32      | `X X X` / `. * .` / `X X X`              | Fixed          | Horizontal bridge                                       |
+| 33      | `X . X` / `X * X` / `X . X`              | Fixed          | Vertical bridge                                         |
+| 34      | `X X X` / `X * .` / `X . .`              | Fixed          | Corner piece, Bottom Right                              |
+| 35      | `X X X` / `. * X` / `. . X`              | Fixed          | Corner piece, Bottom Left                               |
+| 36      | `. . X` / `. * X` / `X X X`              | Fixed          | Corner piece, Top Left                                  |
+| 37      | `X . .` / `X * .` / `X X X`              | Fixed          | Corner piece, Top Right                                 |
+| 38      | `X X X` / `X * .` / `X . X`              | Fixed          | Edge end, Bottom Right                                  |
+| 39      | `X X X` / `. * X` / `X . X`              | Fixed          | Edge end, Bottom Left                                   |
+| 40      | `X . X` / `. * X` / `X X X`              | Fixed          | Edge end, Top Left                                      |
+| 41      | `X . X` / `X * .` / `X X X`              | Fixed          | Edge end, Top Right                                     |
+| 42      | `X X X` / `. * X` / `X X X`              | Fixed          | Single isolated tile, Left                              |
+| 43      | `X X X` / `X * .` / `X X X`              | Fixed          | Single isolated tile, Right                             |
+| 44      | `X . X` / `X * X` / `X X X`              | Fixed          | Single isolated tile, Top                               |
+| 45      | `X X X` / `X * X` / `X . X`              | Fixed          | Single isolated tile, Bottom                            |
+| 46      | `X X X` / `X * X` / `X X X`              | Fixed          | Center                                                  |
+
+#### Usage
+When applying this template to a new texture set, first ensure the texture is sliced into sprites matching these 47 logical configurations. Then, run a script using the description to map the sprites to each rule. Ensure that RuleTile has all 47 TilingRules listed in the template.
+
+### Tiling Rules Template for Rotated Rule Tiles
+
+| Rule ID | Neighbors (Top to Bottom, Left to Right) | Rule Transform | Description                   |
+|:--------|:-----------------------------------------|:---------------|:------------------------------|
+| 0       | `. . .` / `. * .` / `. . .`              | Fixed          | Fully surrounded (inner tile) |
+| 1       | `X . .` / `. * .` / `. . .`              | Rotated        | One corner missing            |
+| 2       | `X . X` / `. * .` / `. . .`              | Rotated        | Two corners missing           |
+| 3       | `X . .` / `. * .` / `. . X`              | Rotated        | Two diagonal corners missing  |
+| 4       | `X . X` / `. * .` / `. . X`              | Rotated        | Three corners missing         |
+| 5       | `X . X` / `. * .` / `X . X`              | Fixed          | Cross Section                 |
+| 6       | `X X X` / `. * .` / `. . .`              | Rotated        | Flat edge                     |
+| 7       | `X X X` / `. * .` / `. . X`              | Rotated        | L-Shape                       |
+| 8       | `X X X` / `. * .` / `X . .`              | Rotated        | L-Shape Inverse               |
+| 9       | `X X X` / `. * .` / `X . X`              | Rotated        | Isolated edge                 |
+| 10      | `X X X` / `. * .` / `X X X`              | Rotated        | Vertical/Horizontal bridge    |
+| 11      | `X X X` / `X * .` / `X . .`              | Rotated        | Corner piece                  |
+| 12      | `X X X` / `X * .` / `X . X`              | Rotated        | Edge end                      |
+| 13      | `X X X` / `. * X` / `X X X`              | Rotated        | Single isolated tile          |
+| 14      | `X X X` / `X * X` / `X X X`              | Fixed          | Center                        |
+
+#### Usage
+When applying this template to a new texture set, first ensure the texture is sliced into sprites matching these 15 logical configurations. Then, run a script using the description to map the sprites to each rule. Ensure that RuleTile has all 15 TilingRules listed in the template.