From 2f736c4c40e4576393b0c16c5d9812f0aba92c78 Mon Sep 17 00:00:00 2001 From: sebastienp Date: Thu, 8 Oct 2026 11:51:01 +0000 Subject: [PATCH] chore: publish 3 skills (create-2d-physics, create-tile-palette-or-rule-tiles, unity-pipeline) --- skills/create-2d-physics/SECURITY.md | 16 ++ skills/create-2d-physics/SKILL.md | 78 ++++++++ .../references/2d-physics-core.md | 142 +++++++++++++ .../references/legacy-2d-physics.md | 28 +++ .../SKILL.md | 12 ++ .../references}/hexagonalruletile.md | 0 .../references/palette-create.md} | 11 +- .../references/ruletile-createempty.md} | 18 +- .../references/ruletile-createfromsegment.md} | 18 +- .../references}/ruletile.md | 0 .../scripts/CreatePaletteTemplate.cs | 0 .../scripts/ManualWorkflowExample.cs | 0 .../scripts/RuleTileGenerator.cs | 0 .../TilemapRuleTileCreateFromSegment.cs | 0 skills/unity-pipeline/SECURITY.md | 17 ++ skills/unity-pipeline/SKILL.md | 188 ++++++++++++++++++ 16 files changed, 498 insertions(+), 30 deletions(-) create mode 100644 skills/create-2d-physics/SECURITY.md create mode 100644 skills/create-2d-physics/SKILL.md create mode 100644 skills/create-2d-physics/references/2d-physics-core.md create mode 100644 skills/create-2d-physics/references/legacy-2d-physics.md create mode 100644 skills/create-tile-palette-or-rule-tiles/SKILL.md rename skills/{tilemap-ruletile-createempty/resources => create-tile-palette-or-rule-tiles/references}/hexagonalruletile.md (100%) rename skills/{tilemap-palette-create/SKILL.md => create-tile-palette-or-rule-tiles/references/palette-create.md} (77%) rename skills/{tilemap-ruletile-createempty/SKILL.md => create-tile-palette-or-rule-tiles/references/ruletile-createempty.md} (60%) rename skills/{tilemap-ruletile-createfromsegment/SKILL.md => create-tile-palette-or-rule-tiles/references/ruletile-createfromsegment.md} (91%) rename skills/{tilemap-ruletile-createempty/resources => create-tile-palette-or-rule-tiles/references}/ruletile.md (100%) rename skills/{tilemap-palette-create => create-tile-palette-or-rule-tiles}/scripts/CreatePaletteTemplate.cs (100%) rename skills/{tilemap-ruletile-createfromsegment => create-tile-palette-or-rule-tiles}/scripts/ManualWorkflowExample.cs (100%) rename skills/{tilemap-ruletile-createfromsegment => create-tile-palette-or-rule-tiles}/scripts/RuleTileGenerator.cs (100%) rename skills/{tilemap-ruletile-createfromsegment => create-tile-palette-or-rule-tiles}/scripts/TilemapRuleTileCreateFromSegment.cs (100%) create mode 100644 skills/unity-pipeline/SECURITY.md create mode 100644 skills/unity-pipeline/SKILL.md diff --git a/skills/create-2d-physics/SECURITY.md b/skills/create-2d-physics/SECURITY.md new file mode 100644 index 0000000..a9f0529 --- /dev/null +++ b/skills/create-2d-physics/SECURITY.md @@ -0,0 +1,16 @@ +# Security notes: create-2d-physics + +This skill has the agent run C# inside the user's open Unity Editor through `unity command eval`. Automated skill scanners flag that 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` | Runs C# in the user's open Editor through `unity command eval` | 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. `eval` sits behind the Pipeline capability gate. No code fetched from a remote source is run. Where a named `unity command` covers a step, the skill uses that instead of `eval`. | + +## Mitigations + +- **Only the user's own Editor.** `unity command eval` talks to the Editor open on this machine. It can't reach another machine or another user's Editor. +- **Capability gate.** `eval` is only available when the project's Pipeline package provides it. +- **No remote code.** The agent runs C# it writes from this skill's own recipes. Nothing downloaded from outside is executed. +- **Named commands first.** When a dedicated `unity command` covers a step, the skill uses it instead of `eval`. diff --git a/skills/create-2d-physics/SKILL.md b/skills/create-2d-physics/SKILL.md new file mode 100644 index 0000000..7aec902 --- /dev/null +++ b/skills/create-2d-physics/SKILL.md @@ -0,0 +1,78 @@ +--- +name: create-2d-physics +description: "Creates and fixes Unity 2D physics in both systems, 2D Physics Core and the legacy Rigidbody 2D system, for any 2D physics question even if neither is named. Not for 3D physics." +allowed-tools: WebFetch, WebSearch +metadata: + version: 0.3.0 + support: "https://unity.com/support-services" +--- + +# Create and fix Unity 2D physics + +Do not weigh 3D physics options. If evidence shows the user means 3D, say so and stop. + +Prefer `WebFetch` over `WebSearch` — faster and lands on the exact reference. Only fetch what you need. Replace `` with the following before fetching: +- **docs.unity.com**: The Unity version, e.g. `6000.7`. Pages are markdown — URLs end in `.md`. +- **Package on docs.unity3d.com**: The package version, e.g. `@1.1`. Check `Packages/manifest.json` if unsure. + +## 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`. The compiler reads using `UnityEngine` and a bare AssetDatabase, Volume, 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 settle-detection they didn't ask for. See [Final step](#final-step). +- Never reflect over types to discover an API — fetch the member page instead. The system probe is the one exception. + +## Step 0: Which physics system + +Unity has two 2D physics systems. They share no code and never interact. Identify which one before writing any physics code — an answer from the wrong system compiles, runs, and does nothing. + +Check the request, scene and existing scripts against the table below. Components are the reliable signal — check scene and existing scripts first. Check the user's request wording too: "add a collider" is component language, "spawn a thousand" is script language. + +| Signal | System | +| --- | --- | +| Physics Pose, Area, Constraint or Simulation components | Core components, 6000.7+ with the package | +| Rigidbody 2D, Collider 2D, Joint 2D, Effector 2D | Legacy | +| `Unity.U2D.Physics` or `UnityEngine.LowLevelPhysics2D` types in script | Core in script | +| `Rigidbody2D`, `Collider2D`, `Physics2D` types | Legacy | +| Both present | Separate simulations. Say so, treat separately | +| No signal | Stop and ask, offering the three routes above | + +Key: +- Legacy = Rigidbody 2D and Collider 2D components. +- Core components = Physics Pose and Physics Area, requiring `com.unity.2d.physics` and Unity 6000.7+. +- Core in script = `Unity.U2D.Physics` API, no package needed. + +If still unsure which systems are installed, run the probe. If the route is still unknown, stop and ask — offer all three routes and never choose for the user: + +Probe: +``` +unity command eval --code 'var r = ""; foreach (var n in new[] { "UnityEngine.Rigidbody2D", "Unity.U2D.Physics.PhysicsWorld", "UnityEngine.LowLevelPhysics2D.PhysicsWorld", "Unity.U2D.Physics.PhysicsPose" }) { var f = false; foreach (var a in System.AppDomain.CurrentDomain.GetAssemblies()) if (a.GetType(n) != null) f = true; r += f + ","; } return r;' +``` +The Probe returns: legacy present, Core as `Unity.U2D.Physics`, Core as `UnityEngine.LowLevelPhysics2D`, Core components present. Core exists if either Core value is true; the true one gives the namespace. `false` rules that route out. + +## System reference + +Once you know the route, read the matching reference before acting: +- [2D Physics Core reference](references/2d-physics-core.md) - components, configuring them, creating bodies in script, ownership, and the full Core topic map. +- [Legacy 2D physics reference](references/legacy-2d-physics.md) - the legacy manual topic map. + +## Worked examples + +Prefer in order: the C# example on the type or member page you are using; existing project scripts (match their style); the sample project at `https://github.com/Unity-Technologies/PhysicsExamples2D`. Check all three before inventing a pattern. + +## Final step + +Do the following checks: + +1. Check the project has zero console errors. Use `console_status` for counts. +2. Stop there unless the user asked you to prove it works or you suspect a specific fault. +3. 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 as they take too much time. + +If a check fails, go back and reread the docs pages in the matching reference to find out what you missed. + +## Final report + +Short checklist: what you changed and why, which physics system you used, anything left for the user to decide or do. diff --git a/skills/create-2d-physics/references/2d-physics-core.md b/skills/create-2d-physics/references/2d-physics-core.md new file mode 100644 index 0000000..62390ad --- /dev/null +++ b/skills/create-2d-physics/references/2d-physics-core.md @@ -0,0 +1,142 @@ +# 2D Physics Core + +- [Step 0](#step-0) — when to read before acting +- [Configuring a component](#configuring-a-component) +- [Creating in script](#creating-in-script) +- [Ownership](#ownership) +- [What you are likely to get wrong](#what-you-are-likely-to-get-wrong) +- [Manual: 2D Physics Core](#manual-2d-physics-core) +- [Scripting reference](#scripting-reference) +- [Package documentation](#package-documentation) + +The engine API is a built-in module — no package needed. The Physics Pose, Area and Constraint **components** come from `com.unity.2d.physics`, requiring 6000.7+. Check `Packages/manifest.json` before suggesting a component; if absent, offer to add it using the `unity-package-management` skill. + +A component is not the physics object. It owns a body, shape or joint — operate on that owned object. Read/write it, apply forces, query it, handle contacts (from a worker thread if needed). See [Physics Pose and Physics Area components](https://docs.unity.com/en-us/engine//manual/unity2d/2d-physics-api/create-objects/pose-and-area.md). + +The components use only the public API, by design, so nothing is component-only — a plain MonoBehaviour driving the engine API always works. Never say a case is unsupported. For many shapes or nested areas, Physics Area Composite already exists. + +Within Core: components for scene-authored objects, script for bulk runtime creation. The modules `com.unity.modules.physics2d` and `com.unity.modules.physicscore2d` are on by default; only matter if stripped. Version sets the namespace, not which system exists — the [Unity 6.5 upgrade guide](https://docs.unity3d.com//Documentation/Manual/UpgradeGuideUnity65.html) covers the rename. Only the components require 6000.7. + +## Step 0 + +Before you go forward with a workflow or diagnosis: + +1. Open and read the documentation page(s) from the [Manual](#manual-2d-physics-core) or [Scripting reference](#scripting-reference) 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. + +Always use versioned URLs — unversioned links resolve to the current release, not the project's version. + +Core script type pages are an exception: the API only changed namespace, so the version only decides whether to write `Unity.U2D.Physics` or `UnityEngine.LowLevelPhysics2D`. Use the project's version when known, otherwise 6000.7. + +Most tasks (apply force or impulse, move a body, read velocity, add a component) need no reading — just do it. + +Exceptions that always require reading first: +- **Setting component values**: fetch the type page per [Configuring a component](#configuring-a-component). +- **Creating a body in script**: read the two pages in [Creating in script](#creating-in-script). +- **Any member you cannot name with confidence**: read one page. Never read more than two pages for a single task. + +## Configuring a component + +Follow these rules for configuring a component: + +- Never write serialized fields — the serialized names differ from public names. Drive everything through public properties and methods via `eval`. +- Definition and geometry are separate: a pose's body settings live in its definition; an area's shape is its geometry. Configure them independently. A change to either needs its apply call before it takes effect — the type page states which one. +- Before configuring any component, fetch its API page and use only members it lists. Read the installed version from `Packages/manifest.json` (major.minor, e.g. `1.1`), then fetch: +`https://docs.unity3d.com/Packages/com.unity.2d.physics@/api/Unity.U2D.Physics..html` + +One page per type covers all members. If a member is missing, treat it as undocumented, not absent. + +## Creating in script + +Before creating a Core body in script, read these two pages and follow their examples. Set `type` on the definition explicitly. + +- `https://docs.unity.com/en-us/engine//script-reference/unity/u2d/physics/physicsbodydefinition.md` +- `https://docs.unity.com/en-us/engine//script-reference/unity/u2d/physics/physicsbody.md` + +Use the project's version, or 6000.7 if unknown. On 6000.3–6000.4 the namespace is `UnityEngine.LowLevelPhysics2D`, e.g. `.../script-reference/unityengine/lowlevelphysics2d/physicsbody.md`. + +Script types — joints, geometry, queries, and everything else — are engine types in the main scripting reference only. Never look for them in the `com.unity.2d.physics` package docs. + +## Ownership + +Core only. Applies to worlds, bodies, shapes, chains and joints. + +Owner-gated calls state it on their page, as [PhysicsBody.Destroy](https://docs.unity.com/en-us/engine//script-reference/unity/u2d/physics/physicsbody/destroy.md) does. The owner key argument defaults to zero (matches objects with no owner); `SetOwner` is different — there, zero creates a new key. A refusal logs a warning rather than throwing. + +Create a key and own what you create. Queries return objects you did not create — deleting one you merely found is the mistake ownership prevents. Script-created objects are yours to destroy; component-created ones need the component removed; the default world is engine-owned and cannot be removed. + +## What you are likely to get wrong + +Core's API is young and was renamed — your recall is unreliable. Legacy's page locations were reorganised — your recall of URLs is stale. Nothing carries over between systems unverified. + +| Your likely assumption | Actually | +| --- | --- | +| Legacy manual pages are flat, like `class-Rigidbody2D.html` | Reorganised under family folders: `2d-physics/rigidbody-2d/`, `2d-physics/collider-2d/` | +| A Core component holds the state, as Rigidbody 2D does | It owns a body, shape or joint. Operate on the owned object | +| The namespace is `UnityEngine.LowLevelPhysics2D` | 6000.4 and earlier. From 6000.5 it is `Unity.U2D.Physics` | +| Box2D v2 naming and semantics apply to Core | It is Box2D v3. Most older forum answers describe v2 | +| Angles are in radians, as Box2D uses | Read the property page. Hinge angles are documented in degrees | +| Core collision layers are a 32-bit mask | 64 layers in Core, 32 in legacy | +| Some behaviour is component-only | None is | +| A user's own component needs wiring to work with Unity's | None. All interaction is engine-side | +| Any handle can be destroyed | Only what you own. See [Ownership](#ownership) | +| You must create a world first | `PhysicsWorld.defaultWorld` exists in an empty scene | +| Debug visuals need gizmos or `Debug.DrawLine` | Core has a physics renderer with automatic and explicit draw calls. Never hand-roll it | +| A method exists because the other system has one like it | Confirm on its own page | +| `bodyType` and `RigidbodyType2D` set body type | Obsolete. Use `type` with `PhysicsBody.BodyType` | +| A newly created body has a known default type | Do not assume — set `.type` explicitly. falls/thrown/bounces → Dynamic; ground/wall/anchor → Static | +| "add a circle/capsule/polygon/segment area" means the dedicated component | Could be that or Primitive with `shapeType` — same shape, two routes. Prefer dedicated when fixed at authoring time; Primitive only if it must switch at runtime. Chain Segment has no dedicated component | + +## Manual: 2D Physics Core + +Base: `https://docs.unity.com/en-us/engine//manual/unity2d/2d-physics-api/`. Pages are `.md`. The landing page is `https://docs.unity.com/en-us/engine//manual/unity2d/2d-physics-api.md` — contents. + +Paths below are relative to the base: +- `introduction.md` — what it is, component-to-object mapping +- `get-started.md` — first scene with components +- `create-objects.md` — Physics Pose and Physics Area components. Children in `create-objects/`: `pose-and-area.md`, `physics-object.md`, `add-sprite.md`, `debug-drawing.md` (Scene view editing, rendering modes) +- `connect-objects.md` — joints. Children in `connect-objects/`: `joints.md`, `create-constraint.md`, `constraint-events.md` +- `properties.md` — definitions, pinned properties, custom data, global settings. Children in `properties/`: `definitions.md`, `pin-properties.md`, `custom-data.md`, `class-physics-core-settings2d.md`, `preferences-window-reference.md` +- `interactions.md` — collisions, contacts, triggers, filtering (queries are `PhysicsWorld` cast/overlap methods in the scripting reference). Children in `interactions/`: `introduction.md`, `collisions-enable.md`, `collision-handle.md` + +Read in full before acting (outside this skill's scope): `worlds.md`, `3d-planes.md`, `multithreading.md`. + +Component reference pages follow a pattern — build them: +- Body: `create-objects/reference-body.md` +- Area: `create-objects/reference-area-.md` (capsule, circle, composite, contour, path, polygon, primitive, segment, sprite) +- Joint: `connect-objects/reference-joint-.md` (distance, fixed, hinge, relative, slider, wheel) +- Constraint: `connect-objects/reference-constraint-ignore.md` +- Simulation: `worlds/reference-simulation-component.md` +- Assets: `worlds/reference-world.md` (Physics Simulation Definition), `worlds/reference-simulation-asset.md` (Physics Simulation World) + +This manual covers components. For joint structs, definitions, geometry, queries, math, events and destruction — use the scripting reference. + +## Scripting reference + +Build the URL — do not search for member pages. Names are lowercase. + +Base: `https://docs.unity.com/en-us/engine//script-reference/` + +| You want | Pattern | Example | +| --- | --- | --- | +| Legacy type in `UnityEngine` | `unityengine/.md` | `unityengine/rigidbody2d.md` | +| Core namespace (lists types) | `unity/u2d/physics.md` | | +| Core type | `unity/u2d/physics/.md` | `unity/u2d/physics/physicsbody.md` | +| Core type, 6000.3–6000.4 | `unityengine/lowlevelphysics2d/.md` | `unityengine/lowlevelphysics2d/physicsbody.md` | +| Method, property, field or nested type | `/.md` | `unity/u2d/physics/physicsbody/createshape.md`, `unity/u2d/physics/physicsbody/linearvelocity.md` | +| A joint in script | Start at `unity/u2d/physics/physicsjoint.md`, then `physicsjoint` and `physicsjointdefinition` | `unity/u2d/physics/physicshingejoint.md` | + +A type page lists members; a method page lists every overload. Units, ranges and defaults are on property pages. A 404 means the name is wrong, or that version's docs aren't published — fetch the type page and read its members, or try an adjacent version. + +For the Core renderer: start at `unity/u2d/physics/physicsworld/renderingmode.md`, `unity/u2d/physics/physicscoresettings2d.md`, and `physicsworld` draw methods: `drawgeometry`, `drawshapeproxy`, `drawqueryresult`, `drawlinestrip`, `drawshapes`. + +## Package documentation + +Package API pages are live only — not local files. Fetch using the version from `Packages/manifest.json`: +`https://docs.unity3d.com/Packages/com.unity.2d.physics@/api/Unity.U2D.Physics..html` + +Package manual pages are local: `/Library/PackageCache/com.unity.2d.physics@*/Documentation~/`. Read only `.md` files in that subfolder. + +The `api/index.html` listing fetches as nothing — go straight to a named type page. diff --git a/skills/create-2d-physics/references/legacy-2d-physics.md b/skills/create-2d-physics/references/legacy-2d-physics.md new file mode 100644 index 0000000..b35a3b7 --- /dev/null +++ b/skills/create-2d-physics/references/legacy-2d-physics.md @@ -0,0 +1,28 @@ +# Legacy 2D physics + +Relative paths in this file resolve to the skill directory — the folder that holds the `SKILL.md` for this skill. + +## Step 0 + +Before you go forward with a workflow or diagnosis: + +1. Open and read the [documentation page(s)](#manual-legacy-2d-physics) 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. + +## Manual: legacy 2D physics + +Base: `https://docs.unity.com/en-us/engine//manual/unity2d/`. Pages are `.md`. + +`2d-physics.md` is the contents page. Landing pages, relative to the base: `2d-physics/rigidbody-2d.md`, `2d-physics/collider-2d.md`, `2d-physics/effectors-2d.md`, `2d-physics/2d-joints.md`, `2d-physics/physics-2d-profiler.md`, plus flat `2d-physics/constant-force-2d-reference.md` and `2d-physics/physics-material-2d-reference.md`. + +Each landing page has a folder of the same name listing its children — follow those rather than guessing leaf names. + +## Scripting reference + +Legacy types live in the main scripting reference as `unityengine/.md`, e.g. `https://docs.unity.com/en-us/engine//script-reference/unityengine/rigidbody2d.md`. See the [Scripting reference](2d-physics-core.md#scripting-reference) table in the Core reference for the full URL pattern, including how it differs from Core types. + +## What you are likely to get wrong + +Legacy's page locations were reorganised — your recall of URLs is stale. Legacy manual pages are not flat like `class-Rigidbody2D.html`; they're reorganised under family folders: `2d-physics/rigidbody-2d/`, `2d-physics/collider-2d/`. Core collision layers use a 64-bit mask; legacy uses 32. diff --git a/skills/create-tile-palette-or-rule-tiles/SKILL.md b/skills/create-tile-palette-or-rule-tiles/SKILL.md new file mode 100644 index 0000000..389d9dc --- /dev/null +++ b/skills/create-tile-palette-or-rule-tiles/SKILL.md @@ -0,0 +1,12 @@ +--- +name: create-tile-palette-or-rule-tiles +description: Create a 2D tile palette from sprites or textures, or make tiles change based on their neighbours. Use for tile palettes or self-connecting tiles, even when the user doesn't name them. +--- + +# Create a tile palette + +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. diff --git a/skills/tilemap-ruletile-createempty/resources/hexagonalruletile.md b/skills/create-tile-palette-or-rule-tiles/references/hexagonalruletile.md similarity index 100% rename from skills/tilemap-ruletile-createempty/resources/hexagonalruletile.md rename to skills/create-tile-palette-or-rule-tiles/references/hexagonalruletile.md diff --git a/skills/tilemap-palette-create/SKILL.md b/skills/create-tile-palette-or-rule-tiles/references/palette-create.md similarity index 77% rename from skills/tilemap-palette-create/SKILL.md rename to skills/create-tile-palette-or-rule-tiles/references/palette-create.md index 0e7452b..d89e0bf 100644 --- a/skills/tilemap-palette-create/SKILL.md +++ b/skills/create-tile-palette-or-rule-tiles/references/palette-create.md @@ -1,12 +1,7 @@ ---- -name: tilemap-palette-create -description: Creates a Tile Palette asset with a rectangular, hexagonal, or isometric Grid layout. Use when the user wants to organize tiles for 2D level design. -required_packages: - com.unity.2d.tilemap: ">=1.0.0" ---- - # Tilemap Palette Creation +Requires package: `com.unity.2d.tilemap` >=1.0.0 + ## Workflow ### Step 1: Parameter Gathering @@ -40,4 +35,4 @@ Ensure that there is a `GridPalette` as a sub-asset of the Tile Palette asset. ## References -Code Template: "scripts/CreatePaletteTemplate.cs" \ No newline at end of file +Code Template: "../scripts/CreatePaletteTemplate.cs" \ No newline at end of file diff --git a/skills/tilemap-ruletile-createempty/SKILL.md b/skills/create-tile-palette-or-rule-tiles/references/ruletile-createempty.md similarity index 60% rename from skills/tilemap-ruletile-createempty/SKILL.md rename to skills/create-tile-palette-or-rule-tiles/references/ruletile-createempty.md index f486ad4..7d9ad39 100644 --- a/skills/tilemap-ruletile-createempty/SKILL.md +++ b/skills/create-tile-palette-or-rule-tiles/references/ruletile-createempty.md @@ -1,17 +1,13 @@ ---- -name: tilemap-ruletile-createempty -description: Creates an empty RuleTile, HexagonalRuleTile, or IsometricRuleTile asset. Use only when the user wants a blank RuleTile and provides no sprites; with sprites or terrain art, use tilemap-ruletile-createfromsegment. -required_packages: - com.unity.2d.tilemap: ">=1.0.0" - com.unity.2d.tilemap.extras: ">=4.0.0" ---- - # Tilemap RuleTile Create Empty +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. If there are Sprites or Spritesheets specified by the user, use the tilemap-ruletile-createfromsegment skill instead. +**WAIT** - Confirm that no Sprites or Spritesheets were specified by the user. This skill is only for empty RuleTiles. 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: @@ -25,10 +21,10 @@ For each TilingRule, ensure the Sprite array has one `null` entry. ## Branching Logic (RuleTile Types) ### Path A: RuleTile -- Use template from `resources/ruletile.md`. +- Use template from [ruletile.md](ruletile.md). ### Path B: HexagonalRuleTile -- Use template from `resources/hexagonalruletile.md`. +- Use template from [hexagonalruletile.md](hexagonalruletile.md). ### Path C: IsometricRuleTile - Create empty rules with appropriate neighbor positions for isometric layout. diff --git a/skills/tilemap-ruletile-createfromsegment/SKILL.md b/skills/create-tile-palette-or-rule-tiles/references/ruletile-createfromsegment.md similarity index 91% rename from skills/tilemap-ruletile-createfromsegment/SKILL.md rename to skills/create-tile-palette-or-rule-tiles/references/ruletile-createfromsegment.md index 85428b2..8dba0b8 100644 --- a/skills/tilemap-ruletile-createfromsegment/SKILL.md +++ b/skills/create-tile-palette-or-rule-tiles/references/ruletile-createfromsegment.md @@ -1,13 +1,9 @@ ---- -name: tilemap-ruletile-createfromsegment -description: Creates RuleTiles from existing terrain or edge sprites so tiles auto-tile while painting, and converts sprite-segment-3x3grid output patterns into TilingRules. Use when the user wants sprites to connect correctly or to define tile neighbor rules, and provides sprites as input. -required_packages: - com.unity.2d.tilemap: ">=1.0.0" - com.unity.2d.tilemap.extras: ">=4.0.0" ---- - # Tilemap RuleTile Create From Segment +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. @@ -125,9 +121,9 @@ 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 | +| [`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 diff --git a/skills/tilemap-ruletile-createempty/resources/ruletile.md b/skills/create-tile-palette-or-rule-tiles/references/ruletile.md similarity index 100% rename from skills/tilemap-ruletile-createempty/resources/ruletile.md rename to skills/create-tile-palette-or-rule-tiles/references/ruletile.md diff --git a/skills/tilemap-palette-create/scripts/CreatePaletteTemplate.cs b/skills/create-tile-palette-or-rule-tiles/scripts/CreatePaletteTemplate.cs similarity index 100% rename from skills/tilemap-palette-create/scripts/CreatePaletteTemplate.cs rename to skills/create-tile-palette-or-rule-tiles/scripts/CreatePaletteTemplate.cs diff --git a/skills/tilemap-ruletile-createfromsegment/scripts/ManualWorkflowExample.cs b/skills/create-tile-palette-or-rule-tiles/scripts/ManualWorkflowExample.cs similarity index 100% rename from skills/tilemap-ruletile-createfromsegment/scripts/ManualWorkflowExample.cs rename to skills/create-tile-palette-or-rule-tiles/scripts/ManualWorkflowExample.cs diff --git a/skills/tilemap-ruletile-createfromsegment/scripts/RuleTileGenerator.cs b/skills/create-tile-palette-or-rule-tiles/scripts/RuleTileGenerator.cs similarity index 100% rename from skills/tilemap-ruletile-createfromsegment/scripts/RuleTileGenerator.cs rename to skills/create-tile-palette-or-rule-tiles/scripts/RuleTileGenerator.cs diff --git a/skills/tilemap-ruletile-createfromsegment/scripts/TilemapRuleTileCreateFromSegment.cs b/skills/create-tile-palette-or-rule-tiles/scripts/TilemapRuleTileCreateFromSegment.cs similarity index 100% rename from skills/tilemap-ruletile-createfromsegment/scripts/TilemapRuleTileCreateFromSegment.cs rename to skills/create-tile-palette-or-rule-tiles/scripts/TilemapRuleTileCreateFromSegment.cs diff --git a/skills/unity-pipeline/SECURITY.md b/skills/unity-pipeline/SECURITY.md new file mode 100644 index 0000000..149651f --- /dev/null +++ b/skills/unity-pipeline/SECURITY.md @@ -0,0 +1,17 @@ +# Security notes: unity-pipeline + +This skill has the agent run C# inside a Unity Editor or development Player the user already has running, through `unity command eval`, `eval_file`, `run_script` and `reload_file`. Automated skill scanners flag that 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` | Runs C# in the user's running Editor or development Player through `unity command eval`, `eval_file`, `run_script` and `reload_file` | It only reaches an instance the user started, with the Pipeline package they installed, so it grants nothing they couldn't do in that Editor themselves. No code fetched from a remote source is run. The skill steers ad-hoc code into versioned project files run with `run_script`, and keeps `eval` for one-liners. | + +## Mitigations + +- **Only the user's own instances.** Commands go to an Editor or development Player the user is running with the Pipeline package installed. Runtime commands need a development build; release Players have no Pipeline server. +- **No remote code.** The agent runs C# it writes for the user's task. Nothing downloaded from outside is executed. +- **Code lives in reviewable files.** Bulk work goes into scripts on disk run with `run_script`, so the user can read and version what ran. `eval` is reserved for short one-liners. +- **Compile-only check.** `run_script --dry_run true` reports diagnostics without loading or running anything. +- **Named commands first.** When a dedicated `unity command` covers a step, the skill uses it instead of running C#. diff --git a/skills/unity-pipeline/SKILL.md b/skills/unity-pipeline/SKILL.md new file mode 100644 index 0000000..44e2bab --- /dev/null +++ b/skills/unity-pipeline/SKILL.md @@ -0,0 +1,188 @@ +--- +name: unity-pipeline +description: Drives a running Unity Editor or dev Player through the unity-pipeline package — recompile, run tests, run C# scripts, method-reload code at runtime and audit the project. Use when an agent must control a live Unity instance or automate its tests. +--- + +# Unity Pipeline (agent control) + +Invoke commands with `unity command [args]`. Run `unity command` with no name to +list what an instance exposes. Two servers exist: **Editor** (`7800-7849`, auto-starts with +the editor) and **Runtime** (`7900-7949`, only in a dev Player build). `unity command --query ` +filters that list by name, description or tag. + +## 1. Install & verify + +```bash +unity pipeline install # install into current project (or --project-path) +unity pipeline list # confirm the editor instance + server are reachable +unity status --until-ready # wait until the editor server is ready +unity command editor_status # confirm the editor server answers +``` + +An Editor that was already open picks up the package only on its next refresh, usually when its +window regains focus. Until then `unity status` reports `STATUS_PIPELINE_LOAD_PENDING`; if that +persists, ask the user to switch to the Unity Editor window, then re-run `unity status --until-ready`. + +## 2. Autonomous edit loop (Editor) + +This is the core agent workflow: keep the editor alive, change code, recompile, test. + +```bash +# 1. Keep the editor ticking even when unfocused/minimized. REQUIRED before headless work — +# Unity otherwise throttles or stalls update/compile when it isn't the active app. +unity command set_autotick --enable true + +# 2. Edit C# source files on disk normally. + +# 3. Recompile (async: triggers a domain reload, then poll until done). +unity command recompile +unity command recompile_status # repeat until "completed" or "up_to_date" +# Tolerate connection errors while the domain reload is in flight — that is expected. +# If recompile_status reports failed=true, read its "errors" array and fix before testing. + +# 4. (Optional) List available tests without running them. +unity command list_tests --mode editor # mode: all | editor | playmode + +# 5. Run tests (filter to keep it fast). +unity command run_tests --mode editor --filter MyFixture.MyTest +``` + +`run_tests` modes: `all` | `editor` | `playmode`. `filter_type`: `testName` | `assembly` | +`category`. For long runs use `--async_tests true` and poll `unity command test_status` +(abort with `unity command cancel_tests`). + +> **Known caveat:** when any selected test *fails*, `run_tests` may surface an opaque +> result instead of the failure details. Re-run a narrower `--filter`, or inspect the +> editor's Test Runner / logs to get the real failure. + +**Reading exit codes.** They separate "rewrite the invocation" from "the Editor failed", which +is the distinction this loop depends on: + +| Exit | Meaning | What to do | +|------|---------|------------| +| `2` | Bad arguments — a misspelled flag, a wrong type, too many positionals. Nothing ran. | Fix the command line and retry. The error names the problem and often suggests the right flag. | +| `6` | The command ran and failed, or no Editor could be reached. | Read the error. If it says no Pipeline instance was found, the Editor isn't reachable: wait with `unity status --until-ready` (or check `unity pipeline list` for Safe Mode), then retry. Otherwise retrying the same invocation will not help. | + +Do not retry an exit 2 unchanged, and do not rewrite a command line on an exit 6. + +## 3. Runtime method reload + +Change gameplay code in a **running** game with no domain reload. The game must be live: +enter Editor Play Mode (`unity command editor_play`) or run a dev Player. The runtime Pipeline driver (enabled via Project Settings > Pipeline > Runtime) auto-discovers tagged methods on `Awake` (no manual +registration). Mono only — Editor Play Mode and Mono desktop dev builds, not IL2CPP. The token +is auto-injected for local requests. + +### `reload_file` + +Edit the method body directly; no separate file, no boilerplate. + +1. **Before entering Play Mode**, tag the method `[MethodReload]` on the MonoBehaviour and recompile. + The reload hook is compiled into the method, so tagging it while the game runs has no effect: + exit Play Mode, recompile, and enter it again. +2. With the game running, edit the method body on disk. +3. Apply (re-run to iterate): + ```bash + unity command reload_file --filename Assets/Spinner.cs + ``` + Add `--pdb` to make it debuggable — emits a portable PDB mapped to your source so breakpoints in + the original file bind (attach the IDE + enable Editor Attaching; compiles unoptimized): + ```bash + unity command reload_file --filename Assets/Spinner.cs --pdb + ``` + +Constraints: `void` instance methods only; **public** members only; debugging requires `--pdb` +(the default emits no symbols). + +`unity command methodreload_status` shows active overrides. `reload_file` options: `--timeout ` +(default 30000), `--assemblyDir ` (persist DLLs instead of in-memory); +`cleanup_methodreload --assemblyDir ` clears old DLLs. + +The CLI consumes `--timeout` itself, in seconds. To pass the package's `--timeout`, put the command's +arguments after `--`: + +```bash +unity command reload_file -- --filename Assets/Spinner.cs --timeout 60000 +``` + +## 4. Bulk construction: `run_script` (the builder pattern) + +For bulk work — creating many objects, wiring fields, generating content — put the code in a +**versioned project script** and run a named static entry point with `run_script`. No domain +reload, no code carried through the protocol; iterating costs an in-memory compile (< ~2s), not +a 15–20s recompile. + +```bash +# 1. Write the builder OUTSIDE Assets/ (so the write triggers no asset import / domain reload), +# e.g. AgentScripts/Build.cs: public static class Build { public static int All() { ... } } +# 2. Run it — relative paths resolve against the project root (the parent of Assets/): +unity command run_script --file AgentScripts/Build.cs --entry Build.All +# 3. Iterate: edit the file, re-run. Useful extras: +unity command run_script --file AgentScripts/Build.cs --dry_run true # compile-only check: diagnostics, nothing loaded or executed +unity command run_script --file AgentScripts/Build.cs --entry Build.All --args '[3, "Green"]' +``` + +Rules of thumb: + +- **Code goes in files on disk via `run_script`; `eval` is for genuinely ad-hoc one-liners.** + Never ship multi-line escaped C# strings through `eval` — write the file, run the entry. +- Compiles see the project's **active editor defines** (`UNITY_EDITOR`, version/platform symbols); + `--defines` appends extra symbols on top. +- Entry points may be `async Task`/`Task` — they are awaited asynchronously (the editor keeps + pumping, so awaits resuming on Unity's context work naturally) and `Task.Result` is returned. + The wait is bounded by `timeout_ms`; on expiry the task keeps running detached. +- Runtime exceptions come back with `file:line` mapped to your source (a source-mapped PDB is + always emitted for executing runs; they compile unoptimized). +- `--mode hotpatch` instead applies `[MethodReload]` in-place method replacements (delegates to + `reload_file`); `entry`/`args`/`dry_run` are rejected there and `references`/`defines` don't apply. + +## 5. Quick C# eval (Editor or dev Player) + +For genuinely ad-hoc one-liners only — anything longer belongs in a file run via `run_script`. +`eval` targets the Editor by default; add `--runtime ` to run it in a dev Player. + +```bash +unity command eval "return 2 + 2;" +unity command eval "return UnityEngine.Time.timeScale;" --runtime MyGame +# Or evaluate a .cs file on disk. Keep it outside Assets/, where Unity would compile it as project source: +unity command eval_file AgentScripts/Scratch.cs +``` + +## 6. Project audit (Editor) + +Static-analysis scan via Project Auditor, producing a CSV of issues to fix. Trigger, poll, read. + +```bash +unity command audit # optional: --categories Code,ProjectSetting --output my.csv +unity command audit_status # repeat until terminal status +``` + +`audit_status` is terminal on `completed` (with `csvPath` + `issueCount`), `failed`, `unavailable`, or +`interrupted` (a domain reload killed the scan — just re-run `audit`). Polling stays responsive while a +Code-category scan compiles assemblies and holds the main thread. One scan at a time: a second `audit` +returns `busy`. There is no cancel — stop polling to abandon a scan. + +CSV columns: `Category, Severity, Areas, Description, RelativePath, Line, DescriptorId, Recommendation` +(diagnostics only, so every row is something to fix; `Recommendation` says how). + +> **Requires Project Auditor plus its rules.** `unavailable` means the Editor has no Project Auditor, +> or it has no analysis rules — in a built-in-module Editor the rules live in the separate +> `com.unity.project-auditor-rules` package (`unity command package_add --identifier +> com.unity.project-auditor-rules --confirm true`). Read the `message` field; the command never reports +> an empty `completed` scan that would look like a clean project. + +## Gotchas + +- **`set_autotick` first.** Without it, recompile and tests can hang while the editor is + unfocused. The package's watchdog relies on the tick loop staying alive. +- **A stuck command may mean a modal dialog is open**, not a hang — a dialog blocks the main + thread until dismissed. If a command runs long, check `unity command editor_status` (answers + instantly even when blocked); `status: "blocked_by_dialog"` means stop retrying and tell the + human what's blocking (its `dialog.title`/`message`/`buttons`) — it can't be clicked over CLI. +- **Method reload needs the game running.** `reload_file` applies to a live + game — enter Editor Play Mode (`unity command editor_play`) first, or run a dev Player. +- **Player-only commands need a dev Player.** `log`, `set_timescale`, `runtime_status`, etc. hit + the Runtime server, which does not run in the Editor. +- **Async commands poll.** `recompile`→`recompile_status`, `run_tests --async_tests`→ + `test_status`. Never assume completion from the trigger call's response. +- **Target a specific instance** when more than one is running: `--project-path ` selects an + Editor, `--runtime ` or `--runtime-path ` selects a dev Player.