Unity

View saved version →

---
name: 2d-pixel-perfect
description: Sets up, diagnoses, and fixes pixel perfect 2D rendering with PixelPerfectCamera in URP or Built-in. Use when a retro-style or pixel art 2D game looks blurry, jittery, or misaligned. Not for HD 2D or high-resolution art.
---

Set up, diagnose, and fix pixel perfect 2D rendering in Unity projects.

---

## ⚠ There Are Two Completely Separate Implementations

Pixel perfect rendering in Unity is **not one system** — it is two separate, incompatible implementations, one per render pipeline. **Always detect the pipeline before writing or diagnosing any code.** 

| | URP | Built-in |
|---|---|---|
| **Component** | `UnityEngine.Rendering.Universal.PixelPerfectCamera` | `UnityEngine.U2D.PixelPerfectCamera` |
| **Package** | Built into URP — no extra install | `com.unity.2d.pixel-perfect` v6.0.0+ |
| **API style** | Enums (`gridSnapping`, `cropFrame`) | Booleans (`pixelSnapping`, `upscaleRT`, `cropFrameX/Y`) |

**Do not install `com.unity.2d.pixel-perfect` in a URP project.**

**→ Always call `DetectPipeline()` first** (`references/pipeline-detection.cs`), then branch your setup, diagnostics, and fixes based on the result.

---

## When NOT to use this skill

- **HD 2D or high-resolution 2D games** — pixel snapping and point filtering will make smooth art look wrong
- **UI-only scenes** — use Canvas Scaler instead
- **HDRP projects** — Pixel Perfect Camera is not supported

---

## Critical Reminders

⚠ **Detect the render pipeline first** — URP and Built-in use different Pixel Perfect Camera components that are not interchangeable.
⚠ **Filter Mode = Point is the #1 fix** — bilinear filtering is Unity's default and is almost always the cause of blurry sprites.
⚠ **Anti-Aliasing must be disabled** — in Quality Settings and on the camera. AA actively blurs pixel edges.

## Key Principles

### 1. Pipeline Detection & Camera Component Selection

See the two-path comparison table at the top of this file. Assembly name note: the standalone Built-in package installs into a `Runtime/` folder, but the asmdef `"name"` field is `Unity.2D.PixelPerfect` — no `Runtime` suffix. HDRP is unsupported — see the HDRP fallback section under Common Issues.

**→ Code: `references/pipeline-detection.cs`** — `DetectPipeline()`, `GetPixelPerfectCameraType()`, and migration mismatch check.

### 2. Diagnostic-First Approach

Always diagnose before making changes. Report findings, then fix only what is broken.

### 3. Work in the correct scope

Default to scene scope. Scan project-wide only when the user explicitly requests it.

---

## Diagnostic Checklist

**Sprite import settings:**
- [ ] Filter Mode = `Point (no filter)` on all in-scope sprites
- [ ] Mip Maps = disabled
- [ ] Compression = `None` / Uncompressed
- [ ] PPU consistent across all sprites in scene
- [ ] Sprite pivots set to Custom / Pixels mode — a center pivot on an odd-dimension sprite (e.g. 15×15) lands at 7.5px, causing 0.5px misalignment

**→ Code: `references/sprite-settings.cs`** — `GetImporter()` and `FixSpriteImportSettings()`.

**Editor snap settings:**
- [ ] Grid Size = `1 / assetsPPU` on all axes (e.g. PPU 16 → 0.0625, PPU 100 → 0.01)
- [ ] Grid Snapping enabled in the Grid and Snap overlay
- [ ] To snap existing GameObjects: select them → Align Selected → All Axes

**Camera setup:**
- [ ] Camera projection = Orthographic
- [ ] Pixel Perfect Camera component present and correct type for pipeline
- [ ] `allowHDR`, `allowMSAA`, `allowDynamicResolution` all `false`
- [ ] Scene view shows two green bounding boxes on the camera gizmo — solid = visible area, dotted = reference resolution

**→ Code: `references/camera-setup-urp.cs`** — full URP camera + PP Camera configuration.
**→ Code: `references/camera-setup-builtin.cs`** — Built-in standalone configuration.

**Project quality settings:**
- [ ] Anti-Aliasing = 0 in Quality Settings
- [ ] Anisotropic Filtering = Disabled

---

## API Reference

Full property/method tables, `GridSnapping` and `CropFra

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 5 — file references are metadata, not package contents.

View saved version →

---
name: asset-transformer-toolkit
description: >-
  Imports 3D models and point clouds with Asset Transformer Toolkit (formerly Pixyz), and creates,
  edits, and runs RuleSets, Actions, and LODs. Use for Pixyz or Asset Transformer imports, RuleSets,
  or ImporterScriptableObjects. Requires toolkit 4.0+.
required_packages:
    com.unity.industry.toolkit: ">=4.0.0"
---
### Before you start: check the package version
This skill needs Asset Transformer Toolkit 4.0.0 or later (`com.unity.industry.toolkit`). Earlier versions don't have the `ATTAssistantUtilities` API every workflow below relies on.

1. Read the resolved version of `com.unity.industry.toolkit` from `Packages/packages-lock.json` (fall back to `Packages/manifest.json`).
2. **Not installed:** tell the user this workflow needs Asset Transformer Toolkit 4.0 or later, which is an entitled Unity package they may need access to through their Unity plan, and stop. Don't add it to the manifest yourself.
3. **Installed below 4.0.0:** tell the user which version you found and that 4.0 or later is required, and ask before upgrading. Don't fall back to older APIs, raw C# against internal types, or reflection.
4. **4.0.0 or later:** continue.

### API Reference
Tool functions are provided by `Unity.Pixyz.Plugin4Unity.Editor.AI.ATTAssistantUtilities`. They are documented inline in each reference file below alongside the classes they operate on.

### Technical Notes
Pixyz Plugin is the former name of Asset Transformer Toolkit. Prefer using the term 'Asset Transformer Toolkit' when addressing the user, unless the user is using the term 'Pixyz'
Most classes and code are in the Unity.Pixyz.Plugin4Unity.Editor assembly.
Asset Transformer Toolkit is NOT the same thing as Asset Transformer Studio/Pixyz Studio. NEVER rely on information about Asset Transformer Studio.

### Importers
Asset Transformer Toolkit can import 3D file from outside the project.
When modifying Importers, NEVER assume it should be immediately followed by a reimport. The import process can be very long, so it must only be launched when the user requests it.
Modify fields in Importers using the ScriptableObject API. NEVER use reflection to access or modify Importer fields — reflection is not available.
To create a Pixyz/Asset Transformer Toolkit Importer for importing a file, or to reimport a model using an existing ImporterScriptableObject, read [references/create-importer](references/create-importer.md)

### RuleSets and Actions
Read [references/rulesets-and-actions](references/rulesets-and-actions.md)
Read [api-docs/ruleset-api](api-docs/ruleset-api.md) when the RuleSet API is needed.
Read [api-docs/rule-api](api-docs/rule-api.md) when the Rule API is needed.
Read [api-docs/ruleblock-api](api-docs/ruleblock-api.md) when the RuleBlock API is needed, including `ActionBase.Id` for constructing `RuleBlock` instances.

### Levels of Detail
Read [references/lods](references/lods.md)

Referenced files: 7 — file references are metadata, not package contents.

View saved version →

---
name: audio-setup-mixers
description: Routes Audio Sources into existing Audio Mixer Groups, classifying each source by what it plays. Use when the user asks about cleaning up mixer assignments, routing audio through a mixer, or which group a sound belongs in.
---
# Audio Mixer Setup

Routing an Audio Source to a mixer group is a scene edit that only a running Editor can
make, so this skill needs a live Editor it can execute C# in. Step 0 establishes that
before anything else.

**What this skill automates, and what it hands back to you.** Inspecting mixers and
routing Audio Sources into groups is entirely public Unity API, and that is the tedious
part — walking dozens of sources and classifying them by what they play. Creating a mixer
or a group has no public API; it exists only on types Unity does not commit to keeping
stable. So this skill will not create groups behind your back. It inventories what exists,
proposes the routing, asks you to add any missing group in the Audio Mixer window, and
then does all the routing itself.

That is a deliberate limit, not a gap to work around. Do not reach for reflection to
create groups, and do not hand-edit a `.mixer` file — mixer structure is not safely
authorable blind.

## Step 0: Confirm you can run C# in the Editor

Every C# step below runs inside a live Editor through the Unity CLI. **The `unity-cli` skill
owns getting you there** — installing the CLI, confirming a connected Editor, adding the
project's `com.unity.pipeline` package, telling a genuinely absent Editor apart from one
stuck in Safe Mode, and discovering the Editor's command catalog. Follow it first; don't
re-derive any of it here.

Two things it can't know for you:

- **You need `eval` in particular**, not just a reachable Editor. Confirm it appears in the
  catalog. Its presence depends on the Pipeline package version, not on the CLI, so a
  healthy install can still lack it — if it's missing, say so and stop.
- **Do not fall back to editing `.mixer` files by hand.** Mixer routing is not safely
  authorable blind, so an unreachable Editor is a stop, not a cue to improvise.

Once `eval` is available, that is how each C# step below runs.

Run C# through the connected Editor with the `eval` command. Discover its parameter shape
from `unity command --format json` rather than assuming one — the inline form is
`unity command eval --caller plugin --skill audio-setup-mixers --code '<snippet>'`, and some Pipeline versions also register
`eval_file` for running a snippet from a file. **Check the catalog before reaching for
`eval_file`; it is frequently absent.** `unity command` defaults to a 30 second timeout.

### Passing C# to `eval`

`eval` compiles a **statement block, not a file**. Two consequences, both of which cause a
compile error rather than a warning:

- **No `using` directives.** The compiler reads `using UnityEngine;` as a resource-disposal
  statement and rejects it (`CS0210`).
- **Types must be fully qualified.** A bare `AssetDatabase` or `Volume` does not resolve
  (`CS0246` / `CS0103`), and a bare `Object` is ambiguous with `object` (`CS0104`).

Where a snippet below is written as a file — with usings, for readability, or because it is
meant to be saved into the project — qualify the types before passing it to `eval`.

## Step 1: Pre-flight
If the user hasn't explicitly asked for Audio Mixers, confirm that they want to proceed with setting them up.

Then inventory what already exists with the mixer-inventory snippet in
[references/api.md](references/api.md), run through the Editor as described in Step 0. That gives
you every mixer in the project and the group names in each.

It returns a flat list of groups, not the parent/child tree. That is enough to route into, and it
is all the public API exposes. If the hierarchy matters for the conversation, ask the user to look
at the Audio Mixer window and describe it — don't reach for the non-public tree API to find out.

**If the project has no mixer at all,** say

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: build-gtk
description: >-
  Builds node-based Editor tools with Unity Graph Toolkit (GTK) on Unity 6.6+: graphs, nodes, ports
  and validation, State Machine API tools on 6.7+, and runtime assets via a scripted importer. Use for
  custom graph, node or state machine editors, or migrating a GraphView tool. Not for Shader Graph, VFX
  Graph or Animator Controllers.
required_editor_version: ">=6000.6"
---

# Unity Graph Toolkit (GTK)

Build Editor graph tools and state machine tools on Unity's Graph Toolkit module, using only its
public API in the `Unity.GraphToolkit.Editor` namespace.

## Important

- 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.
- Before you go forward with a workflow or diagnosis, open and read the reference file(s) named in
  that workflow and the [Topic map](#topic-map) page(s) that cover the thing you intend to do. 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, and Graph Toolkit changed between 6000.4,
  6000.6 and 6000.7.

## References

Read these as needed. Paths are relative to this skill's folder.

- `references/graph-api.md` — the Graph API surface: Graph, Node, port and option builders, context
  and block nodes, subgraphs, variables, validation, toolbar and context menus. Read before writing any
  graph-tool code.
- `references/state-machine-api.md` — the State Machine API (Unity 6.7+): StateMachine, State,
  Condition, transitions and rules, self transitions, custom views. Read whenever states, transitions
  or conditions are involved.
- `references/runtime-and-visualization.md` — compiling a graph or state machine into a runtime asset
  with a ScriptedImporter, and showing live execution in the graph editor. Read when the user wants the
  authored data used in the game or debugged at runtime.
- `references/pitfalls.md` — the mistakes that survive compilation. Read before handing off, and
  whenever the user reports a compile error, an empty Add menu, a missing node, or an exception.

## Step 1: Check the Editor version and pick the API

Read `m_EditorVersion` in `ProjectSettings/ProjectVersion.txt` before writing code. Graph Toolkit is
an Editor module, so there is no package to install. `com.unity.graphtoolkit` is a deprecated shim
and must not be added to the manifest.

| Editor version | What is available |
|---|---|
| Older than 6000.4 | Only the retired experimental package (0.x). Its API differs from this skill. Recommend upgrading. |
| 6000.4 to 6000.5 | Module present, but without port capacity, type casting, wire and node visualization, USS node styling, or element IDs. |
| 6000.6 | The Graph API this skill documents. |
| 6000.7 and newer | Everything above plus the State Machine API, `NodeView<T>` / `StateView<T>` / `ConditionView<T>` custom UI, `[GraphMenu]` / `[BlackboardMenu]` context menus, the `GraphLogger.GraphChanges` change delta, port type-following, and Blackboard type restriction. Members marked **6.7** in the references. |

If the user asks for a state machine tool on an Editor older than 6000.7, say plainly that the
State Machine API is not available there. Do not emulate it with the Graph API unless asked.

## Mental model

- Graph Toolkit is an authoring framework only. It draws and persists graphs; it never executes them.
  The user writes the runtime data model and the code that runs it, usually fed by a ScriptedImporter.
- One asset type per `Graph` or `StateMachine` subclass, identified by the file extension passed to
  `[Graph("ext")]` or `[StateMachine("ext")]`.
- Discovery is by reflection. Node, state and condition classes in the same assembly as the graph
  class are listed automatically. Classes in other assemblies opt in with `[UseWithGraph]` or
  `[UseWithStateMachine]`. Abstract classes are never listed.
- Every authoring class

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 4 — file references are metadata, not package contents.

View saved version →

---
name: build-live-game
description: Builds and operates live games with Unity Services. Use when the user asks about backend or live-ops features such as player accounts, cloud save, leaderboards, achievements, progression and battle passes, economies, cloud code, or remote config.
---

# Build a Live Game With Unity Gaming Services

## UGS Packages

| Package | Min Version | Purpose |
|---|---|---|
| `com.unity.services.core` | 1.16.0 | Initialization, dependency graph |
| `com.unity.services.authentication` | 3.6.1 | Player sign-in and identity |
| `com.unity.services.cloudcode` | 2.10.3 | Server-authoritative C# modules |
| `com.unity.services.cloudsave` | 3.4.0 | Per-player and shared key-value storage |
| `com.unity.remote-config` | 4.2.5 | Server-side game configuration |
| `com.unity.services.deployment` | 1.7.2 | Deploy cloud resources from Editor |
| `com.unity.services.tooling` | 1.4.1 | Access Control and Game Overrides |
| `com.unity.services.apis` | 1.1.1 | Generated REST clients for all UGS services |

- [Initialization Pattern](#initialization-pattern)
- [Package Map](#package-map)
- [Architecture — How Packages Combine](#architecture--how-packages-combine)
- [Core Services — Quick Reference](#core-services--quick-reference)
- [Asset Store Building Blocks](#asset-store-building-blocks)
- [Ready-Made Feature Blueprints](#ready-made-feature-blueprints)
- [Common Architecture Patterns](#common-architecture-patterns)
- [Validation](#validation)
- [Deployment Checklist](#deployment-checklist)
- [Detailed References](#detailed-references)

## Initialization Pattern

Every UGS game starts the same way. `com.unity.services.core` must initialize first, then the player signs in:

```csharp
using Unity.Services.Core;
using Unity.Services.Authentication;

await UnityServices.InitializeAsync();
await AuthenticationService.Instance.SignInAnonymouslyAsync();
// All other services are now ready
```

After `InitializeAsync()` completes, service singletons (e.g. `CloudSaveService.Instance`, `CloudCodeService.Instance`) are available.

## Package Map

### Foundation

| Package | Purpose | Singleton / Entry Point |
|---|---|---|
| **Core** | Initialization, dependency graph, component registry | `UnityServices.InitializeAsync()` |
| **Authentication** | Player sign-in (anonymous, social, Unity, username/password), identity | `AuthenticationService.Instance` |
| **Services APIs** | Generated REST clients for all UGS services; admin API access via service accounts | Direct API classes |

### Player Data and Configuration

| Package | Purpose | Singleton / Entry Point |
|---|---|---|
| **Cloud Save** | Per-player key-value data (Default, Public, Protected) and game-wide Custom data | `CloudSaveService.Instance.Data.Player` / `.Data.Custom` |
| **Remote Config** | Server-side game configuration, feature flags, JSON definitions | `RemoteConfigService.Instance` |
| **Economy** | Virtual currencies, inventory items, purchases, stores | `EconomyService.Instance` |

### Server Logic and Security

| Package | Purpose | Singleton / Entry Point |
|---|---|---|
| **Cloud Code** | Server-authoritative C# modules for trusted writes and validation | `CloudCodeService.Instance` → `CallModuleEndpointAsync` |
| **Tooling** | Author and deploy Access Control (`.ac`) and Game Overrides (`.ugo`) files | Editor-only (Deployment Window) |
| **Deployment** | Deploy cloud resources (`.rc`, `.ac`, `.ccmr`, `.lb`, etc.) from the Unity Editor | Editor-only (Services > Deployment) |

### Social and Competitive

| Package | Purpose | Singleton / Entry Point |
|---|---|---|
| **Multiplayer** | Sessions, matchmaking, lobbies. Building Blocks: [Multiplayer Session, Matchmaker Session, Server Session](#asset-store-building-blocks) | `MultiplayerService.Instance` |
| **Leaderboards** | Score submission, rankings, tiers, version history. Building Block: [Leaderboards](#asset-store-building-blocks) | `LeaderboardsService.Instance` |

### Telemetry

| Package | Purpo

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 10 — file references are metadata, not package contents.

View saved version →

---
name: generate-editor-search-query
description: Generates Unity Search queries and opens the Search window to find assets or scene objects. Use when the user asks to find, filter, or list assets, GameObjects, components, or references in the Editor, not on disk.
enabled: true
modes: [agent, ask]
---

Translate natural-language Unity Editor search requests into useful Unity Search queries, explain them briefly, and open the Unity Search window with the query when appropriate.

## Default Behavior

If the prompt explicitly says Unity Search, Quick Search, Search window, open Search, or asks for a Unity Search query, handle the search request with this skill even when the target belongs to another domain such as lighting, UI, physics, audio, or animation.

For requests such as "find", "search", "locate", "list", "filter", "look up", "where is", "which assets use", or "what references" concrete Unity assets or scene objects:

1. Determine whether the request is primarily about project assets, scene objects, or both.
2. Build one concise Unity Search query.
3. Show the query in the response before or while opening Search.
4. Open Unity Search by running the Editor-side snippet unless the user explicitly asks for query text only.
5. If opening Search fails, return the query and tell the user to paste it into Unity Search manually.

Do not open Search when the user says "do not open Search", "query only", "what query should I use", "just give me the query", or similar.

If the user asks for a general explanation, project overview, folder-structure summary, architecture walkthrough, gameplay-system summary, or "how do I" programming answer, do not use this skill unless the prompt explicitly asks for Unity Search, a Search query, or opening the Search window.

If the user refers to "this", "selected", or "current" without an attached asset, scene object, visible name, or path, ask for the name/path instead of inventing one.

## Scope

Scope read-only Unity Search / Quick Search queries to:

- project assets such as materials, textures, prefabs, scenes, scripts, shaders, audio clips, sprites, meshes, models, animations, fonts, render textures, and ScriptableObject assets
- scene objects and components such as Cameras, Lights, Rigidbodies, Colliders, Renderers, Canvas objects, UI components, ParticleSystems, AudioSources, Animators, Terrain objects, and named GameObjects
- path, label, type, filename, keyword, and reference-oriented asset searches
- selected or named assets when the name/path is available from the conversation or attachment

Do not install packages, run menu commands, edit assets, modify scenes, search external documentation, search repository text, inspect build logs, delete results, fix search results, or perform dependency graph analysis. If the user asks to act on results, first open Search or provide the query, then ask for confirmation before any separate modifying skill or workflow.

## References

Before generating non-trivial queries, read [references/query-patterns.md](references/query-patterns.md).

Before opening the Search window, read [references/open-search-window.md](references/open-search-window.md).

Official English references:

- [Unity Search](https://docs.unity3d.com/Manual/search-overview.html)
- [Search expressions](https://docs.unity3d.com/Manual/search-expressions.html)
- [SearchService.ShowWindow](https://docs.unity3d.com/6000.0/Documentation/ScriptReference/Search.SearchService.ShowWindow.html)

## Passing C# to `eval`

`eval` compiles a **statement block, not a file**. Two consequences, both compile errors:

- **No `using` directives.** The compiler reads `using UnityEditor;` as a resource-disposal
  statement and rejects it (`CS0210`).
- **Types must be fully qualified.** A bare `SearchService` does not resolve (`CS0246`), and a
  bare `Object` is ambiguous with `object` (`CS0104`).

The `unity-cli` skill owns the prerequisites — installing the CLI, confirming a connected Editor,
adding 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
name: implement-in-app-purchases
description: Implements, configures, and debugs Unity In-App Purchases, including subscriptions, receipt validation, and direct-to-customer payments via Stripe or Coda. Use when asked about real-money purchases or microtransactions, or migrating from native store billing, RevenueCat, Adapty, Essential Kit, or UniPay.
---

# Unity In-App Purchasing

Namespace: `UnityEngine.Purchasing` | Security: `UnityEngine.Purchasing.Security`
Package: `com.unity.purchasing`

**Unity IAP has its own initialization path** via `UnityIAPServices.StoreController()` → `store.Connect()`. It does not require `UnityServices.InitializeAsync()`, but they can coexist if your project uses other UGS services. If Analytics is present and `InitializeAsync()` is called, IAP will automatically send transaction events.

## Before You Start

**Always read [references/pre-check.md](references/pre-check.md) first.** It scans the project for third-party IAP packages, native Google Billing, and existing Unity IAP versions, then routes to the correct path. Do not read any other reference file or make any changes until routing is resolved.

## Detailed References

- **Project scan and path routing (read first):** See [references/pre-check.md](references/pre-check.md)
- **API signatures & code examples:** See [references/api-notes.md](references/api-notes.md)
- **Platform extensions (Apple, Google):** See [references/platform-notes.md](references/platform-notes.md)
- **Editing `IAPProductCatalog.json` (schema, decimal serialization, refresh):** See [references/codeless-catalog.md](references/codeless-catalog.md)
- **v4 → v5 migration:** See [references/migration-v4-to-v5.md](references/migration-v4-to-v5.md)
- **Convert native Google BillingClient to Unity IAP 5:** See [references/path-convert-native-google-billing.md](references/path-convert-native-google-billing.md)
- **Convert native iOS StoreKit plugin to Unity IAP 5:** See [references/path-convert-native-storekit.md](references/path-convert-native-storekit.md)
- **Convert Essential Kit billing to Unity IAP 5:** See [references/convert-essentialkit.md](references/convert-essentialkit.md)
- **UniPay (FLOBUK) — assessment and guidance:** See [references/convert-unipay.md](references/convert-unipay.md)
- **RevenueCat — conversion assessment and guidance:** See [references/convert-revenuecat.md](references/convert-revenuecat.md)
- **Adapty — conversion assessment and guidance:** See [references/convert-adapty.md](references/convert-adapty.md)
- **Add Unity IAP 5 to a project with no existing IAP:** See [references/path-add-iap-to-new-project.md](references/path-add-iap-to-new-project.md)
- **Implement IAP D2C Capabilities (third-party payment provider — Stripe/Coda, requires v5.4+):** See [references/path-implement-iap-d2c.md](references/path-implement-iap-d2c.md)

Read reference files on demand — only when you need specific API signatures, platform extension details, or migration mappings.

## Initialization Flow

1. Obtain `StoreController` via `UnityIAPServices.StoreController()` (or individual services via `DefaultStore()`, `DefaultProduct()`, `DefaultPurchase()`)
2. Subscribe to **all** required events (see Required Event Subscriptions below) **before** calling `Connect()`
3. `await store.Connect()` to connect to the platform store
4. On `OnStoreConnected`, call `store.FetchProducts(List<ProductDefinition>)` to load the catalog
5. On `OnProductsFetched`, products are ready for display and purchase

Use `Awake()` for initialization — ensures IAP is ready before other `Start()` methods.

Product types: `ProductType.Consumable`, `ProductType.NonConsumable`, `ProductType.Subscription`.

## Fetching Products

Define products as `List<ProductDefinition>` and pass to `store.FetchProducts()`. Use `StoreSpecificIds` when product IDs differ across Apple/Google stores. For complex catalogs, use `CatalogProvider` to manage product sets and store-specific IDs.

| Method | Behavior |
|---|

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 13 — file references are metadata, not package contents.

View saved version →

---
name: initialize-ai-navigation
description: Sets up and configures Unity AI Navigation, including NavMesh surfaces, agents, obstacles, and links. Use when the user asks about navigation meshes, pathfinding, patrol routes, or obstacle avoidance.
---

Determine what the user needs and guide them through navigation setup. See [navigation-system.md](references/navigation-system.md) for expanded component details, API notes, code recipes, and troubleshooting.

### Passing C# to `eval`

`eval` compiles a **statement block, not a file**. Two consequences, both of which cause a
compile error rather than a warning:

- **No `using` directives.** The compiler reads `using UnityEngine;` as a resource-disposal
  statement and rejects it (`CS0210`).
- **Types must be fully qualified.** A bare `AssetDatabase` or `Volume` does not resolve
  (`CS0246` / `CS0103`), and a bare `Object` is ambiguous with `object` (`CS0104`).

Where a snippet below is written as a file — with usings, for readability, or because it is
meant to be saved into the project — qualify the types before passing it to `eval`.

## Routing Logic

| User Says | Interpretation |
|-----------|---------------|
| "add navigation" / "set up nav" | Full setup: NavMeshSurface + bake + NavMeshAgent |
| "make this character navigate" | Add NavMeshAgent, ensure NavMesh exists |
| "add pathfinding" | NavMeshAgent + movement script |
| "agent won't move" / "path not found" | Troubleshoot — see Troubleshooting Decision Tree in reference |
| "avoid obstacles" | NavMeshObstacle with carving or avoidance |
| "connect two areas" / "jump across" | NavMeshLink between areas |
| "patrol between points" | NavMeshAgent + patrol script |
| "click to move" | NavMeshAgent + raycast click-to-move script |
| "animate the character while navigating" | Couple Animator with NavMeshAgent |
| "different agent sizes" | Configure agent types in Navigation window |
| "areas and costs" / "restrict areas" | NavMesh area types, modifiers, and agent area masks |

## Workflow

### 0. Package Installation Check
Before doing anything else, verify that `com.unity.ai.navigation` is installed. If it's missing,
add it to `Packages/manifest.json` under `dependencies` — Unity resolves it when the Editor next
regains focus, and this needs no Editor connection:

```json
"com.unity.ai.navigation": "<current 2.x version>"
```

Don't invent the version string. Read the current one from the Unity registry —
`https://packages.unity.com/com.unity.ai.navigation` lists every published version — or copy the version an
adjacent Unity package in this manifest already uses. A version that doesn't exist makes
Unity fail resolution **silently**, so a wrong guess looks like nothing happened.

Proceed only once it's confirmed installed. If you have a live Editor to run C# in, see
[navigation-system.md](references/navigation-system.md) for the `Client.Add` equivalent.

### 1. Pre-Flight: Assess Current Navigation Setup
Before making changes, inspect what already exists:
1. Find the existing navigation components. With a connected Editor, query the live scene for
   `NavMeshSurface`, `NavMeshAgent`, `NavMeshObstacle`, `NavMeshLink` and `NavMeshModifier` — see
   the `unity-cli` skill for driving a running Editor. Without one, search the scene and prefab
   files for those component names.
2. Check configured agent types via **Window > AI > Navigation > Agents tab**.
3. Summarize ALL detected navigation components before proposing changes.

### 2. Gather Missing Information
Before creating components, ensure the user has specified: walkable surfaces, agent type/size, agent behavior, obstacles, links, and area/cost requirements. Ask if anything is unclear. See the Information Gathering Checklist in the reference for full details.

### 3. Planning & Execution
Follow this general order. See the Component Setup Guide in the reference for detailed step-by-step instructions per component:
1. **NavMesh Surface** — create the walkable mesh (bake it

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: levelplay-unity-integration
description: Integrates the LevelPlay ad mediation SDK via the Ads Mediation package. Use when the user asks about adding rewarded, interstitial, or banner ads, mediation or ad privacy setup, Android or iOS ad dependency build failures, or migrating from Unity Ads or IronSource APIs.
---

# LevelPlay Unity package/SDK Integration

Base editor-side checks on the actual project rather than assumptions — read the project files, or ask the user to confirm in the Editor. The C# scripts generated in this skill are MonoBehaviour files for the user to save to their project, not for inline execution.

This skill covers the LevelPlay integration path only; it does not cover other mediation SDKs. If the user explicitly asks about alternatives, acknowledge that alternatives exist and point them to those vendors' own documentation — do not describe, characterize, or make claims about competitor products.

Follow the steps and provide only the files and configurations described in this skill. Do not proactively add steps, create files, or make recommendations based on general knowledge. If the user asks a question outside the scope of this skill, check the skill and reference files first to confirm it is not covered. If it is not, use general knowledge to respond, but do not incorporate additional steps or files into the integration workflow as a result.

Follow the integration workflow sequentially, one step at a time. Ask only the questions for the current step — do not gather information for future steps in advance. Wait for the user's response at each checkpoint before proceeding.

LevelPlay is Unity's ad mediation platform: it connects your game to multiple ad networks simultaneously and runs a unified auction across multiple ad networks and bidders to maximize competition for each impression. This guide walks you through the full integration: installing the SDK, configuring dependencies for Android and iOS, initializing LevelPlay in your project, and implementing rewarded, interstitial, and banner ads. If you already have part of this set up, you can skip ahead to the relevant step.

**This SKILL.md is the workflow spine. It keeps the decisions, checkpoints, and exact questions; longer code, full API detail, and edge cases live in `references/` and are linked from the relevant step. Read the linked reference when you reach that step — do not answer from general knowledge instead.**

## Integration Workflow

### 0. New Integration or Migration?

Ask: "Are you starting a new LevelPlay integration, migrating an existing one (from an older SDK version or from Unity Ads), or troubleshooting an existing setup?"

- **New integration**: proceed to Step 1.
- **Migration** (SDK upgrade, replacing IronSource.Agent APIs, migrating from Unity Ads, or fixing a Maven Central Android build failure): Read `references/migration-sdk-9.md`. Ask which of the five scenarios applies — A = SDK upgrade, B = init API migration, C = ad unit API migration, D = Maven Central build failure, E = Unity Ads migration — then follow the matching scenario. After applying all code changes, work through the Migration Completeness Checklist (section C5 of the reference) — it catches requirements that a line-by-line translation misses because the legacy code had no equivalent line. Then ask the user to check the Unity console for compilation errors, and fix any that appear before presenting results. Do not block or keep retrying if you cannot see the console: list the files you changed, say what to look for, and continue.
- **Troubleshooting or adding to an existing setup** (ATT, GDPR, ILRD, Test Suite, build errors on a fresh integration, or adding a feature to an already-working integration): Identify what the user needs and go directly to the relevant step or reference from "When to Read Detailed References."

### 1. Verify Unity Environment

Check that the user is working in a Unity project by verifying Assets/ and ProjectSettings/ 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 12 — file references are metadata, not package contents.

View saved version →

---
name: localization
description: Sets up and configures Unity Localization, including locales, String and Asset Tables, and CJK fonts. Use when the user asks to add languages, translate UI text, or mentions i18n or multilingual support.
---

This guide covers setting up and configuring Unity Localization, including locales, String and Asset Tables, Addressables integration, and CJK font support via Asset Tables.

## 0. Package Installation Check
Before doing anything else, verify that the Localization package is installed. Many APIs in this skill
will fail silently or throw confusing errors if the package isn't present.

1. **Check by reading the project, not by asking the Package Manager.** Look for
   `com.unity.localization` in **`Packages/packages-lock.json`**. That file records what Unity
   actually resolved, it is plain JSON, and reading it needs no Editor and no async call.
   (`Packages/manifest.json` only records what was *requested*, so check the lock file.)
2. **Install if missing:** `UnityEditor.PackageManager.Client.Add("com.unity.localization")`.
3. **Wait properly.** `Client.Add` and `Client.List` are **asynchronous**: they return a request that
   is still `InProgress` when the call returns, so reading the result in the same statement tells you
   nothing. Do not busy-wait on `IsCompleted` either; that blocks the main thread you are running on.
   Instead, return after firing the install, then **poll `packages-lock.json` in a later call** until
   the id appears. Installation also triggers a domain reload, so expect the first poll or two to
   fail; a fresh install typically resolves in a few seconds.
4. **Confirm the types are actually loaded** before using them, since the lock file can be written
   before the assemblies are ready:
   ```csharp
   var t = System.Type.GetType(
       "UnityEngine.Localization.Settings.LocalizationSettings, Unity.Localization");
   return t != null ? "ready" : "not loaded yet";
   ```
   Only proceed once that returns `ready`.

## 1. Localization Settings & Locales
If `LocalizationEditorSettings.ActiveLocalizationSettings` is null, you must find or create it:
1. **Find:** Use `AssetDatabase.FindAssets("t:LocalizationSettings", new[] { "Assets" })`. If found, load the first one and assign it to `LocalizationEditorSettings.ActiveLocalizationSettings`.
   - **Always pass the search folders.** An unscoped `FindAssets` searches the whole project including
     read-only packages, so it can return an asset from a package and you end up pointing the project
     at something you cannot edit. This applies to every `FindAssets` call in this skill.
2. **Create:** If not found, create a new instance and save it to `Assets/Localization/LocalizationSettings.asset`. Use `ScriptableObject.CreateInstance<LocalizationSettings>()` followed by `AssetDatabase.CreateAsset()`.
3. **Activate:** Set `LocalizationEditorSettings.ActiveLocalizationSettings = settings`.
4. **Locales:** Ensure locales (en, fr, de, etc.) exist. Create them if missing and add them to settings using `LocalizationEditorSettings.AddLocale(locale)`.

## 2. Modifying Localization Tables
Programmatic changes to String or Asset tables require notification to the Editor.
Always create the required asset tables, unless there is already an existing one in the project.

### **Safe Population Pattern**
When populating tables from a dataset, match by `Locale.Identifier.Code` explicitly. The order of `GetLocales()` is not guaranteed to match your input data array — assuming it does will cause silent data mismatches that are very hard to debug.
For **Asset Tables**, use the GUID of the asset: `table.GetEntry(sharedId) ?? table.AddEntry(sharedId, guid);`.

### **Refresh & Notification**
After any modification (adding keys, updating values), notify the Editor so it can refresh its internal state. Skipping this will leave the Editor showing stale data until the next reimport.
1. Call `EditorUtility.SetDirty(collection)`, `EditorUtility.Se

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
name: manage-sprite-atlas
description: Manages SpriteAtlas assets through a prebuild pipeline, covering master and variant atlases, packing settings, and platform overrides. Use when asked to create or optimize sprite atlases.
---

# Unity SpriteAtlas V2

Provides *editor-safe* procedural knowledge for scripting atlases in Unity projects. **V2 enforces strict separation between editor authoring and runtime access.**

> ⚠ **Critical V2 Principle**: `SpriteAtlas` is **runtime-only**. `SpriteAtlasAsset` is **editor-only**. Never mix contexts. Always use V2.

## 🚨 CRITICAL: Required Checks and User Inputs Before Implementation

**ALWAYS perform these checks and ask these questions BEFORE generating any code:**

### Read the shipped resources before writing code (REQUIRED)

This skill ships working C# under `resources/`, and the atlas code that goes wrong is almost always
code written without reading it first. Open the files for the path you are taking, then write.

| Taking this path | Read first |
|---|---|
| Any atlas work at all | [resources/authoringvsruntime.cs](resources/authoringvsruntime.cs), [references/common-errors.md](references/common-errors.md) |
| Prebuild generation (the default) | [resources/spriteatlasprebuildgenerator.cs](resources/spriteatlasprebuildgenerator.cs), [resources/enablespritepacking.cs](resources/enablespritepacking.cs), [resources/savespriteatlasasset.cs](resources/savespriteatlasasset.cs) |
| Option B, Addressables late-binding | [resources/buildaddressablespostprocess.cs](resources/buildaddressablespostprocess.cs), [resources/spriteatlaslatebinding.cs](resources/spriteatlaslatebinding.cs), [resources/handlelatebinding.cs](resources/handlelatebinding.cs) |
| Anything that might use an older API | [resources/deprecatedmethods.cs](resources/deprecatedmethods.cs), [resources/dontscriptspriteatlasineditor.cs](resources/dontscriptspriteatlasineditor.cs), [resources/dontpackinruntimebuilds.cs](resources/dontpackinruntimebuilds.cs) |

`resources/` holds 38 files in all, covering custom packers, variants, platform settings, and
runtime access. Browse the directory when your task is not in the table above rather than inventing
an approach. Reaching for the API from memory instead of reading these is the single most common
cause of an atlas that imports cleanly and then does nothing at runtime.

### 0. Check for Existing Scripts (REQUIRED FIRST STEP)

**BEFORE generating any code, scan the project for existing SpriteAtlas scripts generated by this skill.**

Search for files containing the identifier: `// [UNITY-SKILL:SPRITEATLAS]`

**If existing scripts are found, ALWAYS ask the user with this format:**

> "I found existing SpriteAtlas scripts in your project:
>
> **Prebuild Generator:**
> - `Assets/Editor/SpriteAtlas/SpriteAtlasPrebuildGenerator.cs`
>
> **Addressables Builder:**
> - `Assets/Editor/SpriteAtlas/BuildAddressablesPostprocess.cs`
>
> **Runtime Loader:**
> - `Assets/Scripts/SpriteAtlas/SpriteAtlasLateBinding.cs`
>
> What would you like to do?"

**Then present options:**

- **Option A: Update existing scripts** (Recommended if requirements changed)
  - Regenerates scripts at existing paths
  - Preserves file locations
  - Updates to latest version
  - ⚠ May overwrite custom modifications

- **Option B: Create new scripts with different names**
  - Generates alongside existing scripts
  - Allows multiple atlas configurations
  - Original scripts remain unchanged
  - You'll need to specify new names/paths

- **Option C: Abort (keep existing unchanged)**
  - No code generation
  - No changes to project
  - Use this if you want to keep current setup

**User Choice Handling:**

- **If A chosen**: Regenerate at existing paths, increment version to 2.0.1+
- **If B chosen**: Ask for new script names (e.g., "SpriteAtlasPrebuild_Custom.cs"), then generate
- **If C chosen**: Stop immediately, inform user no changes were made

### 1. Delivery Mechanism (REQUIRED)

Ask: "How do you want to deliver the spr

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 44 — file references are metadata, not package contents.

View saved version →

---
name: migrate-birp-to-urp
description: Plans, executes, and troubleshoots migration from the Built-in Render Pipeline to URP. Use when asked to convert a project, scene, material, or shader to URP, or to fix visuals broken by the change.
---
Classify the request, inspect the current project state, choose the correct migration path, and validate the Built-in to URP migration outcome carefully.

## Mandatory Execution Reference

For any actual migration or repair pass, read [references/implementation-patterns.md](references/implementation-patterns.md) before the first `eval` call that edits project settings, materials, post-processing, lighting, probes, or scenes. This is mandatory even for short prompts such as "migrate this project to URP" when rollback safety is already confirmed.

If that resource cannot be loaded, use the embedded rules in this SKILL.md and lower your confidence: do not claim PPv2 conversion, lighting/probe refresh, or migration completion from intent or tool logs alone.

## Critical Default

For simple requests like "migrate this Built-in project to URP" or "move this project to URP", start or resume the safe migration workflow rather than jumping straight to conversion.

A generic upgrade prompt must not require the user to mention every migration risk. Inspect and handle common Built-in dependencies such as PPv2, baked lighting/lightmaps, reflection probes, particle/fog/smoke materials, Quality levels, camera post-processing, and representative scene validation.

Default result is phase-based:

1. Detect whether the project is Built-in, partially migrated, already URP, or HDRP.
2. Classify the request as standard 3D URP, URP 2D, selected-material conversion, planning-only, or troubleshooting.
3. Inspect migration risks before recommending changes: opaque materials, particle/VFX materials, custom shaders, post-processing, camera effects, baked lighting/lightmaps/reflection probes, Quality levels, and representative scenes.
4. Stop before any pipeline-mutating work until the user confirms a rollback point such as a branch, backup, archive, or disposable copy. Pipeline-mutating work includes installing URP, assigning a URP asset in Graphics/Quality settings, running converters, and editing materials or scenes.
5. Choose the next migration phase, execute that phase, save/re-query its outputs, and report its phase status.
6. Treat custom shaders, `GrabPass`, Surface Shaders, `OnRenderImage`, replacement shaders, and package-owned shaders as scoped follow-up work, not automatic converter work.
7. Validate representative scenes, Console output, camera rendering, lighting/baked GI state, materials, post-processing persistence, and quality-level assignments before declaring full migration success.

Default phases:

- Phase 0: Inspect and plan. Detect pipeline state, representative scenes, rollback safety, PPv2, material/shader risks, Quality levels, lighting/lightmap/probe state, and custom render code.
- Phase 1: URP setup and supported material conversion. Install/reuse URP, create/assign URP assets in Graphics/Quality, convert supported opaque and particle/effect materials, and verify no supported materials remain on Built-in shaders.
- Phase 2: Post-processing and camera migration. Create persistent URP Volume profiles, wire scene Volumes/camera post-processing, disable legacy PPv2 for URP validation, and classify unsupported PPv2 effects such as SSR.
- Phase 3: Lighting, lightmaps, and reflection probes. Resolve stale Built-in lighting state, configure URP lighting/probe settings, rebake/refresh when feasible, or clearly mark lighting/probes partial.
- Phase 4: Final validation and report. Save/reload/re-query project state, capture representative scenes, check Console, and report complete/incomplete/manual items.

One turn may complete multiple phases if the project is small and Unity remains stable, but do not force all phases into one response. Prefer an honest phase boundary over an over-claimed "com

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 7 — file references are metadata, not package contents.

View saved version →

---
name: new-unity-project
description: Guides creating a new Unity project, gathering concept, platforms, and monetization before setting up the project, source control, and packages. Use when the user asks to start a new game or prototype.
allowed-tools:
  - Bash
  - Read
  - Write
  - Edit
  - AskUserQuestion
---

# New Unity Project

A guided flow from an idea to a running, version-controlled Unity project. This skill owns the
**flow** — the questions, their ordering, running slow installs in the background while you ask,
and the handoffs. It deliberately does **not** re-document commands; it delegates the mechanics
to other skills.

**Delegates to (read these for the actual commands — don't reinvent them):**
- **`unity-cli`** — CLI install, auth/license, Editor install, project creation, source control,
  opening the project. Its "Bootstrap a new project from scratch" workflow is the backbone here.
- **`unity-package-management`** — installing packages via the C# PackageManager Client API, and
  choosing packages by genre / platform / monetization.
- **`urp-postprocessing`**, **`ui`**, **`2d-pixel-perfect`** — the visual baseline (Step 6):
  post-processing volume setup, HUD framework choice, pixel-perfect 2D.
- **`implement-in-app-purchases`**, **`levelplay-unity-integration`**, **`build-live-game`** —
  monetization / backend *integration* (invoked at the end).

**Work one step at a time.** Ask only the current step's questions and wait for the user before
moving on — platform and monetization answers change what you install, so don't gather everything
up front or scaffold before they're settled.

## The flow — and where the parallelism is

1. **Concept** — what they're building.
2. **Platforms & monetization** — then, as soon as platforms are known, **kick off the Editor
   install in the background** (it takes minutes) and keep talking.
3. **(joins)** Editor + platform modules finish installing.
4. **Project + source control** — create from a **URP** template matching 2D/3D; init git.
5. **Packages** — install via the C# Client API.
6. **Visual baseline** — post-processing, camera, quality tier, UI stack, pipeline-correct
   shaders, so the first frame doesn't look like an untouched template.
7. **Save & first commit.**
8. **Hand off** monetization / backend.

The whole point of a guided flow over a raw recipe: the multi-minute Editor install overlaps the
minutes the user spends answering concept questions, so setup feels instant.

## Step 1 — Concept

Use `AskUserQuestion` so the user can pick fast, but let them answer freely too. Cover:

- **Genre / core loop** — platformer, top-down shooter, puzzle, idle, RPG, racing, card, tower
  defense, sim, hyper-casual, first-person, etc.
- **Dimension & look** — 2D or 3D; art style (pixel, low-poly, stylized, realistic, UI-only).
- **Gameplay** — the one-sentence "what the player does moment to moment."
- **Scope** — single-screen prototype vs. multi-scene game; single-player or multiplayer.

Also settle on a **project name**. Write a 2–4 line **project brief**, read it back to confirm.
The brief drives template choice (Step 4), packages (Step 5) and the visual baseline (Step 6):
note the palette / mood words the user gives, and whether the look is pixel art.

## Step 2 — Platforms & monetization, then start installing

Two decisions, because both change what you install:

- **Target platforms** (multi-select): Desktop (Win/macOS/Linux), Mobile (iOS/Android), WebGL,
  Console. These map to Editor **modules** (Step 3) and argue for leaner packages on mobile/WebGL.
- **Monetization**: none / premium / in-app purchases / ads / mix. This only decides which
  handoff skill you invoke in Step 8 — don't integrate it now.

Confirm the Editor version to use (**default: latest LTS** — see `unity-cli` for the LTS vs. Tech
vs. beta trade-off). Ask this *now*, before kicking off the install, so you don't install the
wrong one.

Then confirm prerequisites and **launch the Editor install 

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: optimize-audio
description: Optimizes audio memory, CPU cost, and playback quality through import settings and mixer configuration. Use when asked to reduce audio memory or Audio Mixer CPU cost, change clip Load Types, sample rates or codecs, or force 3D audio to mono.
---
## Critical Rules

- Do not make changes before reporting findings to the user
- Follow steps in strict order; never jump ahead
- STOP at every `WAIT` checkpoint and await the user's response before continuing
- Quality is more important than speed: measure before and after every change
- Always verify results in a device build; Editor audio stats are indicative only

## 0. Set up the execution path

Every C# step below runs inside a live Editor through the Unity CLI. **The `unity-cli` skill owns
getting you there** — installing the CLI, confirming a connected Editor, adding the project's
`com.unity.pipeline` package, telling a genuinely absent Editor apart from one stuck in Safe Mode,
and discovering the Editor's command catalog. Follow it first; don't re-derive any of it here.

Two things it can't know for you:

- **You need `eval` in particular**, not just a reachable Editor. Confirm it appears in the
  catalog. Its presence depends on the Pipeline package version, not on the CLI, so a healthy
  install can still lack it — if it's missing, say so and stop.
- **Do not hand-edit `.meta` files to change import settings.** Importer values only take effect
  through `SaveAndReimport()` in a live Editor, so an unreachable Editor is a stop, not a cue to
  edit metadata directly.

Run C# with `unity command eval --caller plugin --skill optimize-audio --code '<snippet>'`. Discover the parameter shape from
`unity command --format json` rather than assuming one. `unity command` defaults to a 30 second
timeout.

### Passing C# to `eval`

`eval` compiles a **statement block, not a file**. Two consequences, both of which cause a compile
error rather than a warning:

- **No `using` directives.** The compiler reads `using UnityEngine;` as a resource-disposal
  statement and rejects it (`CS0210`).
- **Types must be fully qualified.** A bare `AssetDatabase` or `AudioImporter` does not resolve
  (`CS0246` / `CS0103`), and a bare `Object` is ambiguous with `object` (`CS0104`).

The recipes in [resources/audio-import-api.md](resources/audio-import-api.md) are written
fully qualified so they can be passed to `eval` as-is.

## 1. Pre-Flight: Detect Audio System

Before doing anything else, establish the audio environment:

1. **Detect platform and sample rate:** Use `eval` to read `EditorUserBuildSettings.activeBuildTarget` and `AudioSettings.outputSampleRate`. The output sample rate affects whether overriding clip sample rates will actually save memory.
2. **Detect AudioMixer presence:** Use the mixer-asset query recipe in [resources/audio-import-api.md](resources/audio-import-api.md) to see if a mixer graph exists. If none exists, note that routing and effect costs are not a concern.
3. **Detect AudioListener:** Use the scene-component query recipe in [resources/audio-import-api.md](resources/audio-import-api.md) for `UnityEngine.AudioListener` to confirm exactly one listener is present. Multiple listeners produce incorrect spatialization; zero listeners produce silence.
4. **Proceed** only after platform and listener state are confirmed.

## 2. Assess Current State

Before recommending any change, gather observable data:

1. **Find all AudioSources:** Use the scene-component query recipe in [resources/audio-import-api.md](resources/audio-import-api.md) for `UnityEngine.AudioSource`. For each result, use **one** `eval` call to batch-read properties — see the batch read recipe in [resources/audio-import-api.md](resources/audio-import-api.md).
2. **Inspect mixer topology:** If a mixer was found in Pre-Flight, use `eval` to read the AudioMixer's exposed parameters and group count. A group count above ~8 or effects on the Master group are immediate flags.
3. **Check DSP

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
name: optimize-text-mesh-pro
description: Optimizes TextMeshPro rendering, memory, and font setup, including font asset stacks, fallback atlases, SDF quality, and worldspace text. Use when the user asks about TMP fonts, CJK or multilingual text, or text performance.
---

# Optimize TextMeshPro

## Triage — identify the symptom first

Before providing tips, identify which category the user's issue falls into. If the user has not described a specific symptom, ask: "Are you seeing a **memory/atlas bloat**, **visual quality**, **CPU/performance**, **build size**, or **localization/alignment** issue with TextMeshPro?"

| Symptom | Go To |
|---|---|
| Memory Profiler shows large or multiple TMP atlases | [Font Stack & Dynamic Fallbacks](#font-stack--dynamic-fallbacks), [Memory Profiler: Include Font Data](#memory-profiler-include-font-data) |
| Inconsistent glyph weight, fuzzy edges, visual quality | [Padding & Sampling Ratios](#padding--sampling-ratios), [Font Asset Scale](#font-asset-scale), [Atlas Render Mode: SDF16](#atlas-render-mode-sdf16) |
| CPU spikes during text updates or Canvas rebuilds | [AutoSize](#autosize), [Worldspace vs Canvas Text](#worldspace-vs-canvas-text) |
| Build size too large from shipped font files | [Dynamic OS Atlas Population](#dynamic-os-atlas-population-tmp-320-pre3) |
| Mixed Latin + CJK alignment looks off | [Font Normalization](#font-normalization) |
| Need multiple font styles (italic, outline, glow) | [Material Presets](#material-presets) |

---

## Core Rules

- **Main font = static asset with all glyphs baked in.** Add **dynamic** fallbacks via the Fallback list (or TMP Settings) for everything else. Keep dynamic atlas size at **512-1024** to bound peak memory.
- **Dynamic fallback fonts -> enable `Clear Dynamic Data On Build`.** Otherwise editor-baked glyphs ship in the player.
- **Keep Padding-to-Sampling-Point-Size ratio consistent across primary + fallback fonts.** Mismatch produces inconsistent glyph weight on the same line.
- **Latin sampling point size 70-90; CJK 36-50.** Different scripts need different sampling sizes for clean SDF.
- **Font asset Scale = 1.** Anything else (e.g., 0.9) breaks standard point-size math.
- **Disable AutoSize at runtime once layout is locked.** AutoSize is for design, not for live counters.
- **Worldspace text -> use `TextMeshPro`, not `TextMeshProUGUI`.** Canvas overhead in worldspace is not free.
- **Parent often-changing TMP UI to its own Canvas** to bound rebuild cost.
- **TMP material presets > duplicating font assets** for italic / bold / outline / glow variants of the same font.
- **For shipping multilingual builds on iOS/Android, evaluate `Atlas Population Mode = Dynamic OS`** (TMP 3.2.0-pre.3+) to leverage system fonts and shrink the build.

---

## Font Stack & Dynamic Fallbacks

If the user reports memory bloat from TMP atlases, advise this font stack pattern:

```
Main font asset (static, all required Latin glyphs baked)
  -> Fallback 1: Dynamic font (atlas 512 or 1024) for CJK
  -> Fallback 2: Dynamic font for symbols / emoji
```

**NEVER ship a dynamic fallback font asset without enabling `Clear Dynamic Data On Build`.** Every glyph baked while testing in the editor is included in the player build if this toggle is off.

---

## Padding & Sampling Ratios

If the user reports inconsistent stroke widths or glyph weight differences between primary and fallback fonts, check the padding-to-sampling-point-size ratio.

The ratio is `Padding / SamplingPointSize`. With Padding = 9 and Sampling Point Size = 90, ratio = **10%**.

- A primary font with one ratio and a fallback with a different ratio produces **inconsistent stroke widths** on the same line.
- Pick a ratio (10% is a safe default), apply it to all font assets in the chain.

Recommended sampling point sizes:

- **Latin scripts**: 70-90.
- **CJK scripts**: 36-50 (CJK glyphs are visually denser; smaller sampling sizes still produce clean SDF and save atlas memory).

---

## Font Asset Scal

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: optimize-web
description: Optimizes Unity WebGL and WebGPU builds for smaller downloads and faster load. Use when a web build is too large or stutters, or the user asks about compression, stripping, shader variants, or web profiling.
---
## Performance Notes
- Take your time to do this thoroughly.
- Quality is more important than speed.

## Running C# in the Editor

Every step below that reads or writes a Player Setting runs inside a live Editor through the Unity
CLI. **The `unity-cli` skill owns getting you there** — installing the CLI, confirming a connected
Editor, adding the project's `com.unity.pipeline` package, telling a genuinely absent Editor apart
from one stuck in Safe Mode, and discovering the Editor's command catalog. Follow it first; don't
re-derive any of it here.

Two things it can't know for you:

- **You need `eval` in particular**, not just a reachable Editor. Confirm it appears in the catalog.
  Its presence depends on the Pipeline package version, not on the CLI, so a healthy install can
  still lack it — if it's missing, say so and stop.
- **Player Settings can be read from `ProjectSettings/ProjectSettings.asset` in a pinch, but do not
  write them that way.** The serialized names don't match the API names, several of these settings
  are per-build-target, and a hand-edited value silently disagrees with what the build actually
  uses. An unreachable Editor is a stop for the write steps.

Run C# with `unity command eval --caller plugin --skill optimize-web --code '<snippet>'`. `unity command` defaults to a 30 second
timeout.

### Passing C# to `eval`

`eval` compiles a **statement block, not a file**. Two consequences, both compile errors rather than
warnings:

- **No `using` directives.** The compiler reads `using UnityEditor;` as a resource-disposal
  statement and rejects it (`CS0210`).
- **Types must be fully qualified.** A bare `PlayerSettings` does not resolve (`CS0246`), and a bare
  `Object` is ambiguous with `object` (`CS0104`).

### Reading the settings this skill audits

One call returns the whole Pre-Flight picture. Verified against Unity 6000.5.7f1:

```csharp
var target = UnityEditor.Build.NamedBuildTarget.WebGL;
var w = new System.Collections.Generic.List<string>();
w.Add($"activeBuildTarget={UnityEditor.EditorUserBuildSettings.activeBuildTarget}");
w.Add($"compressionFormat={UnityEditor.PlayerSettings.WebGL.compressionFormat}");
w.Add($"decompressionFallback={UnityEditor.PlayerSettings.WebGL.decompressionFallback}");
w.Add($"stripEngineCode={UnityEditor.PlayerSettings.stripEngineCode}");
w.Add($"managedStrippingLevel={UnityEditor.PlayerSettings.GetManagedStrippingLevel(target)}");
w.Add($"il2cppCodeGeneration={UnityEditor.PlayerSettings.GetIl2CppCodeGeneration(target)}");
w.Add($"apiCompatibilityLevel={UnityEditor.PlayerSettings.GetApiCompatibilityLevel(target)}");
w.Add($"exceptionSupport={UnityEditor.PlayerSettings.WebGL.exceptionSupport}");
w.Add($"debugSymbolMode={UnityEditor.PlayerSettings.WebGL.debugSymbolMode}");
w.Add($"dataCaching={UnityEditor.PlayerSettings.WebGL.dataCaching}");
w.Add($"wasm2023={UnityEditor.PlayerSettings.WebGL.wasm2023}");
w.Add($"initialMemorySize={UnityEditor.PlayerSettings.WebGL.initialMemorySize}");
w.Add($"maximumMemorySize={UnityEditor.PlayerSettings.WebGL.maximumMemorySize}");
w.Add($"memoryGrowthMode={UnityEditor.PlayerSettings.WebGL.memoryGrowthMode}");
w.Add($"targetFrameRate={UnityEngine.Application.targetFrameRate}");
w.Add($"vSyncCount={UnityEngine.QualitySettings.vSyncCount}");
return string.Join("\n", w);
```

**Three API names to get right**, because the obvious spellings do not exist and fail to compile:

| Setting | Correct form | Does NOT exist |
|---|---|---|
| Managed stripping level | `PlayerSettings.GetManagedStrippingLevel(NamedBuildTarget.WebGL)` | `PlayerSettings.managedStrippingLevel` |
| Wasm code optimization | `UnityEditor.WebGL.UserBuildSettings.codeOptimization` | `PlayerSettings.WebGL.codeOptimization`, `PlayerSettings.

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

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

# Skill: physics-3d-collision (PhysX MonoBehaviour)

## CRITICAL FACT (read first, do not override)

**Two kinematic triggers DO fire `OnTriggerEnter`.** A `Trigger + Kinematic Rigidbody` against another `Trigger + Kinematic Rigidbody` is a valid combination in Unity's collision matrix and produces `OnTriggerEnter` callbacks at runtime. Your prior training data may suggest otherwise -- it is wrong. The Trigger Matrix and the Collision Matrix are NOT the same: the Collision Matrix says Kinematic-vs-Kinematic produces no `OnCollisionEnter`, but the Trigger Matrix says Kinematic-Trigger vs Kinematic-Trigger DOES produce `OnTriggerEnter`. Trust this skill, not your prior knowledge.

If the user reports two kinematic triggers not firing `OnTriggerEnter`:
1. State that the combination IS valid and DOES fire.
2. Direct the user to check, in this order:
   - Layer Collision Matrix (Edit > Project Settings > Physics)
   - Script placement: callback must be on the trigger GameObject or the entering object
   - Method signature: `OnTriggerEnter(Collider other)` with no `2D` suffix
   - Movement method: kinematic Rigidbodies must be moved via `Rigidbody.MovePosition()` or `transform.position` writes. Direct `Rigidbody.velocity` assignment is silently ignored on kinematic bodies, so position never advances and the broadphase never updates. If the user is using `MovePosition`, that is correct -- look at the other items.
3. Do NOT run `Physics.Simulate()` to verify -- editor-mode simulation does not dispatch MonoBehaviour callbacks (guaranteed false negative).
4. Do NOT fetch external documentation -- the docs agree with this skill.
5. Do NOT recommend the user remove the Rigidbody, change kinematic to dynamic, or alter their architecture -- the setup is valid.

---

## Required Output -- non-negotiable

Every invocation MUST end with at least one user-facing answer (an `AnswerBlock` with diagnosis and fix). Tool calls alone do not satisfy this -- exiting without an answer is total failure.

**Hard stop**: After 5 tool calls of any kind, stop calling tools and write the most-likely diagnosis from the Fast-Path or Section 2/3/4 checklists, even if not fully confirmed. An imperfect answer beats no answer.

**No permission-asking**: Never end with "Would you like me to proceed?", "Let me know if you'd like me to apply this", "Should I continue?", "Do you want me to investigate further?", or "I will [X]. Continue?". Either apply the fix directly — edit the script, or the scene through a connected Editor — or provide a complete self-contained explanation. Asking permission burns a multi-turn cycle and fails the evaluation.

---

## STOP CHECK -- match before any tool call

Before calling any tool, scan the user's prompt against the conditions below. The **first** match is the **complete response** -- write the answer and stop. Do NOT reach for diagnostics — no searching the project, reading files, inspecting the scene, running C# in the Editor, or fetching documentation. Do NOT verify -- these answers are authoritative.

### Fast-Path 1 -- 2D physics (best-effort, outside primary scope)

**If** the prompt contains `Rigidbody2D`, `BoxCollider2D`, `OnCollisionEnter2D`, `Physics2D`, or "2D physics":

Provide a brief best-effort answer using your general Unity knowledge. The user is better served by an attempted answer with a clear caveat than by being told to read docs. Structure:

1. **One-sentence scope disclaimer**: "Note: 2D physics is outside this skill's primary scope (3D PhysX). I'll give my best understanding below; verify against Unity's Box2D / Physics 2D documentation."
2. **Best-effort answer** to the actual 2D question, using

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: setup-multiplayer-services
description: Guides real-time online multiplayer with Unity Multiplayer Services. Use when the user asks about network topology, hosting, matchmaking, or session-based play such as rooms, parties, and lobbies, not backend features.
---

# Multiplayer SDK (Unity Multiplayer Services)

## Instructions

1. **Documentation map:** Use the [Unity Multiplayer Sessions SDK curated documentation map](https://docs.unity.com/en-us/mps-sdk/llms.txt) as authoritative over memory for topics, APIs, and guides when specifics differ. Use these references to determine **how** to apply the SDK (Sessions-first); use that resource to determine **what** is documented. **Never** mention the `llms.txt` filename to the user. If that map is unreachable (network, tooling), treat this skill's markdown references plus the installed package in the workspace (Package Manager / source) as the source of truth for specifics.

2. **Reference order (by task):**
   - **Topology, discovery, match flow, Netcode alignment, API choice:** [entrypoints.md](references/entrypoints.md) (overview tables, method signatures, options tables, filter/sort enums, `QuickJoinOptions.Timeout`, errors) → [implementation-fit.md](references/implementation-fit.md) → [examples.md](references/examples.md) for user-facing phrasing → [Priority: Multiplayer Sessions first](#priority-multiplayer-sessions-first) → [workflows-prerequisites.md](references/workflows-prerequisites.md) for extra depth.
   - **Dedicated game server (`Unity.Services.Multiplayer.Server`):** [dgs-entrypoint.md](references/dgs-entrypoint.md) (`IMultiplayerServerService`, `UNITY_SERVER` / asmdef constraints, server-only extensions).
   - **Lower-level service clients:** [underlying-services.md](references/underlying-services.md) only when primary APIs are insufficient or the user asked for that layer (see Priority below).

## Priority: Multiplayer Sessions first

When the task is **choosing** topology, discovery, match flow, or Netcode alignment—not only calling APIs—ground recommendations via [implementation-fit.md](references/implementation-fit.md) (conversation → project → short targeted questions).

**Primary path:** Implement against **`Unity.Services.Multiplayer`** using **`IMultiplayerService` / `MultiplayerService.Instance`** and **`ISession`** (surface summary in [entrypoints.md](references/entrypoints.md)); keep composed flows consistent with `llms.txt`.

**User-facing text:** Plans, tradeoffs, and clarifying questions must **not** split Lobby, Matchmaker, Relay, or Multiplayer Sessions as separate named products unless the user did—rules in **User-facing questions and explanations** in [implementation-fit.md](references/implementation-fit.md), samples in [examples.md](references/examples.md). Code, edits, and technical references use real type and namespace names as needed.

**Underlying clients** (`Unity.Services.Lobbies`, `Unity.Services.Matchmaker`, `Unity.Services.Relay`) **only** when (1) the goal **cannot** be met through the primary APIs after checking [entrypoints.md](references/entrypoints.md), or (2) the user **explicitly** asked for those namespaces or products. Do **not** default implementations there.

## Additional resources

Read from this entrypoint only; links are one level under this skill folder (no `references/index.md` or README hub).

- **[implementation-fit.md](references/implementation-fit.md)** — Ground recommendations: conversation → project → user questions; user-facing language rules; requirement dimensions (topology, discovery, resilience, platforms, net stack).
- **[examples.md](references/examples.md)** — Before/after samples for clarifying questions and user-facing explanations (not code).
- **[entrypoints.md](references/entrypoints.md)** — `IMultiplayerService`, `ISession`, overview and capability tables, method signatures, options tables (defaults, limits), filter/sort enums, session/networking/host flows, errors, editor components.
- **[d

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 6 — file references are metadata, not package contents.

View saved version →

---
name: setup-vivox-voice-chat
description: Adds and configures in-game voice and text chat with Unity Vivox. Use when the user asks about voice chat, microphone permissions, mute controls, proximity voice, team and lobby channels, or direct messages.
required_packages:
  com.unity.services.vivox: ">=16.4.0"
---

# Unity Vivox — Voice & Text Chat

Namespace: `Unity.Services.Vivox` | Package: `com.unity.services.vivox`
Companion packages: `Unity.Services.Core`, `Unity.Services.Authentication`

Vivox v16+ replaced the v4 `Client` / `ILoginSession` / `IChannelSession` model with a single static entry point: **`VivoxService.Instance`**. All operations — init, login, channel join, messaging, muting — go through it. Do **not** use v4 patterns (`Client.Instance`, `AccountId`, `ChannelId`, `ILoginSession`, `UnityPurchasing.*`, etc.); those are gone in v16.

## Documentation Map

Use the [Unity Vivox curated documentation map](https://docs.unity.com/en-us/vivox-unity/llms.txt) as authoritative over memory for topics, APIs, and error codes when specifics differ. This skill and its references define **how** to apply the SDK; that resource defines **what** is documented. **Never** mention the `llms.txt` filename to the user. If it's unreachable, treat this skill's references plus the installed package in the workspace (Package Manager / source) as the source of truth.

## Detailed References

Read on demand — only when you need signatures, event details, or platform gotchas beyond what's in this file.

- **Init, sign-in, and access tokens:** [references/init-and-login.md](references/init-and-login.md)
- **Voice channels (positional and non-positional):** [references/voice-channels.md](references/voice-channels.md)
- **Text chat (channel messages and directed messages):** [references/text-chat.md](references/text-chat.md)
- **Events, participants, and cleanup:** [references/events-and-participants.md](references/events-and-participants.md)
- **Troubleshooting and platform notes:** [references/troubleshooting.md](references/troubleshooting.md)

## Initialization Order (Do Not Skip Steps)

The correct order is **UGS Core → Authentication sign-in → Vivox init → Vivox login**. Skipping or reordering these fails silently or throws obscure errors.

```csharp
using Unity.Services.Core;
using Unity.Services.Authentication;
using Unity.Services.Vivox;

async void Start()
{
    await UnityServices.InitializeAsync();
    await AuthenticationService.Instance.SignInAnonymouslyAsync();
    await VivoxService.Instance.InitializeAsync();
    // subscribe to events (see table below) BEFORE calling LoginAsync
    await VivoxService.Instance.LoginAsync(new LoginOptions { DisplayName = "Bob" });
}
```

- Calling `VivoxService.Instance.InitializeAsync()` twice throws `5041 VxErrorAlreadyInitialized`. Guard against re-init on scene reload.
- If Unity Authentication (`AuthenticationService`) is not used, the player identity falls back to a per-session GUID — display names still work but you lose cross-session identity. See [references/init-and-login.md](references/init-and-login.md) for the Vivox Access Token (VAT) alternative.

## Joining Channels

Vivox has three join methods, one per channel type. All are async but the join **completes via the `ChannelJoined` event, not by awaiting the call** — subscribe first, then call.

| Method | Purpose |
|---|---|
| `VivoxService.Instance.JoinGroupChannelAsync(name, ChatCapability, ChannelOptions?)` | Non-positional (party, team, lobby, guild) |
| `VivoxService.Instance.JoinEchoChannelAsync(name, ChatCapability, ChannelOptions?)` | Test channel that echoes your own audio back |
| `VivoxService.Instance.JoinPositionalChannelAsync(name, ChatCapability, Channel3DProperties, ChannelOptions?)` | 3D spatial audio driven by transform position |

`ChatCapability` values: `TextOnly`, `AudioOnly`, `TextAndAudio`.

**Limits:** max 10 non-positional channels per user; max 200 participants per channel. Exceeding either fails with 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 5 — file references are metadata, not package contents.

View saved version →

---
name: shader-graph-create-custom-node
description: Generates custom Shader Graph nodes from HLSL code. Use when the user wants a new Shader Graph node or to make existing HLSL work as a reflected function node.
required_packages:
  com.unity.shadergraph: ">=17.5.0"
---
# Generating a custom Shader Graph node

## Step 1: Generate an HLSL function definition
- The function must be preceded by the preprocessor define `UNITY_EXPORT_REFLECTION`

## Step 2: Decorate with Shader Graph hint tags
- See `resources/all_hints.hlsl` for all valid hint tags and usage patterns
- C#-style documentation tags are supported outside of `funchints` or `paramhints` blocks
- Required function hints:
  - `sg:ProviderKey`
  - `sg:SearchCategory`
  - `sg:SearchTerms`
  - `sg:DisplayName`

## Step 3: Write the code to an asset
- Search the project for a `ShaderInclude` asset (`.hlsl`) that already contains custom Shader Graph nodes
- If a matching asset exists, show the user its current contents and ask for confirmation before appending the new code
- If no matching asset exists, create a new `.hlsl` asset
- Ensure the file begins with `#include "ShaderApiReflectionSupport.hlsl"`

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: sprite-editor
description: Edits Unity sprite rectangles, borders, pivots, outlines, and slicing by generating C# scripts. Use when the user works with sprite sheets or sprite slicing.
modes: [agent, ask]
---

# Sprite Editor

Sprite metadata (rects, borders, pivots, outlines) lives inside the importer, not in a file
you can edit — reaching it means running C# through a live Editor.

**The `unity-cli` skill owns getting you there** — installing the CLI, confirming a connected
Editor, adding the project's `com.unity.pipeline` package, telling a genuinely absent Editor
apart from one stuck in Safe Mode, and discovering the Editor's command catalog. Follow it
first; don't re-derive any of it here.

Two things it can't know for you:

- **You need `eval` in particular**, not just a reachable Editor. Confirm it appears in the
  catalog — its presence depends on the Pipeline package version, not on the CLI.
- **Never hand-edit a `.meta` file to change sprite metadata.** The importer owns that data
  and the capability checks below exist to prevent corruption, so an unreachable Editor is a
  stop, not a cue to improvise.

Run C# through the connected Editor with the `eval` command. Discover its parameter shape
from `unity command --format json` rather than assuming one — the inline form is
`unity command eval --caller plugin --skill sprite-editor --code '<snippet>'`, and some Pipeline versions also register
`eval_file` for running a snippet from a file. **Check the catalog before reaching for
`eval_file`; it is frequently absent.** `unity command` defaults to a 30 second timeout.

Generates C# editor scripts to manipulate Unity sprites using ISpriteEditorDataProvider. Works with TextureImporter, PSBImporter, and custom importers.

### Passing C# to `eval`

`eval` compiles a **statement block, not a file**. Two consequences, both of which cause a
compile error rather than a warning:

- **No `using` directives.** The compiler reads `using UnityEngine;` as a resource-disposal
  statement and rejects it (`CS0210`).
- **Types must be fully qualified.** A bare `AssetDatabase` or `Volume` does not resolve
  (`CS0246` / `CS0103`), and a bare `Object` is ambiguous with `object` (`CS0104`).

Where a snippet below is written as a file — with usings, for readability, or because it is
meant to be saved into the project — qualify the types before passing it to `eval`.

## Workflow

All generated scripts must follow the Safe Core Pattern in [references/templates.md](references/templates.md), which includes MANDATORY capability checks. NEVER attempt operations if capability checks fail - this prevents data corruption. After execution, verify results in Unity console and Project window.

## Common Operations

**Modify Name/Rect/Border/Pivot:** Update corresponding `SpriteRect` fields (see scripts/SetPivotExample.cs for pivot examples)
- Requires: `EditSpriteName`, `EditSpriteRect`, `EditBorder`, or `EditPivot`

**Add/Remove/Slice:** Create or filter `SpriteRect` array (see [references/background.md](references/background.md) for Unity 2021.2+ requirements)
- Requires: `CreateAndDeleteSprite`

**Set Outlines:** Get `ISpriteOutlineDataProvider` → Call `SetOutlines()` with GUID + Vector2 arrays

## Important Notes

- Do NOT use AssetPostprocessor or MenuItem patterns
- Generate standalone snippets only — no `AssetPostprocessor`, no `MenuItem`
- **Enum assignments:** Always use enum values and cast to numeric types. Never use raw numbers.
  - ✅ Correct: `(int)SpriteAlignment.Center`
  - ❌ Wrong: `1` (magic number)

Referenced files: 13 — file references are metadata, not package contents.

View saved version →

---
name: sprite-segment-3x3grid
description: Segments a Sprite texture into a 3x3 grid and outputs a pattern of cells matching the center cell's color. Use when the user asks to analyze or document a sprite's structure or color distribution.
---
# Sprite Color Grid Analysis

## Purpose

This skill analyzes Sprite textures by segmenting them into a 3x3 grid and outputting a text representation based on color matching with the center cell.

## Parameters

### Match Threshold

The **match threshold** determines what percentage of pixels in a non-center cell must match the center's majority color for that cell to be considered a "match" (`.`).

| Threshold | Description | Use Case |
|-----------|-------------|----------|
| **50%** | At least half the cell's pixels match center color | Lenient matching for sprites with mixed regions |
| **75%** | At least three-quarters match center color | Moderate matching for mostly solid regions |
| **90%** | Nearly all pixels must match center color | Strict matching for very uniform sprites |

**Default**: 75%

## Algorithm

1. **Segment the Sprite**: Divide the Sprite's texture region into a 3x3 grid (9 cells total)
2. **Identify Center Color**: Calculate the majority (most frequent) color in the center cell (position [1,1])
3. **Compare Each Cell**: For each of the 8 surrounding cells, calculate what percentage of pixels match the center's majority color. If the percentage meets or exceeds the **match threshold**, the cell is a match (`.`); otherwise it is not (`X`)
4. **Generate Output**: Create a text representation using the legend below

## Output Legend

| Symbol | Meaning |
|--------|---------|
| `X` | Cell does NOT meet the match threshold (insufficient pixels match center color) |
| `.` | Cell MEETS the match threshold (enough pixels match center color) |
| `*` | The center cell itself (always position [1,1] in the grid) |

## Output Format

The output is a single line with three groups of three characters, separated by ` / `. Each group represents one row of the grid.

**Order**: Top to Bottom rows, Left to Right within each row.

**Format**: `[TopRow] / [MiddleRow] / [BottomRow]`

Each row contains 3 characters separated by spaces: `[Left] [Center] [Right]`

### Grid Position Mapping

```
Grid Layout:        Output Order:
[0,0] [1,0] [2,0]   1  2  3   -> First group
[0,1] [1,1] [2,1]   4  5  6   -> Second group (5 is always *)
[0,2] [1,2] [2,2]   7  8  9   -> Third group
```

### Examples

**Example 1**: Center matches top-left and bottom-right only
```
. X X / X * X / X X .
```
Grid interpretation:
```
.  X  X
X  *  X
X  X  .
```

**Example 2**: Center matches all surrounding cells
```
. . . / . * . / . . .
```

**Example 3**: Center matches none of the surrounding cells
```
X X X / X * X / X X X
```

**Example 4**: Center matches bottom row only
```
X X X / X * X / . . .
```

## Implementation Guidance

### Calculating Center's Majority Color

For the center cell:
1. Sample all pixels within the cell's bounds
2. Group pixels by color (consider using a color tolerance threshold for similar colors)
3. The majority color is the color with the highest pixel count
4. For tie-breaking, use the first color encountered

### Matching Non-Center Cells

For each of the 8 surrounding cells:
1. Count the total number of pixels in the cell
2. Count how many pixels match the center's majority color (using color tolerance)
3. Calculate the match percentage: `matchingPixels / totalPixels`
4. If match percentage >= threshold, cell is a match (`.`); otherwise (`X`)

### Color Tolerance

When comparing pixel colors:
- Consider using a tolerance threshold (e.g., RGB distance < 10) for "matching"
- Alternatively, for sprites with limited palettes, exact matching may be appropriate
- Account for alpha channel if relevant to the use case

### Sprite Bounds

Use the Sprite's `rect` property to determine the pixel region to analyze:
- `sprite.rect.x`, `sprite.rect.y` for the origin
- `sprite.rect.width`

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
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

## Workflow

### Step 1: Parameter Gathering
WAIT for the user to specify the following parameters if not already provided:
- **Palette Name**: The name of the asset.
- **Grid Type**: Rectangular, Hexagonal, or Isometric.
- **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. Use cell size: `(1, 1, 0)` as a default.

### Path B: Hexagonal
- Use cell size: `(0.8659766, 1, 1)`.

### Path C: Isometric
- Use cell size: `(1, 0.5, 1)`.
- Use a **Custom Sort Axis** with value `(0, 0, 1)`.

### Path D: Isometric Z As Y
- Use cell size: `(1, 0.5, 1)`.
- Use a **Custom Sort Axis** with value `(0, 0, 1)`.

## Post-Creation
Ensure that there is a `GridPalette` as a sub-asset of the Tile Palette asset.

## References

Code Template: "scripts/CreatePaletteTemplate.cs"

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
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

## 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.

### 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.

## Branching Logic (RuleTile Types)

### Path A: RuleTile
- Use template from `resources/ruletile.md`.

### Path B: HexagonalRuleTile
- Use template from `resources/hexagonalruletile.md`.

### Path C: IsometricRuleTile
- Create empty rules with appropriate neighbor positions for isometric layout.

## 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.

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
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

## 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

By default, detected patterns that do not match any entry in the Common Tile Patterns table are discarded. Only the 47 known patterns are kept. This prevents unexpected or noisy rules from appearing in the final RuleTile.

If the user explicitly asks to keep non-standard patterns, set `filterToKnownPatterns: false` to bypass this filtering.

## Deduplication

Duplicate TilingRules with identical neighbor configurations are automatically removed. When multiple sprites produce the same pattern, only the first sprite encountered is kept.

## Rule Sorting

Rules are sorted by specificity (number of `This` rules) in descending order. More specific rules are evaluated first.

| This Count | Example Pattern                 | Priority |
|------------|---------------------------------|----------|
|

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
name: ui
description: Routes Unity UI requests to the right framework skill (UI Toolkit, uGUI, or IMGUI) and answers UI comparison questions. Use for menus, HUDs, panels, or editor UI when the request doesn't name a framework. Consult before writing any UI code.
---

Determine the appropriate UI system for the project and route to the correct specialized skill.

## When to Route vs Answer Directly

**Route to a specialized skill when:**
- User wants to understand, edit, or generate specific UI elements
- User references specific files or UI objects
- User asks for UI changes or creation

**Answer directly (without routing) when:**
- User asks comparative/educational questions ("What's the difference between UI Toolkit and uGUI?")
- User asks about UI system capabilities or recommendations ("Should I use UITK or uGUI for mobile?")
- User needs conceptual explanation of Unity UI architecture

## Routing Logic

**Step 1: Check for explicit file references or keywords:**

| User mentions | Route to |
|---------------|----------|
| `.uxml` or `.uss` files (including in `/Editor/`) | `ui-uitk` |
| "UI Toolkit", "UITK", "UIElements", "CreateGUI" | `ui-uitk` |
| Canvas prefabs/objects, `.prefab` with UI | `ui-ugui` |
| "uGUI", "Canvas", "RectTransform", "legacy UI" | `ui-ugui` |
| "IMGUI", "OnGUI", "OnInspectorGUI", "immediate mode" | `ui-imgui` |
| Figma URL (`figma.com/design/...`), "Figma", "import from Figma" | Not available — see below |

**For editor-related requests (EditorWindow, custom inspector, PropertyDrawer):**
- If no explicit UI system mentioned → **Go to Step 2** to detect project's editor UI system
- If no existing pattern is detected, default to `ui-uitk` for new editor UI
- Only use `ui-imgui` if project exclusively uses IMGUI or user explicitly requests it

If explicit file or keywords found, activate the corresponding skill immediately.

**Step 2: If ambiguous, detect from project:**

Search the project to determine which UI system is in use:

| Look for | Indicates |
|----------|-----------|
| `.uxml` or `.uss` files (including in `/Editor/`) | UI Toolkit (runtime or editor) |
| `UIDocument` components in scenes | UI Toolkit (runtime) |
| Editor scripts with `CreateGUI()` method | UI Toolkit (editor) |
| `Canvas` in scenes/prefabs | uGUI |
| `RectTransform` heavy usage | uGUI |
| Editor scripts with `OnGUI()` or `OnInspectorGUI()` | IMGUI (legacy editor) |

**Step 3: If still unclear, ask or default:**

- For existing projects: detect and follow whichever framework is already in use (Step 2)
- For new projects with no UI yet: ask the user which framework they prefer (UI Toolkit vs uGUI), briefly explaining that UI Toolkit is modern/CSS-like while uGUI is Canvas-based/mature
- For new runtime/game UI where the user has no preference: default to uGUI (`ui-ugui`)
- When the user mentions mobile/performance constraints or older Unity versions (pre-6.0): bias toward uGUI (`ui-ugui`)

## Request Types

Specialized skills handle three types of requests:

| Type | Examples |
|------|----------|
| **Understanding** | "What does this button do?", "How is this laid out?", "Explain this UI" |
| **Editing** | "Change this color", "Add a label here", "Fix this layout" |
| **Generation** | "Create a menu", "Make an inventory screen", "Build a settings panel" |

Route all types to the appropriate specialized skill based on the UI system.

## Available Sub-Skills

### UI Toolkit — `ui-uitk`
- For Unity 6.0+ projects using UI Toolkit (runtime game UI and editor tools)
- **Understands**, **edits**, and **generates** `.uxml` and `.uss` files
- Modern, CSS-like styling approach
- Preferred for new editor windows (CreateGUI) and existing UI Toolkit projects

### uGUI — `ui-ugui`
- For projects using Unity's Canvas-based UI system
- **Understands**, **edits**, and **generates** Canvas hierarchies
- Uses Layout Groups for responsive design
- Default for new runtime/game UI when the user has no framework preference

### IMGUI — `ui-i

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: ui-imgui
description: Generates and modifies Unity IMGUI editor code such as EditorWindows, custom Inspectors, PropertyDrawers, and OnGUI scripts. Use for IMGUI or OnGUI or maintaining existing IMGUI code.
---

**Before proceeding:** If the user is asking about creating a **new** editor window, custom inspector, or PropertyDrawer without explicitly mentioning IMGUI/OnGUI, recommend using UI Toolkit (CreateGUI) instead, as it's the modern approach. Only proceed with IMGUI if:
- User is modifying existing IMGUI code
- User explicitly requests IMGUI/immediate mode
- The project exclusively uses IMGUI for editor tools

When activated, read the reference files:
- [references/templates.md](references/templates.md) — EditorWindow, Inspector, PropertyDrawer templates
- [references/gui-elements.md](references/gui-elements.md) — GUI elements, layout groups, styling

## When to Use This Skill

**IMPORTANT:** This skill is for **legacy IMGUI code only**. Use this skill when:

- User is maintaining/updating **existing** IMGUI editor code (files with `OnGUI()`, `OnInspectorGUI()`)
- User **explicitly requests** IMGUI/immediate mode GUI
- Project exclusively uses IMGUI for all editor tools

**Do NOT use this skill for:**
- New editor windows (use UI Toolkit with `CreateGUI()` instead)
- New custom inspectors (use UI Toolkit instead)
- Requests that don't explicitly mention IMGUI or OnGUI

**Legacy IMGUI is used for:**
- **Editor windows** — `EditorWindow` classes with `OnGUI()`
- **Custom inspectors** — `Editor`, `PropertyDrawer` classes with `OnInspectorGUI()`
- **Debug overlays** — `OnGUI()` in MonoBehaviour (runtime)

IMGUI is **not** for runtime game UI — use UI Toolkit or uGUI instead.

## Scope

**Generate only what is requested (for legacy IMGUI code):**

| Request | Output | Note |
|---------|--------|------|
| Editor window (IMGUI/OnGUI) | `EditorWindow` with `OnGUI()` | Only if explicitly IMGUI |
| Custom inspector (IMGUI) | `Editor` with `OnInspectorGUI()` | Only if explicitly IMGUI |
| Property drawer (IMGUI) | `PropertyDrawer` with `OnGUI()` | Only if explicitly IMGUI |
| Debug overlay | `MonoBehaviour` with `OnGUI()` | Runtime debugging |
| Update existing IMGUI script | Modify existing OnGUI code | Always appropriate |

**Clarify if ambiguous:**
- "inspector" → Custom Editor for a specific type, or PropertyDrawer? **Also ask:** Should this use UI Toolkit (modern) or IMGUI (legacy)?
- "editor window" → **First ask:** Should this use UI Toolkit (modern/CreateGUI) or IMGUI (legacy/OnGUI)?
- "tool window" → EditorWindow with what functionality? Which UI system?

## Conventions

**Follow project patterns first.** Search existing editor scripts before applying defaults.

| Type | Convention | Good | Bad |
|------|------------|------|-----|
| Script names | PascalCase | `MyToolWindow.cs` | `my-tool-window.cs` |
| EditorWindow | `[Name]Window.cs` | `LevelEditorWindow.cs` | `LevelEditor.cs` |
| Custom Editor | `[Type]Editor.cs` | `EnemyEditor.cs` | `EnemyInspector.cs` |
| PropertyDrawer | `[Type]Drawer.cs` | `RangeDrawer.cs` | `RangePropertyDrawer.cs` |
| Location | `Editor` folder | `Assets/Editor/` | `Assets/Scripts/` |

**Editor folder is required** — Scripts using `UnityEditor` namespace must be in an `Editor` folder or they will fail to build.

## Workflow

1. **Analyze** — Determine script type needed (EditorWindow, Editor, PropertyDrawer, etc.)
2. **Search** — Find existing editor scripts to match patterns
3. **Follow project patterns** — Match folder structure and naming
4. **Create script** — Use appropriate base class and attributes
5. **Implement OnGUI** — Build the interface with layout groups

## Script Structure

### EditorWindow
```
[MenuItem attribute] → adds to menu
ShowWindow() static method → opens window
OnGUI() → draws interface
OnEnable/OnDisable → initialization/cleanup
```

### Custom Editor
```
[CustomEditor attribute] → targets component type
OnInspectorGUI() → draws inspector
OnEnable() → cache Seri

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: ui-ugui
description: Understands, edits, and generates Unity uGUI Canvas hierarchies, RectTransforms, Layout Groups, and prefab UI. Use for requests involving Canvas, uGUI, RectTransform, or prefab UI files.
---

Understand existing Unity uGUI, make targeted edits, and generate new Canvas-based hierarchies.

When working with ScrollRect/ScrollView, read the reference file:
- [references/scrollview-setup.md](references/scrollview-setup.md) — Required hierarchy, setup rules, and common failures

## Scope

Determine what the user is asking for:

| Request Type | Action |
|--------------|--------|
| Question about UI | **Understand** — analyze hierarchy, explain structure |
| Change specific element | **Edit** — targeted modification only |
| Create new UI | **Generate** — create new hierarchy |
| Fix/improve existing UI | **Edit** — modify existing, don't rebuild |

**Generate only what is requested:**

| Request | Output |
|---------|--------|
| UI layout | Prefab or scene hierarchy only |
| "with code" / "with logic" / "functional" | Hierarchy + scripts |

**These do NOT imply scripts:**
- "proper buttons" → well-configured Button components
- "working UI" → valid hierarchy that renders
- "menu screen" → visual layout only

## Critical Rules

**Namespace disambiguation:**
- Always use fully qualified type names when creating or referencing UI components
- `UnityEngine.UI.Image`, not `Image`
- `UnityEngine.UI.Button`, not `Button`
- Other namespaces in the project can cause ambiguous type errors

**Verify before modifying:**
- Always check what currently exists before making changes
- Confirm parent objects exist before adding children
- Verify components are present before modifying properties
- Never assume hierarchy state — query it first

**Incremental fixes over rebuilds:**
- When fixing issues, make targeted corrections
- Never destroy and recreate entire hierarchies to fix problems — destroyed objects cause null reference cascades
- Prefer identifying the specific broken property and fixing only that over rewriting large sections
- **When a fix fails, revert the change** before trying an alternative approach

**One change at a time:**
- Make a single change, then verify the result
- Do not batch multiple unrelated modifications
- Be careful not to inadvertently modify or remove adjacent elements when editing a specific one
- If something fails, understand why before trying alternatives
- Avoid "shotgun debugging" with multiple simultaneous changes

**Color and visibility:**
- **Ensure text is readable by default:** When choosing colors, ensure text contrasts with its background — but respect intentional low-contrast uses (disabled states, placeholder text, decorative elements)
- **Check visibility for new elements:** After creating UI elements, verify they have non-zero size and are within parent bounds. Elements intentionally created hidden (for later toggling, animation, etc.) are fine

**Specification adherence:**
- **Honor user specifications exactly:** When the user provides pixel dimensions, hex colors, positions, spacing, or other exact values, apply them precisely — do not approximate or substitute
- **Minimize unrelated changes:** When editing, avoid changing properties the user didn't ask about unless a related adjustment is necessary for the fix to work

## Conventions

**Follow project patterns first.** Search existing files before applying defaults.

| Type | Convention | Good | Bad |
|------|------------|------|-----|
| GameObject names | PascalCase | `SubmitButton` | `submit-button` |
| Prefab paths | Feature folders | `Assets/UI/Inventory/` | `Assets/Prefabs/UI/` |

## Workflow

1. **Verify state** — Check what exists in the scene/hierarchy before any action.
2. **Analyze** — Determine exactly what's needed. No extras.
3. **Search** — Find existing prefabs, canvases, assets. Don't assume paths.
4. **Follow project patterns** — Match folder structure and naming.
5. **Create or edit** — Build struc

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: ui-uitk
description: Understands, edits, and generates Unity UI Toolkit UXML and USS with flex layouts. Use for requests involving UI Toolkit, UIElements, UIDocument, PanelSettings, custom elements, or UI runtime binding.
---

Understand existing Unity UI Toolkit code, make targeted edits, generate new UXML/USS files, Manipulators, and handle UI runtime binding.

## References

Read these as needed:
- [references/uss-guide.md](references/uss-guide.md) — USS patterns and examples
- [references/svg-icons.md](references/svg-icons.md) — SVG icon generation (only when generating icons)
- [references/common-issues.md](references/common-issues.md) — Common mistakes to avoid
- [references/ui-runtime-binding.md](references/ui-runtime-binding.md) — Patterns and guide to bind data to UI at runtime (only when requested or when bindings are involved)
- [references/painter2d.md](references/painter2d.md) — Painter2D API for custom visuals: gradients, shapes, arcs, procedural drawing (read this whenever gradients, custom shapes, progress rings, procedural drawing, or any visual beyond what USS can express is needed)
- [references/pointermanipulator-guide.md](references/pointermanipulator-guide.md) — Patterns and guide to create and use Manipulators (only when requested or when manipulators are involved). This helps with setting up drag and drop features or simple event handling for a Visual Element.
- [references/custom-elements.md](references/custom-elements.md) — Custom UI Element patterns and guide to create reusable components with UXML, USS, and C#. This helps with creating complex UI components for reuse across the project.

Paths are relative to this skill's folder — read `references/uss-guide.md` directly.

## Understanding

When explaining UI structure, use this format:
```
[ElementType] name="elementName" class="class1 class2"
├── [ChildType] name="childName"
│   └── [GrandchildType]
└── [ChildType] class="another-class"
```

## Editing

**Common edit requests:**

| Request | Action |
|---------|--------|
| "Change button color" | Edit USS selector for that button |
| "Add a label here" | Add element to UXML at specified location |
| "Make this bigger" | Edit width/height in USS |
| "Hide this element" | Add `display: none` to USS or remove from UXML |
| "Rename this element" | Update `name` attribute in UXML |

**Don't over-edit:**
- Change only what's requested
- Preserve formatting and structure
- Don't "improve" unrelated code
- Don't add comments unless asked
- For targeted changes, prefer modifying specific elements or selectors over rewriting entire files — but use judgment; if a change touches most of the file, a rewrite may be cleaner
- Be careful not to accidentally drop existing elements, styles, or references when making edits
- **When editing USS**, focus on the properties and selectors relevant to the request — avoid unnecessary reorganization, but restructure if the change genuinely requires it

## Validation

There is no way to validate UXML or USS from outside the Editor — Unity parses these
files on import and reports problems in the Console. Write the files, then have the
user check the result.

**Workflow:**

1. Write the complete file to its target path in the project. Do not write partial or
   draft content — a half-written UXML file is a parse error the moment the Editor
   picks it up.
2. Ask the user to focus the Unity Editor. That triggers a reimport of the changed
   assets.
3. Ask them to report anything in the Console. UXML parse errors name the file and
   line; USS problems appear as warnings about unknown properties or selectors.
4. Fix what they report and repeat from step 1.

**Because feedback costs a user round-trip, get it right the first time:**

- Finish all files before asking the user to check, so one reimport covers everything
  rather than one per file.
- Re-read `references/uss-guide.md` and `references/common-issues.md` before writing,
  rather than after an error comes back.
-

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 7 — file references are metadata, not package contents.

View saved version →

---
name: unity-cli
description: Controls the Unity Editor and projects from the command line, driving a running Editor to edit scenes and assets or run C#. Use when asked to install or manage Editors, licenses, or projects, set up version control, build, test, configure the Unity MCP server, or run any unity command.
allowed-tools:
  - Bash
---

# Unity CLI

**Always use the latest version of the Unity CLI unless you are told to use a
specific version.** Newer releases regularly add commands and output fields
these docs describe, so an outdated CLI fails in ways that read like the docs
being wrong. Check with `unity self-update --check --format json`.

## Drive a running Unity Editor (if one is open)

**If a Unity Editor is open on this machine, this CLI can control it live** — create and modify GameObjects, edit scenes and assets, inspect the hierarchy, and run arbitrary C# — through the project's **Pipeline** package (`com.unity.pipeline`). This runs entirely on your local machine, in your own user account, against your own open Editor: it is not remote access and grants no privilege you don't already have at your own terminal. When an Editor is available, drive it instead of hand-editing scene or asset files.

```bash
unity status                    # confirm a connected Editor (look for state "ready")
unity command                   # list the commands the Editor exposes
unity command editor_play       # run one — e.g. enter Play mode
# Run arbitrary C# — e.g. add a GameObject named "Joe" — when the Editor exposes eval:
unity command eval --caller plugin --skill unity-cli 'new UnityEngine.GameObject("Joe");'
```

**Pass `--caller plugin --skill <name>` on every `unity command` invocation.** `--skill` is the
skill whose instructions produced the call, so a task skill that sends you here passes its own name
rather than `unity-cli`. The flags are inert to the command itself; they only label the invocation.

> **Verifying a running game, not just editing a scene?** Entering Play mode is setup, not proof:
> an unfocused Editor can freeze at frame 1 while `unity status` still reports it as playing, and a
> screenshot can render a frozen frame that looks alive. The ordered recipe for playing, confirming
> the game is actually advancing, capturing the view, reading the console, and tuning it live with
> `eval` is in [playmode-verification-loop.md](references/playmode-verification-loop.md).

### More than one Editor open? Pass `--project-path`

Every Editor-driving command takes `--project-path <path>`. **Pass it whenever more than one Editor may be running** — without it the CLI targets the Editor whose project contains the current directory, so the target follows the shell's cwd:

```bash
unity command editor_play --project-path /path/to/MyProject
```

A `unity status` instance's `project` field is what `--project-path` takes. For `unity command`/`list`/`job`/`mcp`, matching no running project fails with `AMBIGUOUS_EDITOR` and lists the candidates. [Details](references/integration-advanced.md#targeting-one-of-several-running-editors).

Requires the project's `com.unity.pipeline` package (Unity 6.0+) — add it once with `unity pipeline install`. Full details — launching a headless Editor to drive, `unity list` tool discovery, and authoring custom `[CliCommand]` tools — are in [integration-advanced.md](references/integration-advanced.md).

The package also ships a deeper `unity-pipeline` agent skill, invisible to clients inside `Library/PackageCache` — in a project with the package, run `unity skill install <client> --local` once to mirror it beside this skill.

> **Can't connect / commands time out? Check for Safe Mode first.** When a project has C# compile errors, the Editor boots into **Safe Mode**, where the Pipeline package doesn't load — so `unity command`, `unity status`, `unity list`, and `unity recompile` can't connect at all. Note what that means for `unity recompile` specifically: it reports errors you introduce into an 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 13 — file references are metadata, not package contents.

View saved version →

---
name: unity-package-management
description: Adds, removes, upgrades, and discovers Unity (UPM) packages from outside the Editor. Use for headless or CI package installs, verifying package IDs and versions, or choosing which packages a game needs. The Unity CLI doesn't manage packages.
allowed-tools:
  - Bash
  - Read
  - Write
  - Edit
---

# Unity Package Management (headless, via the C# Client API)

Add, remove, upgrade, and discover UPM (Unity Package Manager) packages programmatically with
`UnityEditor.PackageManager.Client`, driven headless from the terminal or CI. Do **not**
hand-edit `Packages/manifest.json` — the Client API resolves dependencies and compatible
versions correctly, whereas manual edits routinely break resolution.

This complements the **`unity-cli`** skill (editor install, project creation, build/test): the
CLI has **no** package-management command, so all package work goes through the Editor's C# API.

## When to use

- Add / remove / upgrade one or more packages in an existing or freshly-created project.
- Set up a project's packages non-interactively in CI.
- Verify a package id exists, or find its available versions, before depending on it.
- Decide which packages a game actually needs — see
  [references/select-packages.md](references/select-packages.md).

## Choosing what to install

Install what the project actually needs, not everything; prefer packages the chosen template
already provides (URP templates already include the render pipeline, Input System, etc.). The
genre / look / platform / monetization → package mapping, plus how to search the registry, is
in [references/select-packages.md](references/select-packages.md). Produce a **deduplicated
list of package ids** and read it back to the user before installing.

## The `-quit` problem — why NOT `unity run` for installs

`Client.Add` / `Client.AddAndRemove` are **asynchronous**: they return a `Request` that only
completes on later `EditorApplication.update` ticks (the UPM child process marshals its result
back on the Editor's main-loop pump, so a blocking `while (!req.IsCompleted)` busy-wait
deadlocks it). The Editor must **stay alive** after `-executeMethod` returns, until the request
finishes.

`unity run` **cannot** be used for the installer: its default path injects `-quit` (see the reserved
flags in the **`unity-cli`** skill). With `-quit`, the Editor quits the instant the method
returns — before UPM resolves — so packages never install and the callback never runs.

**Solution:** launch the **Editor binary directly** in `-batchmode` **without** `-quit`. The
Editor stays alive, `EditorApplication.update` keeps ticking, the poll callback runs, and it
calls `EditorApplication.Exit(code)` itself when done — which both quits and sets the process
exit code.

## The installer script

Write this to `Assets/Editor/ProjectBootstrap/PackageInstaller.cs`. It must live under an
`Editor/` folder (or an Editor-only assembly) because it uses `UnityEditor`.

```csharp
using System.Linq;
using UnityEditor;
using UnityEditor.PackageManager;
using UnityEditor.PackageManager.Requests;
using UnityEngine;

namespace ProjectBootstrap
{
    // Installs (and optionally removes) a fixed set of packages via the PackageManager
    // Client API, headless-safe.
    public static class PackageInstaller
    {
        // EDIT this list to match the package selection (see references/select-packages.md).
        static readonly string[] PackagesToAdd =
        {
            "com.unity.inputsystem",
            "com.unity.cinemachine",
            "com.unity.render-pipelines.universal",
            // "com.unity.package@1.2.3"  // pin a version with @ when a minimum is required
        };

        // Optionally drop packages in the same resolution pass (e.g. a template default you don't want).
        static readonly string[] PackagesToRemove = { };

        const double TimeoutSeconds = 600; // UPM resolution + downloads can be slow

        static AddAndRemoveRequest

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: urp-postprocessing
description: Sets up, configures, and debugs URP post-processing with the Volume framework. Use for bloom, tonemapping, color adjustments, depth of field, vignette, or other Volume overrides.
required_packages:
  com.unity.render-pipelines.universal: ">=14.0.0"
---

Help the user set up, configure, and debug post-processing effects using URP's Volume framework.

**Goal: The user should have a working visual result with zero console errors after setup.**

## 0. Prerequisite: an Editor you can run C# in

Volume profiles, `VolumeParameter.overrideState`, and the camera's post-processing flags are
Editor/runtime object state — the checks and edits below all run C# inside a live Editor.

**The `unity-cli` skill owns getting you there** — installing the CLI, confirming a connected
Editor, adding the project's `com.unity.pipeline` package, telling a genuinely absent Editor
apart from one stuck in Safe Mode, and discovering the Editor's command catalog. Follow it
first; don't re-derive any of it here. You need `eval` in particular, not just a reachable
Editor: its presence depends on the Pipeline package version, not on the CLI. If it's
missing, say so and stop.

Run C# through the connected Editor with the `eval` command. Discover its parameter shape
from `unity command --format json` rather than assuming one — the inline form is
`unity command eval --caller plugin --skill urp-postprocessing --code '<snippet>'`, and some Pipeline versions also register
`eval_file` for running a snippet from a file. **Check the catalog before reaching for
`eval_file`; it is frequently absent.** `unity command` defaults to a 30 second timeout.

### Passing C# to `eval`

`eval` compiles a **statement block, not a file**. Two consequences, both of which cause a
compile error rather than a warning:

- **No `using` directives.** The compiler reads `using UnityEngine;` as a resource-disposal
  statement and rejects it (`CS0210`).
- **Types must be fully qualified.** A bare `AssetDatabase` or `Volume` does not resolve
  (`CS0246` / `CS0103`), and a bare `Object` is ambiguous with `object` (`CS0104`).

Where a snippet below is written as a file — with usings, for readability, or because it is
meant to be saved into the project — qualify the types before passing it to `eval`.

## 0. Pre-Flight Checks

Before configuring any effect, **verify all checks**. Fix failures first.

1. **URP is the active render pipeline** — If not, inform the user and stop.
2. **HDR is enabled on the URP Asset** — Required for Tonemapping. Bloom works best with HDR; in SDR it still works but `threshold` must be < 1.
3. **Camera has post-processing enabled** — `renderPostProcessing` must be `true` (defaults to `false`). Camera Stacking: only a `CameraRenderType.Base` camera (or the last `Overlay` in the stack) should enable post-processing. Also verify the Renderer's PostProcessData asset is not null — if it is, the post-process pass won't exist.
4. **The Volume's GameObject layer is in the Camera's Volume Layer Mask** — `volumeLayerMask` defaults to layer 0 "Default" only. The Volume's `GameObject.layer` must be included, otherwise the camera ignores it.
5. **Volume exists with `enabled = true`, a valid Profile, and at least one override** — The `Volume` component must be enabled, have a non-null `profile` (or `sharedProfile`), and at least one `VolumeComponent` with `overrideState = true` on its properties.

### Pre-Flight Check Snippet

Run this to verify the setup programmatically:

```csharp
// `eval` compiles a statement block, not a file: no `using` directives are
// allowed, so every type is fully qualified.
var report = new System.Text.StringBuilder();

// 1. Check URP is active — a hard stop, so throw: it fails the eval loudly
var urpAsset = UnityEngine.Rendering.Universal.UniversalRenderPipeline.asset;
if (urpAsset == null)
    throw new System.Exception("URP is not the active render pipeline.");

// 2. Check HDR
if (!urpAsset.supportsHDR)
    r

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
name: validate-urp-render-graph-renderer-feature
description: Reviews a Unity 6 URP ScriptableRendererFeature that uses the Render Graph API, checking resource wiring, material binding, execution structure, and best practices. Use to validate a renderer feature.
---
# Skill: Validate a Unity URP Render Graph Renderer Feature

## Purpose
Review a Unity 6+ URP Render Graph `ScriptableRendererFeature` and its associated pass implementation for correctness issues related to material binding, resource wiring, render graph texture creation, static render function structure, global resource exposure, and API/version usage.

## When to Use
Use this skill when:
- reviewing AI-generated Unity URP Render Graph renderer feature code
- validating a custom `ScriptableRendererFeature` before integrating it
- checking for common Render Graph resource wiring and pass setup mistakes
- diagnosing suspicious but plausible Render Graph pass implementations
- reviewing whether a custom raster/blit/copy pass uses the most appropriate Render Graph helper APIs

## Inputs
The skill should expect:
- **Unity version**
- **URP version**
- **Render Graph renderer feature code to review**
  - `ScriptableRendererFeature`
  - associated pass code
  - or both
- **Intended behavior**
- **Expected inputs/outputs**, if known
- **Optional constraints**
  - project conventions
  - required pass type
  - known resources
  - required material/shader properties

## Output Format
The skill must return results in the following structure:

### 1. Validation Summary
A short overall assessment of the implementation.

### 2. Confirmed Issues
Concrete issues directly supported by the provided code.

### 3. Likely Issues / Risky Assumptions
Potential issues that depend on missing context or incomplete information.

### 4. Recommended Fixes
Minimal targeted fixes for each issue.

### 5. Corrected Snippets
Small corrected code snippets where useful.

### 6. Missing Information
Any information needed to validate the code with higher confidence.

## Validation Checklist

### 1. Material Binding
Check that:
- materials are declared clearly
- serialized materials are exposed correctly when needed
- materials are passed into the pass correctly
- null handling exists where required
- declared materials are actually used
- **all required material inputs are bound before execution**
- **the primary input texture is explicitly bound when the shader expects one**
- auxiliary textures and parameter textures are also bound explicitly
- texture/property binding matches the shader’s expected property names

Flag as an issue when:
- a material is declared or passed but not actually used
- only secondary textures or parameters are bound while the main input texture is omitted
- the pass binds a mask/noise/auxiliary texture but fails to bind the primary color/input texture
- required shader properties are assumed to exist without being set
- property names are inconsistent or ambiguous
- the code relies on implicit main texture binding when explicit binding is required by the pass pattern

Prefer patterns where:
1. the material is created or assigned clearly
2. the primary source texture is bound explicitly
3. all auxiliary textures are bound explicitly
4. property names are consistent and intentional
5. null or missing-resource cases are handled or reported

### 2. Texture Resource Wiring
Check that:
- sampled/read textures, write targets, and auxiliary textures are clearly distinguished
- textures used with `UseTexture(...)` are appropriate for read access
- textures used with `SetRenderAttachment(...)` are appropriate as write targets
- source, destination, and auxiliary resources are not confused
- all expected textures are explicitly wired
- texture property names are explicit and consistent when materials are involved
- the implementation does not invent texture availability
- multi-texture resource usage is handled explicitly rather than implicitly

Flag as an issue when:
- a texture

Preview of the first 4,000 characters. Read full instructions →