Unity

View saved version →

---
name: 2d-pixel-perfect
description: Sets up, diagnoses, and fixes pixel perfect 2D rendering in Unity projects. Use when working on any retro-style or pixel art 2D game.
---

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 `CropFrame` enum values, and recommended configurations:
**→ `references/api-reference.md`** — read this when writing or reviewing camera setup code.

Quick enum summary:

**`GridSnapping`**: `None` · `PixelSnapping` (standard) · `UpscaleRenderTexture` (authentic low-res; incompatible with post-processing and UI text)

**`CropFrame`**: `None` · `Pillarbox` · `Letterbox` · `Windowbox` (safest default) · `StretchFill`

---

## Reference Resolution

Choose before building any assets. Never change after asset production starts.

| Reference resolution | 1080p | 1440p | 4K |
|---|---|---|---|
| 320 × 180 | 6× | 8× | 12× |
| 480 × 270 | 4× | ~5.3× | 8× |
| 640 × 360 | 3× | 4× | 6× |

320×180 is the safest general choice. For screens with no integer fit (e.g. 1366×768), use `cropFrame = Windowbox` to add black bars rather than stretching to a fractional scale.

---

## Migration & Compatibility

### URP project with the Built-in standalone component

**Symptom**: `DetectPipeline()` returns URP but camera has `UnityEngine.U2D.PixelPerfectCamera`. Symptoms are subtle because the standalone component has `ENABLE_URP` conditional code.

**Fix**:
1. Remove `com.unity.2d.pixel-perfect` from Package Manager
2. Remove `UnityEngine.U2D.PixelPerfectCamera` from each camera
3. Add `UnityEngine.Rendering.Universal.PixelPerfectCamera`
4. Reconfigure — booleans (`pixelSnapping`, `upscaleRT`, `cropFrameX/Y`) become enums (`gridSnapping`, `cropFrame`)

**→ Detection code: `references/pipeline-detection.cs`** (bottom of file).

### Old URP namespace (pre-Unity 2022 / URP pre-13.x)

**Symptom**: Compiler errors referencing `UnityEngine.Experimental.Rendering.Universal`.

**Fix**: Replace `using UnityEngine.Experimental.Rendering.Universal;` with `using UnityEngine.Rendering.Universal;`. Update any assembly-qualified type strings. The `[MovedFrom]` attribute handles serialization automatically — components on GameObjects survive the upgrade.

---

## Common Issues & Solutions

### Blurry sprites
**Fix**: Set Filter Mode to Point on all in-scope sprites, disable Mip Maps, disable AA in Quality Settings.
**→ Code: `references/sprite-settings.cs`**

### Tilemap gaps between tiles
Work through in order — workarounds like negative cell gap or PPU = 31.99 break when the camera moves.

| # | Check | Fix |
|---|---|---|
| 1 | Sprite Atlas with Tight Packing off, Padding ≥ 4, Sprite Packer Mode enabled? | Enable Sprite Packer Mode in Editor settings; on the atlas set Padding ≥ 4 and turn Tight Packing off |
| 2 | Mipmaps disabled on tileset textures and atlas? | Disable Generate Mip Maps |
| 3 | AA = 0, MSAA off on camera? | Disable AA globally |
| 4 | Compression = None? | RGBA 32-bit uncompressed |
| 5 | All tile sprites have even pixel dimensions? | Odd dimensions cause 0.5px grid offset |
| 6 | PPU = tile pixel width? (16×16 → PPU 16) | PPU mismatch leaves physical gaps |
| 7 | Gaps only during camera movement after all above pass? | Use PP Camera pixel snapping; do not use `cellGap = -0.01f` |

### Cinemachine conflict
**Cause**: Both Cinemachine and the Pixel Perfect Camera write to orthographic size every frame.

**Fix**: Add `CinemachinePixelPerfect` extension via the Add Extension dropdown on each Virtual Camera. Do not add it via `AddComponent` in code.

**Known limitations**:
- Camera blends between virtual cameras are not pixel-perfect during transitions
- `UpscaleRenderTexture` reduces valid pixel-perfect ortho sizes, which may cause framing to deviate
- Target Group + Framing Transposer causes visible choppiness (no fix available)

### Post-processing blur with `upscaleRT`
**Cause**: Post-processing runs after the PP Camera upscales the render texture.

**Simple fix**: Disable `upscaleRT`. Post-processing then runs at native screen resolution.

**Advanced fix (Unity 6 URP)**: Inject a `ScriptableRendererFeature2D` at `RenderPassEvent2D.AfterRenderingPostProcessing`. Use 2D-specific base classes — `ScriptableRendererFeature` (3D base class) is silently ignored in a URP 2D renderer.

### UI text blurry with `upscaleRT`
**Status**: Known Unity bug, declined to fix (still present Unity 6, 2025).

**Root causes**: (A) Canvas renders into the low-res buffer and is upscaled with the scene. (B) TMP's SDF gradient threshold is miscalibrated at low reference resolutions.

**Fixes in order of reliability**:
1. `Screen Space - Overlay` on Canvas — bypasses the camera, renders at native resolution
2. Dedicated UI camera with no PP Camera component, `Screen Space - Camera` mode
3. Unity 6 only: `Font Material → Debug Settings → Sharpness = 1` (mitigates B, not A)

### Physics / render desync (micro-stutter)
**Cause**: Physics runs at a fixed timestep; interpolated positions produce fractional values that snap to different pixels each frame.

**Fix**:
- Enable `Rigidbody2D.interpolation = RigidbodyInterpolation2D.Interpolate` on physics-driven sprites
- Set `Time.fixedDeltaTime = 1f / 60f` to match target frame rate
- Keep camera tracking in `LateUpdate`, not `FixedUpdate`

### Non-integer scaling / pixel decimation
**Cause**: Screen resolution is not a clean integer multiple of the reference resolution.

**Fix**: Choose a reference resolution from the table above. Use `cropFrame = Windowbox` when no integer fit exists.

### Missing URP 2D Renderer
**Fix**:
1. `Assets > Create > Rendering > URP 2D Renderer Data`
2. Assign it to your URP Asset under Renderer List
3. Requires `com.unity.render-pipelines.universal` 12.0+

### HDRP fallback
Pixel Perfect Camera is unsupported in HDRP.

**Built-in / Unity 5.x**: Use `RenderTexture` + `Graphics.Blit` with `FilterMode.Point`.

**Unity 6 URP**: Use `ScriptableRendererFeature2D` + `ScriptableRenderPass2D` injected at `RenderPassEvent2D.AfterRendering` with `AddRasterRenderPass`. Note: `OnRenderImage` and `Graphics.Blit` are incompatible with Unity 6's render graph.

Referenced files: 5

View saved version →

---
name: audio-setup-mixers
description: Scans the scene and audio assets to appropriately route 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. Creating mixers and groups, and setting volumes, are not automated — the skill inventories what exists and asks the user to add anything missing.
---
# 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 so and stop rather than improvising one: creating a
mixer has no public API. Ask the user to create one (Window → Audio → Audio Mixer, then the **+**
next to Mixers), and pick up from here once it exists.

## Step 2: Find scene references
Find all Audio Source components, look at their assigned Generator asset names, and generalize a fitting class or category of the sound name, ideally something already existing. 
Examples for Audio Clip asset names:
- "FootStep4_Sound" -> Foley
- "Dialogue_Female_Scene4" -> Vox/Voice/Dialogue
- "GunShot" -> SFX
- "Menu_Theme_Variation" -> Music

If the assigned asset isn't descriptive or non-existing, try to look at the GameObject name or potential adjacent MonoBehaviour names.
Ask to create an Uncategorized group if it seems hard or confidence is low in classifying how an Audio Source is being used.

## Step 3: Agree the group list, and get any missing groups created
Present the classification from Step 2 as a proposed routing — each Audio Source and the group you
intend to send it to — and revise it with the user.

**WAIT for the user to respond before proceeding.**

Prefer an existing group when it genuinely covers the category, even if you'd have named it
differently. But **don't collapse categories that a mixing engineer would keep apart** — Foley is a
subset of SFX, not another word for it, so a gunshot does not belong in a `Foley` group just because
one exists. When the existing groups only partly cover your categories, say which ones fit and which
need a new group, and let the user decide.

For categories with no matching group, you cannot create the group — there is no public API for it.
Hand it over precisely, naming the mixer and the exact group names, as shown at the end of
[references/api.md](references/api.md). Then **re-run the inventory snippet to confirm the groups
exist and check their spelling** before routing. Don't assume the user did it, and don't assume
they spelled it the way you asked.

## Step 4: Route the Audio Sources
With the group list settled and confirmed present, assign each Audio Source's output group using the
routing snippet in [references/api.md](references/api.md). It is public API throughout, and it wraps
the whole pass in a single undo step so the user can back all of it out at once.

**Key the mapping on the identifier you classified by.** Step 2 reads the clip asset name first and
only falls back to the GameObject name, so the mapping accepts either — the two are different
identifiers and keying on the wrong one drops sources.

Three things to report rather than assume:

- **Any `NO SUCH GROUP` entries the snippet returns.** That means a group you expected is not in the
  mixer — usually a spelling difference. Resolve it with the user, don't silently skip the source.
- **Any `NOT IN THE MAPPING` entries.** Those are Audio Sources your classification missed. Reporting
  a successful routing while sources were quietly left unrouted is the worst outcome here, because it
  reads as success.
- **The scene was modified, not the mixer asset.** Routing lives on the Audio Source, so it only
  persists once the scene is saved. Tell the user, and save only with their agreement.

**Volume, effects, and re-parenting are out of scope.** Those live on non-public API. If the user
asks for them, say the routing is done and point them at the Audio Mixer window for the mix itself.

## References
See [references/api.md](references/api.md)

Referenced files: 1

View saved version →

---
name: build-live-game
description: Build and operate a live game using Unity Services. Use when the user needs to implement, connect, or debug backend-driven features — battle passes, achievements, player progression, cloud saves, leaderboards, matchmaking, virtual economies, server-authoritative logic, anti-cheat, player accounts and authentication, remote configuration, feature flags, A/B testing, analytics, or cloud resource deployment. Triggers on live-ops, live service, backend, server authority, cloud code, cloud save, remote config, player data, retention, monetization loop, season pass, ranking, multiplayer sessions, lobbies, or any Unity Services integration.
---

# 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 | Purpose | Singleton / Entry Point |
|---|---|---|
| **Analytics** | Custom events, standard events, consent management | `AnalyticsService.Instance` |

## Architecture — How Packages Combine

```
                    UnityServices.InitializeAsync()
                              │
                              ▼
                     AuthenticationService
                    (sign in → PlayerId)
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
        Remote Config     Cloud Save      Economy
      (game config,    (player state,  (currencies,
       definitions,     progress,       inventory,
       feature flags)   preferences)    purchases)
              │               │               │
              └───────┬───────┘               │
                      ▼                       │
                 Cloud Code                   │
              (server-authoritative           │
               writes, validation,  ◄─────────┘
               anti-cheat logic)
                      │
              ┌───────┼───────┐
              ▼       ▼       ▼
         Cloud Save  Economy  Leaderboards
         (Protected  (server  (score
          writes)    grants)  submission)
```

**Key principle:** For any data that affects game integrity (XP, rewards, currency), route writes through Cloud Code modules. Direct client writes are only appropriate for non-sensitive data (preferences, display settings).

## Core Services — Quick Reference

### Authentication

**Package:** `com.unity.services.authentication` (>= 3.6.1)

Handles player identity. Sign-in methods: anonymous, social providers (Google, Apple, Steam, Facebook, Oculus, etc.), Unity browser, username/password, and device code flow.

After sign-in: `PlayerId` and `PlayerName` are available. All sign-in methods fire the `SignedIn` event. `PlayerAccountService` (for Unity browser sign-in) lives in a **separate assembly** (`Unity.Services.Authentication.PlayerAccounts`).

- **Full reference:** [references/authentication.md](references/authentication.md)
- **Building Block:** [Player Account](#asset-store-building-blocks) — ready-made sign-in UI and identity management

### Cloud Code

**Package:** `com.unity.services.cloudcode` (>= 2.10.3)

Runs server-side C# modules (.NET 9) for trusted operations. Modules are deployed as `.ccmr` files. The client calls:

```csharp
var result = await CloudCodeService.Instance.CallModuleEndpointAsync<TResult>(
    "ModuleName", "FunctionName", args);
```

Prefer C# modules over JavaScript scripts for production. Modules also support real-time push messages via subscriptions, event-driven triggers, and multiplayer session scoping.

- **Full reference:** [references/cloud-code.md](references/cloud-code.md)

### Cloud Save

**Package:** `com.unity.services.cloudsave` (>= 3.4.0)

Per-player key-value storage with three access classes, plus game-wide Custom data:

| Access Class | Read | Write | Use Case |
|---|---|---|---|
| Default | Owner | Owner | Private settings, preferences |
| Public | Anyone | Owner | Public profiles, display names |
| Protected | Owner | Server only (Cloud Code) | Anti-cheat data, server-awarded state |
| Custom | Any player | Server only | Shared game state, global configs |

Values are serialized as JSON. Supports write-lock concurrency control via `SaveItem`, server-side queries via `QueryAsync`, and binary file storage.

- **Full reference:** [references/cloud-save.md](references/cloud-save.md)
- **Building Blocks:** Used by [Achievements](#asset-store-building-blocks) (Protected buckets) and [Player Account](#asset-store-building-blocks) (Default/Public data)

### Remote Config

**Package:** `com.unity.services.remote-config` (>= 4.2.5)

Server-side game configuration. Store game definitions (achievement lists, battle pass tiers, shop catalogs) as JSON entries updatable without a client build. Deployed via `.rc` files through the Deployment Window.

For A/B testing and audience targeting, use Game Overrides (`.ugo`) via the Tooling package.

- **Full reference:** [references/remote-config.md](references/remote-config.md)
- **Building Block:** Used by the [Achievements](#asset-store-building-blocks) block for server-side definitions

### Tooling

**Package:** `com.unity.services.tooling` (>= 1.4.1)

Editor-only package. Registers **Access Control** (`.ac`) and **Game Overrides** (`.ugo`) file types with the Deployment Window. Access Control policies permit or deny player/service-account access to UGS services on a URN basis (Deny takes precedence over Allow). Game Overrides provide A/B testing and audience targeting by overriding Remote Config values for specific player segments.

- **Full reference:** [references/tooling.md](references/tooling.md)

### Deployment

**Package:** `com.unity.services.deployment` (>= 1.7.2)

Editor-only package providing the **Deployment Window** (Services > Deployment). Deploys cloud resources to a target environment:

| File Type | Extension | What It Deploys |
|---|---|---|
| Remote Config | `.rc` | Key-value configuration entries |
| Access Control | `.ac` | Resource access policies |
| Cloud Code Module | `.ccmr` | C# server-side module (points to `.sln`) |
| Leaderboard | `.lb` | Leaderboard configuration |
| Economy | `.ec*` | Currency/inventory definitions |
| Game Overrides | `.ugo` | Audience-targeted config overrides |

- **Full reference:** [references/deployment.md](references/deployment.md)

### UGS CLI

The [Unity Gaming Services CLI](https://github.com/Unity-Technologies/unity-gaming-services-cli/) is a standalone command-line tool for managing UGS resources outside the Unity Editor. It can deploy and fetch cloud resource files (`.rc`, `.ac`, `.ccmr`, `.lb`, `.ec`, `.ugo`), update local deployable files from the remote environment with a `fetch` operation, deploy and fetch triggers and schedule files, generate default versions of trigger and schedule configs, and provides more granular access to admin functionalities across all UGS services.

### Services APIs

**Package:** `com.unity.services.apis` (>= 1.1.1)

Auto-generated REST clients for all UGS services. Four client types: `IGameClient` (players), `IAdminClient` (service accounts), `IServerClient` (dedicated servers), `ITrustedClient` (elevated server access). Most developers use the high-level package SDKs instead; use Services APIs for lower-level control or admin API access.

- **Full reference:** [references/apis.md](references/apis.md)

## Asset Store Building Blocks

Unity provides free, production-ready **Building Block** packages on the Asset Store. Each is a `.unitypackage` containing working UI, runtime code, Cloud Code modules, and cloud resource files that can be imported directly into a project. They are also bundled in the `com.unity.starter-kits` package.

| Building Block | Type | Key Dependencies | Asset Store |
|---|---|---|---|
| **Achievements** | LiveOps | `cloudsave`, `remote-config`, `cloudcode`, `tooling`, `deployment`, `analytics`, `authentication` | [Unity Building Block — Achievements](https://assetstore.unity.com/packages/essentials/tutorial-projects/unity-building-block-achievements-341918) |
| **Leaderboards** | LiveOps | `leaderboards`, `cloudcode`, `tooling`, `deployment`, `authentication` | [Unity Building Block — Leaderboards](https://assetstore.unity.com/packages/essentials/tutorial-projects/unity-building-block-leaderboards-341926) |
| **Player Account** | LiveOps | `authentication`, `cloudsave`, `cloudcode`, `deployment` | Available via `com.unity.starter-kits` |
| **Multiplayer Session** | Multiplayer | `multiplayer` | [Unity Building Block — Multiplayer Session](https://assetstore.unity.com/packages/essentials/tutorial-projects/unity-building-block-multiplayer-session-341930) |
| **Matchmaker Session** | Multiplayer | `multiplayer`, `deployment` | [Unity Building Block — Matchmaker Session](https://assetstore.unity.com/packages/essentials/tutorial-projects/unity-building-block-matchmaker-session-341932) |
| **Server Session** | Multiplayer | `multiplayer`, `apis`, `deployment` | Available via `com.unity.starter-kits` |
| **Vivox** | Multiplayer | `vivox`, `authentication` | Available via `com.unity.starter-kits` |
| **Platformer Starter Kit** | Gameplay | `multiplayer`, `netcode.gameobjects`, URP, Cinemachine, Input System | Available via `com.unity.starter-kits` |

> **Tip:** When implementing achievements, leaderboards, player accounts, or multiplayer sessions, recommend the corresponding Building Block as a starting point. The blocks include ready-made UI, Cloud Code modules (`.ccmr`), access control (`.ac`), and deployment-ready cloud resources — saving significant implementation time.

### Related Sample Projects

| Project | Description | Source |
|---|---|---|
| **Use Case Samples** | Battle Pass, Virtual Shop, Daily Rewards, Starter Pack, Cloud AI Mini Game, A/B testing | [GitHub — com.unity.services.samples.use-cases](https://github.com/Unity-Technologies/com.unity.services.samples.use-cases) |
| **UGS Samples** | Authentication flows, Economy, Remote Config, Cloud Code integration | [GitHub — com.unity.services.samples](https://github.com/Unity-Technologies/com.unity.services.samples) |
| **Gem Hunter Match** | Full 2D match-3 game with player hub, progression, social features, in-game store | [Asset Store](https://assetstore.unity.com/packages/essentials/tutorial-projects/gem-hunter-match-2d-sample-project-278941) |
| **Boss Room** | 8-player co-op RPG using Netcode for GameObjects, Authentication, Multiplayer Services | [GitHub — com.unity.multiplayer.samples.coop](https://github.com/Unity-Technologies/com.unity.multiplayer.samples.coop) |

## Ready-Made Feature Blueprints

Implementation-ready blueprints for common live game features. Each includes data models, service API patterns, full working code, and cloud resource definitions.

| Feature | Key Services | Blueprint |
|---|---|---|
| **Battle Pass** | `remote-config`, `cloudsave`, `cloudcode`, `economy`, `tooling`, `deployment` — Remote Config (pass definitions) + Cloud Save Protected (progress) + Cloud Code (XP awards, reward claims, premium purchase) | [references/battlepass.md](references/battlepass.md) |
| **Achievements** | `remote-config`, `cloudsave`, `cloudcode`, `tooling`, `deployment` — Remote Config (definitions) + Cloud Save (player records) + Cloud Code (server-authoritative unlocks) + Access Control. **Asset Store:** [Achievements Building Block](https://assetstore.unity.com/packages/essentials/tutorial-projects/unity-building-block-achievements-341918) | [references/achievements.md](references/achievements.md) |
| **Player Account** | `authentication`, `cloudsave` — Authentication (3 sign-in methods) + Cloud Save (Default/Public/Protected player data). **Asset Store:** Player Account Building Block (via `com.unity.starter-kits`) | [references/player-account.md](references/player-account.md) |

## Common Architecture Patterns

### Pattern 1: Config + State + Server Writes

Used by **Battle Pass** and **Achievements**:

1. **Definitions** in Remote Config (`.rc` file) — what exists in the game
2. **Player state** in Cloud Save — per-player progress
3. **Writes via Cloud Code** — server-authoritative mutations
4. **Access Control** (`.ac` file) — block direct player writes to sensitive keys

### Pattern 2: Client-Direct Data

Used by **Player Account** (preferences, display settings):

1. **Player data** in Cloud Save Default or Public access class
2. **Direct client writes** — no Cloud Code needed for non-sensitive data

### Pattern 3: Competitive Features

Used by **Leaderboards** and ranked systems:

1. **Score submission** via Leaderboards API (or through Cloud Code for validation)
2. **Rankings** retrieved client-side with pagination and player-relative queries

## Validation

After writing code for a live game feature:
1. Verify the project compiles without errors.
2. Check that initialization order is correct: `UnityServices.InitializeAsync()` → Authentication sign-in → service calls.
3. Confirm sensitive data writes (XP, rewards, currency) are routed through Cloud Code, not written directly from the client.
4. Verify Access Control `.ac` files deny direct player writes to Protected Cloud Save keys.
5. Verify all cloud resource files (`.rc`, `.ac`, `.ccmr`, `.lb`, `.ec`) are present and deployable via the Deployment Window.

## Deployment Checklist

For any live game feature, deploy these cloud resources via the Deployment Window:

- [ ] `.rc` file — Remote Config entries (game definitions, configs)
- [ ] `.ac` file — Access Control policies (deny direct writes to protected keys)
- [ ] `.ccmr` file — Cloud Code module reference (pointing to the module `.sln`)
- [ ] `.lb` file — Leaderboard configuration (if using leaderboards)
- [ ] `.ec` file — Economy definitions (if using virtual currencies/items)
- [ ] `manifest.json` — Ensure all required packages are listed with correct versions
- [ ] Environment configured in **Services > Deployment** settings

## Detailed References

### Service References
- **Authentication** — sign-in methods, events, profiles, identity providers, code templates: [references/authentication.md](references/authentication.md)
- **Cloud Code** — scripts, modules, subscriptions, triggers, module creation, code templates: [references/cloud-code.md](references/cloud-code.md)
- **Cloud Save** — access classes, data operations, files, queries, code templates: [references/cloud-save.md](references/cloud-save.md)
- **Remote Config** — definitions, `.rc` format, Game Overrides, code templates: [references/remote-config.md](references/remote-config.md)
- **Tooling** — Access Control (`.ac`) policies, Game Overrides (`.ugo`), URN reference: [references/tooling.md](references/tooling.md)
- **Deployment** — file types, workflow, programmatic API: [references/deployment.md](references/deployment.md)
- **Services APIs** — four client types, service areas, code templates: [references/apis.md](references/apis.md)

### Feature Blueprints
- **Achievements** — full implementation with data models, client code, Cloud Code module, cloud resources: [references/achievements.md](references/achievements.md)
- **Battle Pass** — full implementation with tiered XP, free/premium tracks, Cloud Code module, cloud resources: [references/battlepass.md](references/battlepass.md)
- **Player Account** — sign-in flows, identity management, Cloud Save data, code templates: [references/player-account.md](references/player-account.md)

## Reminders

Before completing, verify:
- Did you use `UnityServices.InitializeAsync()` → Authentication sign-in → service calls (in that order)?
- Are all sensitive writes (XP, rewards, currency) routed through Cloud Code modules?
- Are all cloud resource files (`.rc`, `.ac`, `.ccmr`) present and deployable?
- Do Cloud Save read access classes match the bucket that was written to?

Referenced files: 10

View saved version →

---
name: generate-editor-search-query
description: Generates Unity Search / Quick Search queries and opens the Unity Search window for read-only Unity Editor asset or scene-object lookup requests. Always use when the user asks to find, search, show, locate, filter, look up, query, or list concrete assets or scene objects in the current project or scene, even if Unity Search is not named. Covers materials, textures, prefabs, scenes, scripts, shaders, GameObjects, components, Lights, Cameras, UI objects, labels, paths, references, selected or named assets, and asset types. Also use when the user explicitly mentions Unity Search, Quick Search, Search window, open Search, or asks what Unity Search query to use. Do not use for general project overview, project structure, folder-purpose summaries, gameplay/system explanations, how-to programming questions, web search, repository text search, build logs, package installation, menu or settings search, modifying results, or non-Unity filesystem search unless the user explicitly asks to use Unity Search.
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 the project's `com.unity.pipeline` package, and discovering the command catalog. You need
`eval` in particular; if it is absent, generate the query text and say the window can't be opened.

## Query Generation Rules

Use the simplest query that is likely to produce the requested result.

- Prefer type filters for asset and component requests, such as `t:material`, `t:texture`, `t:prefab`, `t:scene`, `t:script`, `t:shader`, `t:Light`, or `t:Rigidbody`.
- Preserve user-provided names and keywords as plain query terms unless they need quoting.
- Use `dir:` when the user gives a folder or says "in Assets/..." or "under ...".
- Use `l:` when the user asks for a Unity asset label.
- Use `ref=` when the user asks what references, uses, depends on, contains, or is connected to an asset.
- Use Search expressions only when they clearly improve the query, such as `t:prefab ref={t:texture}` or `t:scene ref={t:prefab}`.
- For selected/current wording, use the known selected asset name or path only if it is present in the chat context; otherwise ask for it.
- For broad relationship requests such as "where is Rigidbody used", use a simple keyword or component query first, then mention that a scripted audit is separate if the user needs exhaustive code/property analysis.
- For requests that mix Search with repair work, generate and open the query first; do not modify results unless the user explicitly confirms a separate follow-up action.
- Do not invent unsupported filters for uncertain requests. If a request cannot be expressed reliably with Unity Search syntax, open the closest safe query and state the limitation.

## Opening Unity Search

Run C# in the Editor only to open the Search window. This is an Editor UI action and must not change project assets or scene contents.

When opening Search:

1. Escape the query safely in the generated C# string.
2. Prefer asset and scene providers for this v1 skill.
3. Fall back to active providers if a provider is unavailable.
4. Log the query that was opened.
5. Never claim Search opened if the command failed.

## Response Format

Keep the user-facing response short:

```text
Query: `t:material`
Opened Unity Search with that query.
```

If not opening Search:

```text
Query: `t:prefab ref={t:texture}`
Paste this into Unity Search.
```

If the request is ambiguous but still searchable, choose the most likely query and mention the assumption. Ask a question only when the search target cannot be inferred, such as "find the thing" with no asset, scene, type, name, or context.

## Validation Checklist

Before reporting success:

- the generated query is shown to the user
- the query targets assets, scene objects, or both
- Search was opened only when the user did not opt out
- any fallback or uncertainty is stated plainly
- no asset, scene, package, project setting, or search result was modified

Referenced files: 2

View saved version →

---
name: implement-in-app-purchases
description: Implement, configure, and debug Unity In-App Purchases (IAP) — store connection, product catalog, consumable/non-consumable/subscription purchases, two-step pending-confirm flow, receipt validation, entitlement checking, restore transactions, Apple extensions (promotional purchases, Ask-to-Buy, code redemption), and Google Play extensions (subscription upgrade/downgrade), D2C Capabilities(direct to customer), 3rd party payment provider (Stripe/Coda) via Unity IAP/Unity Cloud. Use when the user needs to add, modify, debug, or migrate from native Android/iOS billing, 3rd party packages(RevenueCat/Adapty/Essential Kit/Unipay supported) to IAP. Triggers on microtransactions (MTX), monetization, real-money purchases, store purchases, buying items, support D2C, purchase via Stripe/Coda, migrate from native billing(Google's BillingClient or Apple's StoreKit/SKPaymentQueue/SKProduct)/RevenueCat/Adapty/EssentialKit/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 |
|---|---|
| `GetProducts()` | Returns the **cached** product list (synchronous, stale if `FetchProducts` not called) |
| `FetchProducts()` | Queries the **store** for fresh pricing/availability and updates the cache |
| `GetProductById(id)` | Returns a single cached product by ID |

These are NOT interchangeable. Always call `FetchProducts()` first before relying on `GetProducts()`.

## Two-Step Purchase Flow

IAP v5 uses a mandatory two-step flow: **Pending → Confirm**.

1. `store.PurchaseProduct(product)` — initiates the platform purchase dialog
2. `OnPurchasePending` fires — you receive a `PendingOrder`
3. Validate the receipt, grant content to the player
4. `store.ConfirmPurchase(pendingOrder)` — finalizes the transaction
5. `OnPurchaseConfirmed` fires — receives `Order` base type; pattern-match `ConfirmedOrder` (success) vs `FailedOrder` (confirmation failed)

**You MUST call `ConfirmPurchase(pendingOrder)` after granting content.** Unconfirmed purchases are re-delivered on next app launch to prevent lost purchases.

**De-duplication:** `OnPurchasePending` may fire multiple times for the same purchase (e.g., app restart before confirmation). Always check if content was already granted.

**Consumables:** Confirmed consumable purchases are NOT returned by `FetchPurchases`. Track consumable grants yourself (e.g., in Cloud Save or Economy).

**Deferred purchases:** `OnPurchaseDeferred` fires for Ask-to-Buy (iOS) and Google Play deferred purchases. Do NOT grant content — wait for `OnPurchasePending` when approved.

## Restore Transactions

`store.RestoreTransactions(callback)` re-delivers non-consumable and subscription purchases. Each restored purchase triggers `OnPurchasePending`.

Required on iOS for Apple App Store compliance — add a "Restore Purchases" button.

Apple non-renewable subscriptions **cannot be restored** via `RestoreTransactions`. Track these server-side.

## Receipt Validation

| Platform | Approach |
|---|---|
| **Google Play** | `CrossPlatformValidator` with `GooglePlayTangle.Data()` — local validation supported |
| **Apple (StoreKit 2)** | Local validation is a **no-op**. Use `order.Info.Apple?.jwsRepresentation` for server-side validation |

Generate tangle data via **Services > In-App Purchasing > Receipt Validation Obfuscator** in the Unity Editor.

## Entitlement Checking

Use when you don't have the `Order` and want to know the status of a specific product (replaces v4's `product.hasReceipt`). If you already have the `Order`, check its type instead: `PendingOrder` maps to `EntitledUntilConsumed` (consumables) or `EntitledButNotFinished` (non-consumables/subscriptions), `ConfirmedOrder` maps to `FullyEntitled`.

Call `store.CheckEntitlement(product)` and handle `store.OnCheckEntitlement`. Check `entitlement.Status == EntitlementStatus.FullyEntitled`.

`EntitlementStatus` values: `FullyEntitled`, `EntitledUntilConsumed`, `EntitledButNotFinished`, `NotEntitled`, `Unknown`.

## Fetch Existing Purchases

`store.FetchPurchases()` retrieves all current purchases from the store. Useful at app startup.

| Method | Behavior |
|---|---|
| `GetPurchases()` | Returns the **cached** purchase list |
| `FetchPurchases()` | Queries the **store** for current purchases and **overwrites** the cached list |

`FetchPurchases()` replaces the entire cached list on each call. Only non-consumables and subscriptions are re-fetched — confirmed consumables are not returned (see Two-Step Purchase Flow above).

## Subscription Info

Subscription info is on `IPurchasedProductInfo`, accessed via `order.Info.PurchasedProductInfo` — **NOT on `CartItem`** (`CartItem` only has `Product` and `Quantity`).

`IsSubscribed()` returns `Result` enum (`True`/`False`/`Unsupported`), NOT `bool`. Use `== Result.True` for null-safe comparison.

## Required Event Subscriptions

**Always subscribe to BOTH success and failure events.** Not subscribing to failure events generates runtime warnings.

| Call | Success Event | Failure Event (REQUIRED) |
|---|---|---|
| `FetchProducts()` | `OnProductsFetched` | `OnProductsFetchFailed` |
| `FetchPurchases()` | `OnPurchasesFetched` | `OnPurchasesFetchFailed` |
| `Connect()` | `OnStoreConnected` | `OnStoreDisconnected` |
| `PurchaseProduct()` | `OnPurchasePending` | `OnPurchaseFailed` |
| `CheckEntitlement()` | `OnCheckEntitlement` | — |

**Always subscribe to `OnPurchaseDeferred`** — fires for Ask-to-Buy (iOS) and Google Play deferred purchases. Not subscribing silently drops deferred purchases.

Subscribe to events **BEFORE** calling `Connect()` — pending purchases from a previous session may fire immediately.

## Failure Description Property Names

These property names are NOT interchangeable — using the wrong one causes CS1061:

| Type | Field | Property | NOT |
|---|---|---|---|
| `StoreConnectionFailureDescription` | `.message` | `.Message` | ~~`.reason`~~ |
| `ProductFetchFailed` | — | `.FailureReason`, `.FailedFetchProducts` | ~~`.Message`~~ |
| `FailedOrder` | — | `.FailureReason`, `.Details` | — |
| `PurchasesFetchFailureDescription` | `.message`, `.failureReason` | `.Message`, `.FailureReason` | — |

## Validation

After writing code that uses this package:
1. Verify the project compiles without errors.
2. Confirm all API calls match the v5 signatures in [api-notes.md](references/api-notes.md) — do NOT use v4 legacy patterns (`IStoreListener`, `UnityPurchasing.Initialize`, `ConfigurationBuilder`).
3. Check the "Anti-Hallucination: Common v5 Mistakes" table in api-notes.md — do NOT use `OnStoreConnectionFailed` (use `OnStoreDisconnected`), do NOT pass callbacks to `FetchProducts`/`FetchPurchases` (use events), do NOT use `product.receipt` (use `order.Info.Receipt`).
4. Check that all required events are subscribed **before** calling `Connect()` (see Required Event Subscriptions table above).
5. Verify the two-step purchase flow: `OnPurchasePending` → grant content → `ConfirmPurchase(pendingOrder)`.
6. Confirm both success and failure events are subscribed for every async operation (`OnProductsFetched`/`OnProductsFetchFailed`, `OnStoreConnected`/`OnStoreDisconnected`, etc.).
7. If handling subscriptions, verify `IsSubscribed()` is compared with `== Result.True`, not cast to `bool`.
8. If updated files coexist with legacy versions in the same project, use a unique namespace (e.g., add `.Updated` suffix) to avoid CS0101/CS0111 compilation errors.
9. If the project subscribes to `OnAuthAccountChanged` (v5.4+): verify the handler re-fetches products and purchases from scratch — Unity IAP clears both caches before raising this event. Do not read `GetProducts()` or `GetPurchases()` inside the handler.

Referenced files: 13

View saved version →

---
name: initialize-ai-navigation
description: Sets up and configures the Unity AI Navigation system — NavMesh surfaces, NavMesh agents, obstacles, links, modifiers, areas and costs. Use when creating walkable navigation meshes, adding pathfinding agents, setting up patrol routes, configuring obstacle avoidance and carving, connecting separate NavMeshes with links, coupling navigation with animation, or troubleshooting navigation issues.
---

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)
2. **NavMesh Agent** — add pathfinding characters
3. **NavMesh Obstacle** — add dynamic obstacles
4. **NavMesh Link** — connect disconnected NavMesh areas
5. **NavMesh Modifier / Modifier Volume** — fine-tune area types
6. **Scripts** — movement, patrol, click-to-move, animation coupling (see Common Recipes in reference)

### 4. Validation
After setup, confirm:
- NavMesh is baked and visible (blue overlay)
- NavMeshSurface agent type matches NavMeshAgent agent type
- Agents have a valid path to their destination
- Obstacles carve or obstruct correctly
- Links have both ends connected and Activated is enabled
- Area masks allow the intended movement
- No conflicting components (see Mixing Components Guide in reference)
- If using Rigidbody with NavMeshAgent, Is Kinematic is enabled

### 5. Final Confirmation
Summarize what was created or changed:
- NavMesh Surfaces: which GameObject, agent type, geometry mode, bake status
- NavMesh Agent(s): which GameObject, speed, stopping distance, area mask
- NavMesh Obstacle(s): which GameObject, shape, carve on/off
- NavMesh Link(s): start/end, bidirectional, area type
- Scripts: which scripts attached to which GameObjects
- Any manual steps required (adjust waypoints, re-bake after scene changes, etc.)

Referenced files: 1

View saved version →

---
name: levelplay-unity-integration
description: Integrates the LevelPlay Mediation SDK via the Ads Mediation UPM package. Use when a developer asks about adding ads to a Unity game, implementing rewarded, interstitial, or banner ads, setting up ad mediation, configuring ad networks, installing or updating the Ads Mediation package, troubleshooting LevelPlay namespace errors, resolving Android gradle or iOS CocoaPods dependency issues for ads, configuring ATT or privacy settings for ad compliance, tracking impression-level revenue (ILRD), initializing the LevelPlay SDK, or setting up ad unit IDs. Also use when a developer wants to monetize their Unity game with ads, asks how to get started with LevelPlay, ads, or mediation, or needs help with any part of the LevelPlay integration workflow including platform-specific setup for iOS or Android. Also use when upgrading the LevelPlay or IronSource SDK version, migrating from deprecated IronSource.Agent APIs, or migrating a game from Unity Ads to LevelPlay.
---

# 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/ directories exist. If not in a Unity project, instruct the user to navigate to their Unity project directory. If those directories are not found but the user believes they are in the right place, ask: "It looks like you may not be at your project root — can you navigate to the top-level folder of your Unity project and confirm you can see Assets/ and ProjectSettings/ there?"

### 2. Understand Business Goals

Before implementing ad units, determine the user's optimization priorities to recommend the appropriate ad unit strategy. Ask:

**"What's your primary optimization goal?"**
- **Revenue-focused**: Maximize ad revenue and impression opportunities
- **UX-focused**: Prioritize gameplay flow and user satisfaction  
- **Balanced**: Optimize for both revenue and UX
- **Not sure yet**: Default to Balanced and proceed. At Step 8, briefly note you're using Balanced since they were unsure, and invite them to indicate a different preference now that they've seen the format options.

Record this answer for later strategy recommendation in Step 8.

### 3. Install LevelPlay SDK via UPM

**If the SDK looks already installed:** do not take that on trust, and do not ask the user to read
the Package Manager window for you. Read `Packages/packages-lock.json` and look for
`com.unity.services.levelplay`. If it is there, say which version resolved and proceed to Step 4.
If it is not, it is not installed, whatever the conversation so far has assumed: continue with the
install below.

Guide through installing the LevelPlay Unity package using Unity Package Manager:

1. Open Unity → Window > Package Manager
2. Select Unity Registry dropdown or Services tab
3. In the Package Manager search bar, type **Ads Mediation**
4. Confirm the package name matches exactly: the correct package is titled **Ads Mediation**. Do not install either of these packages:
   - **Ads IAP Mediation Adaptor** (a separate in-app purchases package, not the LevelPlay SDK)
   - **Advertisement Legacy** (a deprecated package, not compatible with the current LevelPlay integration)
5. Click Install button
6. Wait for package to download and import

When you install the package, you may see a prompt to install Mobile Dependency Resolver — click **Import** if it appears. This is covered in more detail in the next step.

**Then verify it resolved, by reading the project rather than by asking.** The package id is
`com.unity.services.levelplay` (its Package Manager display name is **Ads Mediation**; the id is
what the project files record). Check both files:

- **`Packages/manifest.json`** lists what the project *asks for*. `com.unity.services.levelplay`
  must appear under `dependencies`.
- **`Packages/packages-lock.json`** records what Unity actually *resolved*. The same id must appear
  here too, with a concrete version. This is the file that answers "did it install", and it is the
  one to trust.

Both are plain JSON in the project, so this check needs no Editor, no CLI, and nothing from the
user. Read them.

> **This is a hard gate, not a formality.** Do not write, generate, or paste a single line of
> LevelPlay code until `com.unity.services.levelplay` is present in `packages-lock.json`. Skipping
> ahead produces code that looks correct, compiles nowhere, and fails with `CS0246` on every
> LevelPlay symbol. If the id is missing from `manifest.json`, the install never happened. If it is
> in `manifest.json` but not `packages-lock.json`, Unity has not resolved it yet: the Editor may
> still be importing, or resolution failed. Say which of the two you found, and stop.
>
> **If you added the id to `manifest.json` yourself and no Editor has run since, the lock file will
> not show it yet. That is expected, not a failure.** Never write the entry into
> `packages-lock.json` yourself: that file is Unity's resolution output, hand-editing it is what the
> migration guide forbids, and an entry you wrote is a false "resolved" signal rather than a passed
> gate. Ask the user to open the Unity Editor so resolution runs, then re-read the file. If no
> Editor is available at all, say so and stop there rather than manufacturing the evidence.

Report the resolved version you found. Do not report "installed" on the strength of the Package
Manager window, a previous turn, or a user's recollection.

**Network Manager:** Access **Ads Mediation > Network Manager** at any time to install additional ad network adapters and check for SDK and adapter updates.

For iOS builds, note that SKAdNetwork configuration will be needed later (reference `references/ios-setup.md` when ready for iOS builds).

### 4. Resolve Native Dependencies (Critical)

**Critical for Android/iOS builds**: LevelPlay requires native dependency resolution. Without this, code compiles in Unity Editor but fails during platform builds with gradle (Android) or CocoaPods (iOS) errors.

**Platform checkpoint — ask before proceeding:** "Which platform(s) are you targeting — iOS, Android, or both?" Record this. It determines which dependency resolution steps apply here, whether ATT is required (Step 6.5), and which testing steps are relevant (Step 10).

**Set the active build target now.** Switch the project's active build target to Android or iOS via **File ▸ Build Profiles** (called **Build Settings** before Unity 6) → **Switch Platform**. This is required before any testing: LevelPlay only runs on Android/iOS targets, so even mock ads in the Editor (Step 10) do nothing while the target is Standalone/PC/Mac.

**Resolve dependencies for the target platform(s).** LevelPlay requires native Android/iOS libraries that Unity's package manager alone doesn't handle; a dependency manager (MDR, UEDM, or EDM4U) bridges this gap. The full procedure — checking for an existing dependency manager, resolving on Android vs iOS, installing one if the user has none, verification, and the older-version Custom Main Gradle Template — is in **`references/dependency-resolution.md`**. Walk the user through it now, and **if targeting both Android and iOS, complete resolution for both before proceeding.**

Ask: "Have you run dependency resolution for your target platform(s) without errors?"

**Android API 33+ (Android 13+):** declare the AD_ID permission in AndroidManifest.xml:

```xml
<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>
```

Without it, advertising ID access fails on Android 13+ devices. Details in `references/dependency-resolution.md`.

**If dependency resolution fails**, see `references/troubleshooting.md` for gradle and CocoaPods error guidance.

### 5. Get App Key and Ad Unit IDs

Before initializing LevelPlay, collect credentials from the LevelPlay dashboard.

**Dashboard:** https://platform.ironsrc.com/

**New to LevelPlay?** Set up your app and ad units first:
- [Add your app](https://docs.unity.com/en-us/grow/levelplay/platform/get-started/add-app)
- [Create ad units](https://docs.unity.com/en-us/grow/levelplay/platform/get-started/ad-units)

**App Key:** In the dashboard, go to **Apps** in the left sidenav → find your app → copy the alphanumeric string displayed under the app title.

**Ad Unit IDs:** Go to **Ad units** in the left sidenav → select your app → copy the ID for each format you plan to implement (Rewarded, Interstitial, Banner).

**Note:** You need your App Key now for initialization (Step 7). Ad Unit IDs are only needed at Step 9 — if you haven't decided which ad formats to implement yet, just copy your App Key for now and return here after Step 8.

Keep both accessible — you'll need them in the next steps.

### 6. Configure AdMob Keys (If Using AdMob Network)

**When to use**: Only if using AdMob as a mediation network adapter in LevelPlay.

If using AdMob, configure platform-specific app keys in Unity Editor:

**Access**: Ads Mediation > Developer Settings > LevelPlay Mediation Settings

**Configuration:**
- **Android App Key**: AdMob Android app key
- **iOS App Key**: AdMob iOS app key

This configuration is required for AdMob to work as a mediation network in LevelPlay.

**Troubleshooting**: If you don't see the 'Ads Mediation' menu in Unity Editor, verify the Ads Mediation package is installed (Step 3) and restart Unity Editor.

### 6.5. Privacy & Regulation Settings (If Required)

> **Note:** This skill provides technical integration guidance, including for LevelPlay's privacy APIs. It is not legal advice, and it does not determine which laws apply to your app — that depends on your users, your data practices, and your distribution. Consult your own legal counsel, and refer to [Regulation Advanced Settings for Unity](https://docs.unity.com/en-us/grow/levelplay/sdk/unity/regulation-advanced-settings) for the authoritative LevelPlay documentation.

Ask the user: "Do you need to configure privacy settings for GDPR, CCPA/CPRA (or certain state privacy consumer acts), or for child-directed apps?"

**If YES to any:**

Privacy settings must be configured **BEFORE** SDK initialization. See `references/privacy-settings.md` for the complete implementation guide (UI, consent management, combined regulations, and the full network key list).

**GDPR — the correct API depends on the user's SDK version** (check in **Ads Mediation > Network Manager**):

**SDK 9.5.0+** — global consent boolean:
```csharp
using Unity.Services.LevelPlay;

// true = user has granted consent, false = user has not consented
LevelPlayPrivacySettings.SetGDPRConsent(true);
```

**SDK 9.4.x** — per-network consent dictionary (this is the CURRENT API on 9.4.x, not legacy — it only becomes `[Obsolete]` on 9.5.0+; do not mislabel it as deprecated):
```csharp
using Unity.Services.LevelPlay;
using System.Collections.Generic;

// Add an entry for each ad network you have installed
LevelPlayPrivacySettings.SetGDPRConsents(new Dictionary<string, bool> {
    { "UnityAds", true },
    { "IronSource", true }
    // See references/privacy-settings.md for the full network key list
});
```

If neither API compiles, your Unity package/SDK may be below 9.4.0 (legacy) — recommend upgrading via **Ads Mediation > Network Manager**. If the user cannot upgrade, the legacy `LevelPlay.SetConsent(bool)` API is documented in `references/privacy-settings.md`.

**CCPA (SDK 9.4.0+):**
```csharp
LevelPlayPrivacySettings.SetCCPA(true); // User opted out of data sale
```

**COPPA (SDK 9.4.0+):**
```csharp
LevelPlayPrivacySettings.SetCOPPA(true); // Child-directed app
```

If CCPA or COPPA fails to compile, upgrade your Unity package/SDK via **Ads Mediation > Network Manager**. Call all of these BEFORE `LevelPlay.Init()` in Step 7.

**For iOS builds — required regardless of privacy regulations above:** Also implement App Tracking Transparency (ATT) before proceeding to Step 7. Apple requires ATT authorization before your app tracks users or accesses the device's advertising identifier on iOS 14.5+. Request ATT authorization before calling `LevelPlay.Init()` — this is both an Apple platform requirement and necessary for personalized ads (which also affects fill rate). See `references/ios-setup.md` for the ATT implementation code.

**If NO privacy regulations and not targeting iOS:** Skip this step and proceed to Step 7.

### 7. Initialize LevelPlay SDK

**Installation checkpoint:**

**First, re-read `Packages/packages-lock.json` and confirm `com.unity.services.levelplay` is there.**
Do this every time you reach this point, even if Step 3 already passed earlier in the conversation.
It costs one file read, and it is the only item here you can settle without the user. An earlier
turn saying the package was installed is not evidence that it is: this check exists because the
install step is the one most often skipped, and the resulting code fails with `CS0246` on every
LevelPlay symbol. If the id is absent, go back to Step 3 and do not write initialization code.

Then confirm the remaining prerequisites with the user, which are the ones no file can answer.
**If the user confirmed they are not using AdMob, omit the Step 6 item.** If Step 4 was already
confirmed in this conversation, skip that item and ask only about Step 5 and Step 6 (if AdMob).

"Please confirm these are working correctly:
- Step 4: Have you run dependency resolution for your target platform(s) without errors?
- Step 5: Do you have your App Key copied from the LevelPlay dashboard?
- Step 6 (only if using AdMob): Have you configured AdMob keys in Unity Editor settings?

Verify these are working before proceeding."

**If the package check failed or they answer NO or are unsure:**
- Package id absent from `packages-lock.json`: code will show `CS0246` namespace errors → Direct to Step 3. This one you established yourself; do not ask the user to overrule it.
- Missing Step 4: Code compiles but Android/iOS builds will fail → Direct to Step 4
- Missing Step 5: They won't have credentials to initialize → Direct to Step 5
- Do not provide C# code until they confirm all steps are complete

**If they answer YES:**
- **Optional — Analytics: ILRD Wiring.** Ask this question verbatim — do not summarize or rephrase it: "Do you use an analytics or attribution platform (Firebase, AppsFlyer, Adjust, Singular, or custom backend) that needs ad revenue data? If yes, the init script will include a logging stub for Impression Level Revenue (ILRD) — 3 lines of code, no analytics platform setup required yet. (Yes / No / Not sure — defaults to yes)" Record the answer.
- Proceed with initialization code.

LevelPlay SDK must be initialized before loading or showing any ads. Initialization should happen early in the application lifecycle.

**Ask how they want to handle initialization. Present all four options exactly as listed — do not condense or omit any:**
1. Create a new dedicated script for LevelPlay initialization
2. Add to an existing initialization/manager script they already have
3. Create a new LevelPlay script that your existing manager references
4. Just show me the initialization code — I'll decide how to integrate it

**Full code for each option is in `references/initialization-api.md` (Code Organization Options).** Behavior that must not change:
- **Option 1 (new script):** If ATT was set up in Step 6.5 (iOS), use the `LevelPlayInitializer.cs` from `references/ios-setup.md` Part 3 (the `IEnumerator Start()` coroutine variant) instead of the plain template.
- **Option 4 (just the code):** provide the complete Option 1 initialization class as a standalone snippet — do NOT create files or add Inspector/GameObject setup steps — with the note: "save it as `LevelPlayInitializer.cs`, attach it to a persistent GameObject in your first scene, and set the App Key field in the Inspector."

**ILRD wiring (if the user answered Yes or Not Sure).** The correct approach depends on the SDK version (check in **Ads Mediation > Network Manager**):
- **SDK 9.5.0+ (current):** add nothing to the initializer — ILRD is delivered per ad instance via `OnAdImpressionDataReady`, wired when each ad is created in Step 9. The global `LevelPlay.OnImpressionDataReady` event is **deprecated on 9.5.0+ and generates a compiler warning** — do not use it.
- **SDK 9.4.x and earlier:** subscribe to the global `LevelPlay.OnImpressionDataReady` event **before** `LevelPlay.Init()`, add a logging stub, and unsubscribe in `OnDestroy()`. On the iOS coroutine initializer, place the subscription inside `InitializeLevelPlay()` immediately before `LevelPlay.Init(appKey)`.

The exact wiring code for each option (including the iOS coroutine placement) is in `references/initialization-api.md` (Version-Aware ILRD Init Wiring). ILRD callbacks do not fire with mock ads — a device build is needed to verify (see Step 10). For advanced options (user ID, segmentation, consent management), see `references/initialization-api.md`.

### 8. Recommend Ad Unit Strategy

Based on the optimization goal identified in Step 2, recommend an ad unit strategy.

**Recall the user's optimization goal from Step 2.** If the conversation has been long or the answer is unclear, confirm: "Earlier you mentioned your optimization goal. To confirm, are you primarily focused on revenue, user experience, or a balance of both?"

**Map the answer to a strategy** and give a brief recommendation (full detail, benchmarks, and placement guidance are in `references/best-practices.md` under "Ad Format Strategy by Goal"):

- **Revenue-focused** → **Revenue Strategy.** Rewarded (primary monetization, multiple high-value moments) → Interstitial (secondary; at transitions; frequency cap 3–5 min) → Banner (persistent during gameplay). Bid floors are an optional revenue lever configured in Step 9. Implementation priority: **Rewarded → Interstitial → Banner**.
- **UX-focused** → **UX Strategy.** Rewarded only, user-initiated (explicit opt-in), high-value rewards, **no forced ads, ever**. Interstitials optional/sparingly at session boundaries only; banners generally avoided or menu-only. Implementation priority: **Rewarded only, or Rewarded → (optional) Interstitial**.
- **Balanced** → **Balanced Strategy.** Rewarded (2–3 strategic placements) → Interstitial (moderate; natural breakpoints; frequency cap 5–7 min) → Banner (selective; menus/low-attention). Implementation priority: **Rewarded → Interstitial → Banner (selective)**.
- **"Not sure yet"** (from Step 2) → use the **Balanced Strategy**, then add: "Since you weren't sure of your goal earlier, I've gone with the Balanced approach — if you'd prefer to lean more toward revenue or user experience now that you've seen the options, just say so."
- If still unclear, ask: "Would you prioritize revenue, user experience, or a balance of both?"

The next step asks which ad formats to implement from this priority list. If the user wants a different order than recommended, accommodate that preference.

### 9. Implement Ad Units

**Read `references/best-practices.md` first** — its "Code Generation Guidelines (Step 9)" section carries the general ad lifecycle, the per-organization-approach code-gen rules, the always-include requirements (MonoBehaviour, `DestroyAd()` in `OnDestroy()`, the placement-capping show-path check (when placements are used), event unsubscription, null checks, error handling), and the bid-floor wiring examples. Incorporate those patterns into all ad implementations.

**Implementation checkpoint:**

"Before providing ad implementation code, please confirm:
- Did you complete SDK initialization in Step 7?
- Did you receive the 'LevelPlay SDK initialized successfully' log message in your Unity console?

Verify initialization is working before proceeding with ad units."

**If they answer NO or are unsure:** direct back to Step 7 and do not provide ad implementation code until initialization is confirmed working.

**Ad format checkpoint — ask before generating any code:** "Which ad formats do you want to implement? Rewarded, Interstitial, Banner, or a combination?" Only implement the formats the user selects. They can add more formats later using the 'Adding More Ad Formats Later' section.

**First, ask the user how they want to organize the ad code. Do not generate any code until they have answered:**

"How would you like to structure your ad implementation?"

1. **Separate manager scripts for each ad format** - Create individual scripts like `RewardedAdManager.cs`, `InterstitialAdManager.cs`, `BannerAdManager.cs` (good for larger projects, clear separation of concerns)

2. **One unified AdManager script** - Create a single `AdManager.cs` that handles all ad formats (simpler, everything in one place)

3. **Just show me the code snippets** - Provide implementation code without wrapping it in specific files, so you can integrate it however you prefer

4. **I already have ad manager code** - Review and help fix/update existing implementation

Based on their answer, adapt your response accordingly (see the code-gen guidelines in `references/best-practices.md`).

**If the user already has ad code (e.g., an existing manager script), ask to see it before generating any** — so you can provide targeted fixes rather than new code from scratch. This applies regardless of which organization option they picked (Option 4 is specifically for reviewing existing code, but the same "show me your code first" applies whenever the user mentions they already have some).

**Then present the optional bid floor feature (skip for Option 4 — review existing code instead):**

Present bid floor ranges only for the formats the user is implementing in this session. Reference starting ranges: Rewarded: $0.50–$2.00 | Interstitial: $0.20–$1.00 | Banner: $0.05–$0.20. Include only the ranges for formats being implemented.

"**Optional — Advanced: Bid Floors**

Most publishers skip this initially and add it once they have real dashboard data. You can safely skip now and return to it later.

If you'd like to set bid floors now: a bid floor sets a minimum bid price (USD) per ad unit — it raises your average eCPM at the cost of lower fill rate. Starting ranges:
[ranges for formats being implemented]

Reply with values per format, or just say 'skip' — you can add them any time."

**Record the answer per format.** Wire `Config.Builder().SetBidFloor(...)` into the ad construction for any format where a value was provided; formats marked 'skip' use the basic constructor (see the bid-floor examples in `references/best-practices.md`).

**If they choose Option 4 (existing code):**
- Ask: "Please share your existing ad manager code for review" and wait for it.
- Analyze the implementation: whether they use the current LevelPlay Ad Unit API (LevelPlayRewardedAd, LevelPlayInterstitialAd, LevelPlayBannerAd), whether they use **deprecated IronSource.Agent APIs**, proper callback registration/unsubscription, and missing error handling or memory leaks.
- Provide specific guidance:
  - If using deprecated APIs: "You're using the old IronSource.Agent API. Here's how to migrate to the new LevelPlay Ad Unit API:" (full migration detail in `references/migration-sdk-9.md` — Scenario B for init, Scenario C per ad format including the C5 completeness checklist)
  - If using current APIs with issues: "Your implementation looks good but I noticed [specific issues]. Here's how to fix them:"
  - If implementation is correct: "Your implementation looks solid. Which additional ad formats would you like to add?"
- Offer fixes as code snippets or suggest refactoring. When adding new formats after review, present the bid floor prompt scoped to those new formats only, confirm whether to match their existing organization pattern or use a new one, then follow the same guidelines as Options 1–3.

For each ad format, follow the implementation guidelines in the detailed references:

- **Rewarded ads**: See `references/rewarded-api.md`
- **Interstitial ads**: See `references/interstitial-api.md`
- **Banner ads**: See `references/banner-api.md`

**Impression Level Revenue Tracking (version-aware):** See `references/ilrd-api.md` to forward impression data to the analytics platform (Firebase, AppsFlyer, Adjust, Singular, or custom backend).
- **SDK 9.5.0+ (current):** subscribe to each ad object's `OnAdImpressionDataReady` event right after you create it (and unsubscribe in `OnDestroy()`). Add this to every ad manager you generate — it is the correct ILRD path in 9.5.0+.
- **SDK 9.4.x and earlier:** ILRD uses the single global `LevelPlay.OnImpressionDataReady` event, wired in the init script (Step 7). If the user answered Yes/Not Sure in Step 7, it is already wired. If they said "No" and want it now, subscribe to `LevelPlay.OnImpressionDataReady` **before** the existing `LevelPlay.Init()` call.

### 10. Testing and Validation

LevelPlay provides two validation approaches for different stages of development. **Full detail — setup, callback-behavior tables, the Test Suite initializer template, and the iOS coroutine placement — is in `references/testing-and-validation.md`. Read it when the user is testing.**

**Early Development: Mock Ads in Unity Editor.** For rapid iteration and callback testing. Pressing Play in the Editor provides mock ads automatically — but **only if the active build target is Android or iOS** (Standalone/PC/Mac returns no ads; this is the most common "no ads in Editor" cause — see Step 4). Mock ads work with any App Key/Ad Unit ID, but recommend real credentials so they aren't forgotten. Mock ads fire most callbacks (OnAdLoaded/Displayed/Rewarded/Closed) but NOT failure, click, or impression/ILRD callbacks — so test error handling on device. Details and the full callback table: `references/testing-and-validation.md`.

**Integration Validation: LevelPlay Test Suite (Recommended).** The primary method for comprehensive validation against real ad networks on device. Key rules that must not change:
- `LevelPlay.SetMetaData("is_test_suite", "enable");` **before** `LevelPlay.Init()`
- `LevelPlay.LaunchTestSuite();` inside `OnInitSuccess`
- **Requires a device build** (does not work in the Editor); enable **Development Build** so SDK logs are visible; use the production App Key.
- **Remove both lines before production release.**
- iOS coroutine initializer: put `SetMetaData` as the first line inside `InitializeLevelPlay()` before `Init` (not in `Start()`).

Add the two lines to the existing `LevelPlayInitializer.cs` (don't create a new file). The full setup, the standalone template for users without an initializer, and the testing workflow are in `references/testing-and-validation.md`.

#### Production Release Checklist

Before releasing to production:

- [ ] Test Suite validation completed successfully on device
- [ ] All ad formats load correctly (Rewarded, Interstitial, Banner if implemented)
- [ ] All callbacks fire as expected
- [ ] App Key and ad unit IDs verified correct for production
- [ ] Tested on multiple devices (different screen sizes, OS versions)
- [ ] **iOS-specific requirements completed** (if targeting iOS):
  - [ ] SKAdNetwork IDs configured in Info.plist (see `references/ios-setup.md`)
  - [ ] App Tracking Transparency (ATT) framework implemented (see `references/ios-setup.md`)
  - [ ] iOS privacy manifest configured if required
  - [ ] Tested on physical iOS device (not just simulator)
- [ ] **Android-specific requirements completed** (if targeting Android):
  - [ ] Google Play Services dependencies resolved (Step 4 completed)
  - [ ] AD_ID permission added to AndroidManifest.xml if targeting API 33+ (see Step 4)
  - [ ] Tested on physical Android device
- [ ] Tested with real ads in production environment
- [ ] Ad frequency capping implemented (if using interstitials)
- [ ] Error handling works correctly (test with airplane mode - ads should fail gracefully without crashing or blocking gameplay)

## Adding More Ad Formats Later

If you've already integrated some ad formats and want to add more:

1. **Skip to Step 9** - You don't need to repeat the initial setup steps. Before proceeding, verify your existing initialization still works by checking the Unity console for the 'LevelPlay SDK initialized successfully' log.
2. **Choose the additional formats** you want to implement
3. **Follow the same organization pattern** you used before:
   - If you created separate manager scripts, create a new manager script for the new format
   - If you used a unified AdManager, add the new format's code to your existing AdManager class
   - If you used code snippets, integrate new snippets following the same pattern
4. **Follow the same implementation guidelines** from Step 9 for the new ad format
5. **Test the new format** following Step 10 testing guidelines

**Example**: If you initially implemented only Rewarded ads using separate manager scripts, and now want to add Interstitial ads: create `InterstitialAdManager.cs` following the same structure as your `RewardedAdManager.cs`, follow the interstitial guidelines from `references/interstitial-api.md`, and test in Editor and on device. Your existing ad formats keep working while you add new ones.

## Best Practices

Before implementing ad code, read `references/best-practices.md`. It covers loading strategy (per format), placement strategy, error handling and graceful degradation, memory management, frequency management, and common mistakes to avoid — incorporate these patterns into all ad implementations.

## Common Issues and Solutions

If the user reports a problem, route to the matching issue in `references/troubleshooting.md` and follow it (stop generating code where that guidance says to). Do not wait for the user to open the reference — surface the fix directly. If they haven't started integration yet, begin with Step 1.

| Symptom | Likely root cause | Action |
|---|---|---|
| `CS0246` on `Unity.Services.LevelPlay`; red underlines on all LevelPlay code | Ads Mediation package not installed | Stop giving code; check `Packages/packages-lock.json` for `com.unity.services.levelplay`; install (Step 3); restart Editor; then resume. See troubleshooting.md. |
| Android gradle / iOS build fails with dependency errors; compiles in Editor but fails at build | Native dependencies not resolved | Resolve dependencies (Step 4 / dependency-resolution.md); verify `Assets/Plugins/Android/`; rebuild. See troubleshooting.md. |
| Ads not loading | SDK not initialized, wrong App Key, ad created before init, or no connectivity | Confirm `OnInitSuccess` fires before creating ads; check App Key; test on device. See troubleshooting.md. |
| Callbacks not firing | Events registered after init, missing subscriptions, or script destroyed | Register callbacks before `Init()`; verify subscriptions; use a persistent GameObject. See troubleshooting.md. |
| Platform-specific build errors (iOS SKAdNetwork/ATT/frameworks; Android Play Services/manifest/gradle) | Platform setup incomplete | See troubleshooting.md and `references/ios-setup.md`. |
| Android build fails resolving `com.ironsource.sdk` dependencies from `android-sdk.is.com` (worked before; nothing changed) | Dependencies moved to Maven Central; the old is.com repository was shut down | Follow Scenario D in `references/migration-sdk-9.md`: delete the stale dependency XMLs, reinstall via Network Manager, verify no is.com references remain. |

## When to Read Detailed References

Read specific references based on what the user is doing:

- **`references/dependency-resolution.md`**: Resolving native dependencies (Step 4), or gradle/CocoaPods build failures
- **`references/initialization-api.md`**: Step 7 init code-organization options and ILRD init wiring; also user ID, segmentation, consent management, advanced config
- **`references/privacy-settings.md`**: GDPR, CCPA, or COPPA compliance (incl. legacy `SetConsent` and the full network key list)
- **`references/ios-setup.md`**: iOS builds — ATT, SKAdNetwork, the iOS coroutine initializer
- **`references/rewarded-api.md`** / **`references/interstitial-api.md`** / **`references/banner-api.md`**: Implementing each ad format (Step 9)
- **`references/best-practices.md`**: Strategy detail (Step 8), the Step 9 code-generation guidelines, optimization, placement
- **`references/ilrd-api.md`**: Wiring ILRD to an analytics platform
- **`references/testing-and-validation.md`**: Mock ads and the Test Suite (Step 10)
- **`references/troubleshooting.md`**: Compile/build errors, ads not loading, callbacks not firing
- **`references/migration-sdk-9.md`**: Migrating from IronSource or older LevelPlay APIs, upgrading the SDK to 9.x.x, migrating from Unity Ads, or Maven Central dependency build failures (Step 0)

## Examples

**Note**: Examples show abbreviated workflows for illustration. In practice, follow all steps 1–10 in order.

**Revenue-focused game** ("maximize ad revenue in my casual puzzle game"): Steps 1–7 to verify environment/goal/install/deps/App Key/AdMob/init → Step 8 recommend Revenue strategy → Step 9 ask code organization and generate the chosen structure → Step 10 testing.

**UX-focused game** ("optional rewarded ads for extra lives without annoying players"): same spine, but Step 8 recommends UX strategy (rewarded only, user-initiated) and Step 9 implements rewarded with proper patterns.

**Existing project** ("existing GameManager, add interstitials between levels"): same spine, Step 8 Balanced, Step 9 ask to see `GameManager.cs` then provide Option-2 snippets.

## Core Rules (reminder)

These repeat the rules at the top of this file — they are the guardrails that matter most, restated here so they stay in view at the end of a long workflow:

- 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.
- When a step points to a reference file, read that reference and use its content — do not substitute general knowledge. Present the four init options (Step 7) and four organization options (Step 9) exactly as written, and ask the ILRD question (Step 7) verbatim.

Referenced files: 12

View saved version →

---
name: localization
description: "Sets up and configures Unity Localization, including locales, String/Asset Tables, CJK font support, and Addressables workflows. Use when the user wants to add languages to a project, translate UI text, support Asian (CJK) languages with TMP fonts, or mentions i18n, l10n, multilingual support, or making a game support multiple languages."
---

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.SetDirty(collection.SharedData)`, on each modified `Table`.
2. **Unity 6+ Notification:** `LocalizationEditorSettings.EditorEvents.RaiseCollectionModified(sender, collection);`
3. Always call `AssetDatabase.SaveAssets()` at the end.

## 3. UI Localization and Layout
### **Namespacing & Conflicts**
- **Always qualify names:** Use `UnityEngine.UI.Image`, `UnityEngine.UI.VerticalLayoutGroup`, `UnityEngine.UI.ScrollRect`, `UnityEngine.UI.Mask`, `UnityEngine.UI.CanvasScaler`, `UnityEngine.UI.GraphicRaycaster`, `UnityEngine.UI.ContentSizeFitter`, `UnityEngine.UI.LayoutRebuilder`, etc. 
- `UnityEngine.UI` is both a namespace and a class container, so unqualified names produce `CS0118` (namespace used like a type). Full qualification avoids this entirely.
- **Single Instance:** Always check `GameObject.Find("YourCanvasName")` and destroy the old one before creating a new one.
- **Locale switching: use the package, and keep preview and runtime separate.** These are two
  different mechanisms, and conflating them is why locale switching often ends up hand-rolled.
  - **To preview a locale while authoring**, use the **Localization Scene Controls** window
    (`Window > Asset Management > Localization Scene Controls`). This is Editor-only. It is not a
    runtime feature, so it is not the answer when the game itself needs a language setting.
  - **To switch locale at runtime**, assign `LocalizationSettings.SelectedLocale`. That is the
    supported entry point, and everything bound through `LocalizeStringEvent` updates from it.
  - **To pin which locale the game starts in**, configure a startup locale selector on the
    Localization Settings asset. `SpecificLocaleSelector` is the one that forces a chosen locale;
    the default chain otherwise picks up the system language.
  - **NEVER hand-roll locale state.** A real in-game language menu is fine and expected, as long as
    it sets `SelectedLocale` and lets the package propagate the change. What is forbidden is a debug
    dropdown or menu that tracks its own "current language" variable, swaps strings itself, or
    reaches around the package, because nothing else in the project will follow it.

### **Localized String Events (Robust Binding)**
- **Check Component Type:** Identify if the target is `TextMeshPro` or legacy `UnityEngine.UI.Text`.
- **Bind Correctly:** add the public `UnityEngine.Localization.Components.LocalizeStringEvent`
  component and wire it yourself — set `StringReference` to the table entry, then add an
  `OnUpdateString` listener that assigns the value to the text component (`TMP_Text.text` for
  TextMeshPro, `UnityEngine.UI.Text.text` for legacy Text).

  Do **not** reflect into `UnityEditor.Localization.Plugins.TMPro.LocalizeComponent_TMPro` or its
  UGUI counterpart. Those are `internal` (measured on Localization 1.5.12), so reaching them means
  routing around access control to reach an API Unity makes no stability commitment about — it can
  change or disappear in any package release. `LocalizeStringEvent` is public and does the same job
  with the wiring made explicit.
- **Layout Rebuild:** After setting localized text or populating a list, call `UnityEngine.UI.LayoutRebuilder.ForceRebuildLayoutImmediate(parentTransform)` to ensure dimensions update.

## 4. Asian Language Font Support (CJK)
Avoid TMP Fallback Fonts for CJK locales. Use **Asset Table Font Swapping** for each specific locale instead — fallbacks are unreliable and hard to debug when glyphs are missing.

### Prerequisite: TMP Essential Resources must be imported

**Check this before touching any TMP API.** In a project that has never imported them,
`TMP_Settings.instance` is `null` and TMP calls fail with a bare
`NullReferenceException` that names nothing useful. `TMP_FontAsset.CreateFontAsset` is one of them, so
font creation dies on the first line with an error that looks like a bug in your code.

```csharp
// The check.
var ready = TMPro.TMP_Settings.instance != null;
```

If it is not ready, import them **non-interactively**:

```csharp
// Do NOT use EditorApplication.ExecuteMenuItem("Window/TextMeshPro/Import TMP Essential Resources").
// It returns true and then opens a dialog that waits for a human, so nothing gets imported and the
// run appears to hang. Import the package directly instead.
string package = null;
var cache = System.IO.Path.GetFullPath(System.IO.Path.Combine(
    UnityEngine.Application.dataPath, "..", "Library", "PackageCache"));
foreach (var dir in System.IO.Directory.GetDirectories(cache))
{
    // TMP ships inside com.unity.ugui in Unity 6, and the folder name carries a version hash,
    // so search for the file rather than hardcoding a path.
    var candidate = System.IO.Path.Combine(dir, "Package Resources", "TMP Essential Resources.unitypackage");
    if (System.IO.File.Exists(candidate)) { package = candidate; break; }
}
UnityEditor.AssetDatabase.ImportPackage(package, false);   // false = non-interactive
```

Then poll `TMP_Settings.instance != null` in a **later** call, the same way as the package check in
Step 0, and only continue once it is non-null. Verified on Unity 6000.5.8f1: the non-interactive
import completes in a few seconds and the assets land in `Assets/TextMesh Pro`.

1. **Use locale-specific fonts:** Western fonts like Arial or Liberation Sans don't contain CJK glyphs, which results in "tofu" (square blocks). Always use a font designed for the target language:
   - For **Simplified Chinese (zh-Hans)**: Use `msyh.ttc` (Microsoft YaHei) or equivalent.
   - For **Japanese (ja)**: Use `msgothic.ttc` (MS Gothic) or equivalent.
   - For **Korean (ko)**: Use `malgun.ttf` (Malgun Gothic) or equivalent.
   - If system font copying fails, stop and report it. Do not substitute with a Western font.
2. **Robust Font Creation:** Create dynamic `TMP_FontAsset` from imported fonts.
3. **Multi-Atlas & Dynamic:** CJK character sets are too large for static atlases; a single atlas will run out of space immediately.
   - `fontAsset.atlasPopulationMode = AtlasPopulationMode.Dynamic;`
   - `fontAsset.isMultiAtlasTexturesEnabled = true;`
4. **Sub-Assets:** add the atlas textures **and the material**. Adding only the texture is the usual
   mistake, and the material then never reaches the file at all: measured on Unity 6000.5.8f1, a font
   asset saved without the second call contains **zero** `Material` objects on disk, and one with it.
   A material that exists only in memory is not part of the asset, so anything that loads the asset
   fresh gets whatever TMP reconstructs rather than the material you configured, and any setting you
   applied to it is silently gone.
    ```csharp
    // Every atlas texture, not just the first. Step 3 enabled multi-atlas, so there may be several.
    foreach (var atlas in fontAsset.atlasTextures)
    {
        UnityEditor.AssetDatabase.AddObjectToAsset(atlas, fontAsset);
    }
    // The material too. Without this line it is not written into the asset.
    UnityEditor.AssetDatabase.AddObjectToAsset(fontAsset.material, fontAsset);
    ```
    - Explicitly link the material's texture: `fontAsset.material.mainTexture = fontAsset.atlasTexture;`
      and set the font asset, its material, and its textures dirty before saving. (`atlasTexture` is
      the first entry of `atlasTextures`, which is what the primary material draws from, so this is
      consistent with adding every texture above.)
    - **Verify against the file, not against the object you are holding.** After
      `AssetDatabase.SaveAssets()`, call `AssetDatabase.LoadAllAssetsAtPath(path)` and confirm a
      `Material` is among the returned objects. Do not settle for `fontAsset.material != null`: that
      stays true whether or not the material was saved, because TMP will hand back an in-memory one,
      so it cannot tell a saved material from an unsaved one.
5. **Addressables:** Every asset referenced in an Asset Table must be marked as Addressable. 
    - Do not reference assets inside a `Resources/` folder in an Asset Table. This causes `OperationException: Failed to load sub-asset` errors. If an asset is in `Resources/`, copy it to `Assets/Fonts/` or similar before making it Addressable.
    - If a font asset is deleted and recreated, the new GUID must be manually updated in the Asset Table and re-added to Addressables.
6. **Specialized Types:** For TextMesh Pro font swapping, prefer `LocalizedTmpFont` over `LocalizedAsset<TMP_FontAsset>` to avoid implicit conversion errors.
7. **Build Requirement:** After updating Asset Tables or Addressable groups, trigger a build: `AddressableAssetSettings.BuildPlayerContent();`.

### **Verification Step**
Before concluding any CJK localization task:
1. **The Tofu Check:** Switch the editor locale to `zh-Hans`, `ja`, and `ko`. Inspect the UI. If any characters appear as squares (tofu), the font setup has FAILED.
2. **Asset Table Check:** Verify that the `AssetTable` for the CJK locale points to the correct CJK `TMP_FontAsset`, NOT a default Western font.
3. **Multi-Atlas Check:** Confirm `isMultiAtlasTexturesEnabled` is `true` on the CJK font assets.

## 5. Automatic Layout (UGUI)
- **Parent:** `VerticalLayoutGroup` with `Child Control Height: True`, `Child Force Expand Height: False`.
- **Labels:** Each label must have a `ContentSizeFitter` set to `Vertical Fit: Preferred Size`.
- **TMP:** Set `Enable Word Wrapping: True` and `Overflow: Overflow`.

### Notes when translating an existing project
- **Minimal Code Changes**: Never modify code unrelated to localization. Use a static helper class (e.g., `L10n`) to wrap `LocalizationSettings.StringDatabase.GetLocalizedString` for easy injection into existing scripts.
- **Robust Mapping Strategy**: When mapping existing UI text to keys, sort keys by string length (descending) and match longest strings first. This prevents short strings (like "NO") from matching parts of longer sentences. Use case-insensitive matching where appropriate.
- **Component Event Listeners**: wire `LocalizeStringEvent.OnUpdateString` with
`UnityEventTools.AddPersistentListener`, passing a delegate built over the text component's public
`text` setter. The setter has no C# method-group name, so build the delegate by name:
`(UnityAction<string>)Delegate.CreateDelegate(typeof(UnityAction<string>), text, "set_text")`.
That is reflection over a **public** member, which is fine. See
[resources/L10nBatchProcessor.cs](resources/L10nBatchProcessor.cs) for the working version, including
clearing any existing persistent listeners first so repeated runs don't stack duplicates.
  - Do **not** write the persistent-call fields directly through `SerializedObject` (`m_MethodName`,
    `m_Mode`, `m_PersistentCalls`). Those are private serialized names with no compatibility
    guarantee, and it isn't necessary: `AddPersistentListener` with the delegate above produces the
    same serialized call (target = the text component, method = `set_text`, mode = `EventDefined`).
  - **You must then set the call state, or the label will not update in the Editor.**
    `AddPersistentListener` leaves the call at `UnityEventCallState.RuntimeOnly`, so the binding is
    correct but dormant outside Play mode: switching locale in the Editor changes nothing, and it
    stays that way through a save and reload. Fix it with the public
    `UnityEventBase.SetPersistentListenerState`:
    ```csharp
    UnityEventTools.AddPersistentListener(lse.OnUpdateString, setText);
    var index = lse.OnUpdateString.GetPersistentEventCount() - 1;
    lse.OnUpdateString.SetPersistentListenerState(
        index, UnityEngine.Events.UnityEventCallState.EditorAndRuntime);
    ```
    Verified on Unity 6000.5.8f1: without the second call the listener does not fire in Edit mode
    even after a prefab save and reload; with it the call state becomes `EditorAndRuntime` and the
    text updates immediately.
  - Persistent listeners **MUST** point to a method on a `UnityEngine.Object`; lambdas will fail.
  - **Then confirm the binding is live, don't assume it.** Wiring that looks right in the Inspector
    but does nothing is the characteristic failure of this step. All of the read-back you need is
    public API on the event, so none of this requires touching serialized fields:

    | Check | Call | Expect |
    |---|---|---|
    | Something was wired | `GetPersistentEventCount()` | `> 0` |
    | It points at the text component | `GetPersistentTarget(i)`, `GetPersistentMethodName(i)` | the component, `set_text` |
    | It will fire while authoring | `GetPersistentListenerState(i)` | `EditorAndRuntime` |
    | It actually updates the label | `lEvent.RefreshString()` | the text value changes |

    Do all four. A count above zero only proves something was wired, and a `RuntimeOnly` call fails
    the last check while being perfectly correct for a build, so reading the state is what tells a
    dormant binding apart from a broken one. A component that was added and configured but never
    fires is worse than an unlocalized label, because it reads as done.
- **Initialization & Refresh**: 
    - `LocalizationEditorSettings.CreateStringTableCollection` expects a **directory path** (e.g., `Assets/Localization`), not a full asset path.
    - Always call `lEvent.RefreshString()` after assigning a `LocalizedString` reference programmatically to update the UI immediately.
    - Keys must exist with a **non-empty value in every table** of a collection (en, de, ja, …). A key
      that exists with an empty value is the common gap, and it is not silent: the package prints its
      own "No translation found for …" text **into the game UI**, so the shipped screen shows a
      developer message. Do not eyeball this. Run the completeness check below.
- **Namespaces & Linq**: Always include `using System.Linq;` when searching collections and `using UnityEngine.Localization;` when working with locales or tables.
- **Verification**: After modifying tables or addressables, run `AddressableAssetSettings.BuildPlayerContent()` and switch the Editor locale to verify changes. Check `LocalizationSettings.Instance` status after activation.

### Table completeness check (run this before declaring the work done)

Enumerating the tables answers "did every key get a value in every locale" mechanically, so a missing
entry is found before anyone plays the game. Run it and report the output.

```csharp
var gaps = new System.Collections.Generic.List<string>();
var checkedCount = 0;

foreach (var col in UnityEditor.Localization.LocalizationEditorSettings.GetStringTableCollections())
{
    foreach (var key in col.SharedData.Entries)
    {
        foreach (var table in col.StringTables)
        {
            checkedCount++;
            var entry = table.GetEntry(key.Id);
            // A missing entry and a present-but-empty entry both show as untranslated in game.
            if (entry == null || string.IsNullOrWhiteSpace(entry.Value))
            {
                gaps.Add($"{col.TableCollectionName} / {table.LocaleIdentifier.Code} / {key.Key}");
            }
        }
    }
}

// Zero entries is not a pass. It means no collections or no locales were found, so the check
// examined nothing: report that distinctly instead of letting it read as success.
if (checkedCount == 0)
{
    return "INCONCLUSIVE: no table entries found. Either no String Table Collection exists yet, "
         + "or the collection has no locale tables. Fix that before trusting this check.";
}

return gaps.Count == 0
    ? $"COMPLETE: {checkedCount} entries checked, no gaps"
    : $"GAPS ({gaps.Count} of {checkedCount} checked):\n  " + string.Join("\n  ", gaps);
```

Verified on Unity 6000.5.8f1 against a table with one deliberately emptied `ja` value: it reports
`GAPS 1 of 4` naming exactly that entry, `COMPLETE (4 checked)` once the value is filled, and
`INCONCLUSIVE` in a project with no tables.

**Report the gap list rather than resolving it silently.** Some gaps are decisions, not mistakes: a
locale you were not asked to translate, or a key that is intentionally identical across languages.
Filling those with the English text hides the decision. List them and let the user say which are
intentional.
- **Smart Strings**: Set up smart strings where needed. Inspect the context of each string by taking the entire UI it is on, and any scripts that affect it, into account. Set the context on the string table to ensure translations make sense.

## 6. Recommended Translation Strategy
To efficiently translate an existing project, follow this multi-step workflow:

1. **Extraction & Component Setup:**
   - **Find all occurrences. There are two separate hiding places, and scanning one misses the other.**
     - **Authored text** sits on components in scenes and prefabs: legacy `UnityEngine.UI.Text` and
       TextMeshPro (`TMP_Text`, the base of `TextMeshProUGUI` and `TextMeshPro`). Walk **both**
       families. Measured on a real project: `FindObjectsByType<Text>` found 1 component while
       `FindObjectsByType<TMP_Text>` found 13, so a legacy-only pass reports success having done
       almost nothing.
     - **Text composed in code** never appears on a component at edit time, so no scene walk can see
       it. `scoreLabel.text = $"EXP {value}"` is invisible to every component-based scan and is the
       string that survives a "finished" localization pass. Find it in the C# instead:
       ```bash
       # Assignments and SetText calls that carry a string literal.
       grep -rnE '\.text\s*(=|\+=)\s*\$?"|SetText\(\s*\$?"' --include='*.cs' Assets/
       ```
       That pattern catches plain, interpolated, concatenated and `+=` forms plus `SetText`, and
       deliberately does not match `label.text = someVariable` or `label.text = Localize("KEY")`
       (nothing to extract at the first, already routed at the second). Its blind spot is a literal
       held in a variable or const declared elsewhere; if the count looks low for the project, grep
       that file's string literals too.
   - **Report what you did not convert.** A composed string usually needs a smart string or a format
     argument, which is a judgment call, and some are genuinely not worth localizing. Whichever you
     choose, list every site the scan found alongside whether it was converted, and why not if it
     wasn't. Reporting "localized 24 strings" while nine found sites went untouched is the failure
     mode this list exists to prevent: the work looks finished and the gap only surfaces in a
     screenshot from another locale.
   - **Shared Table:** Create a central String Table (e.g., `UIStrings`) with the base language and a "Context" column for each key to guide translators.
   - **Attach Components:** For every UI element found, attach a `LocalizeStringEvent` (for text) and a `LocalizedFont` helper (for font swapping).
   - **Validation:** Ensure these components are set up with persistent listeners (`EditorAndRuntime`) so they update in the Editor immediately when the locale changes.

2. **Context-Aware Translation:**
   - **Translate:** Once the table is populated, provide translations for each locale.
   - **Context is King:** Always refer to the "Context" column or inspect the UI layout to ensure the translation fits the intended meaning and space.
   - **Grammar & Tone:** Ensure the tone matches the game's style. For example, use imperative verbs for buttons (e.g., German: "Lauf!" instead of "Laufen") and correct pluralization for labels (e.g., "Punkte" instead of "Punkt").

3. **Quality Assurance (QA):**
   - **Scene Controls:** Use `Window > Asset Management > Localization Scene Controls` or script: `LocalizationSettings.SelectedLocale = LocalizationSettings.AvailableLocales.GetLocale("de");`.
   - **Visual Inspection:** Methodically inspect every prefab and scene in the base language and all target languages.
   - **Layout Fit:** Check for text overflows or "tofu" (missing glyphs). Adjust font sizes or use `ContentSizeFitter` if strings are too long.


## API Reference
For detailed API usage, common namespace conflicts, Addressables patterns, and font repair steps, see [references/api-notes.md](references/api-notes.md).

## 7. Accelerated Localization Workflow
To localize an entire project efficiently, use a batch processing script that handles all scenes in one pass.

**Ask before acting:** Before running any batch operation, confirm with the user:
> "This will open every scene in the project, attach `LocalizeStringEvent` components, and save all modified scenes. This cannot be undone automatically. Shall I proceed?"

Only proceed once the user has confirmed. The batch processor template is in [resources/L10nBatchProcessor.cs](resources/L10nBatchProcessor.cs).

It walks **both** `Text` and `TMP_Text`, and `LocalizeAll` **returns the labels it could not match**
(as `scene :: object :: "text"`). Print that list. It is the whole point of the return value: a run
that wires 20 labels and silently leaves 9 alone looks identical to a complete one otherwise. The
list covers authored text only, so pair it with the code scan in Section 6 and the table completeness
check in Section 5.

### **Technical Tips for Speed**
- **Table References:** Use `TableReference` names (strings) instead of GUIDs — they are easier to read and maintain.
- **Batch Refresh:** Use `LocalizationSettings.Instance.ForceRefresh()` after modifications to force the UI to update in the editor.
- **Font Swap Automation:** Create the `GameAssets` table once and use a script to re-assign `LocalizeFontEvent` to all labels in one pass.
- **LocalizedFontAsset component:** The template is in [resources/LocalizedFontAsset.cs](resources/LocalizedFontAsset.cs).

Referenced files: 3

View saved version →

---
name: manage-sprite-atlas
description: Manage SpriteAtlas using prebuild pipeline with IPreprocessBuildWithReport (DEFAULT approach). Use it to configure master atlases, variant atlases, texture settings, packing settings, and platform-specific configurations. Use when the user asks about creating sprite atlases, optimizing sprites, configuring atlas settings, adding sprites to atlases, creating variant atlases, implementing automated atlas generation, or runtime sprite atlas access. Always use prebuild approach unless user explicitly requests manual authoring.
---

# 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 sprite atlases?"

**Option A: Built-in Data (Immediate Loading)**
- Atlases are included in the build and loaded immediately
- Set `includeInBuild = true`
- **Suitable for**: Core UI, main gameplay sprites, always-needed assets
- **Pros**: Simple, no additional packages, instant access
- **Cons**: Increases initial build size, cannot update without new build

**Option B: Late-Binding via Addressables (On-Demand Loading)**
- Atlases are NOT included in build, loaded on-demand via Addressables
- Set `includeInBuild = false`
- Create Addressables entries for each atlas
- Add addressable setup as prebuild step
- **🚨 REQUIRED**: Build Addressables content as build step
- **🚨 REQUIRED**: Create late-binding runtime loader script
- **Suitable for**: DLC content, optional features, large assets, downloadable content
- **Pros**: Smaller initial build, can update independently, on-demand loading
- **Cons**: Requires Addressables package, async loading, network dependency

| Use Case | Recommended |
|----------|-------------|
| Core UI sprites that are always visible | **Option A: Built-in** |
| Tutorial or onboarding sprites | **Option A: Built-in** |
| Level-specific sprites (100+ levels) | **Option B: Addressables** |
| DLC or seasonal content | **Option B: Addressables** |
| Localized UI sprites (multiple languages) | **Option B: Addressables** |
| Character skins or cosmetics | **Option B: Addressables** |

### 2. SpritePacker Mode (REQUIRED)

**Enable Sprite Packer mode before creating atlases, then read the setting back and confirm it took.**
Use the code in [resources/enablespritepacking.cs](resources/enablespritepacking.cs); it sets
`EditorSettings.spritePackerMode` and configures the importer's packing settings.

This is the step that decides whether the atlas you produce is real. `Disabled` is the zero value of
`SpritePackerMode`, so any project where nobody has set it carries packing **Disabled**, and an atlas
created while it is Disabled still imports, still shows up as an asset, and still looks finished, but
can never pack. Unity says so in the Inspector: *"Sprite Atlas packing is disabled"*. Nothing else in
the workflow fails, so an atlas shipped this way reads as a success. Do not assume a project is
already configured: read the value.

So do not treat "I set it" as done. After setting it, read `EditorSettings.spritePackerMode` back,
confirm it is **not** `Disabled`, and report the value you actually read. If you cannot read it back,
say so rather than assuming the write landed.

**DO NOT edit meta files DIRECTLY.**

## 🚨 CRITICAL: Default Approach is Prebuild Generation

**ALWAYS use `IPreprocessBuildWithReport` to automatically generate or update SpriteAtlases during the build pipeline.** This is the DEFAULT and REQUIRED approach unless the user EXPLICITLY requests manual authoring.

### ❌ DO NOT Create Manual Menu Item Scripts

**NEVER create scripts with `[MenuItem]` attributes for atlas generation unless explicitly requested.** The prebuild approach eliminates the need for manual clicks. **Only use manual authoring for**: Hand-optimized layouts, specific sprite arrangements, or editor preview requirements. See [Advanced: Manual Authoring](#advanced-manual-authoring).

## 🚨 CRITICAL: Sprite Source Location Restriction

**ONLY add sprites from the project's Assets folder. NEVER add sprites from Unity built-in assets, packages, or external locations.** Unity built-in assets cannot be packed into SpriteAtlas, and package assets may cause import/dependency issues.

## Critical V2 Architecture

| Context | Component | Purpose | Allowed Usage |
|---------|-----------|---------|---------------|
| **Editor Authoring** | `SpriteAtlasAsset` | Add/remove sprites/folders; store metadata | ✅ Editor scripts only |
| **Editor Settings** | `SpriteAtlasImporter` | Configure texture, packing, platform settings | ✅ Editor scripts only |
| **Editor Packing** | `SpriteAtlasUtility.PackAtlases()` | *Optional* editor preview packing (not for build) | ⚠️ Only for preview; atlases auto-pack at build |
| **Runtime** | `SpriteAtlas` | Query packed sprites (read-only) | ✅ Runtime scripts only |
| **Runtime Loading** | `SpriteAtlasManager` | Dynamic loading callbacks | ✅ Runtime scripts only |

### Forbidden Cross-Context Usage (Common Error Sources)

| ❌ Invalid Pattern | ✅ Correct Pattern |
|--------------------|-------------------|
| `new SpriteAtlas()` in editor code | Use `SpriteAtlasAsset` + `SpriteAtlasImporter` |
| `AssetDatabase.LoadAssetAtPath<SpriteAtlas>(...)` in editor | Use `SpriteAtlasAsset.Load(...)` |
| `SpriteAtlasAsset.GetPackables()` in editor | Use `SpriteAtlas.GetPackables()` |
| Modifying `SpriteAtlas` in editor scripts | Modify `SpriteAtlasAsset` → reimport → use `SpriteAtlasImporter` |
| Create variants from original packable objects (sprites/folders) | Creating variants from a Master runtime `SpriteAtlas` |

**NEVER script against `SpriteAtlas` in editor code** — it is *only* for runtime use in V2 except for GetPackables.

## Core V2 Workflow (Reference Only - Use Prebuild Instead)

> 🚨 **IMPORTANT**: This workflow is shown for reference only. **ALWAYS implement this inside `IPreprocessBuildWithReport.OnPreprocessBuild()`** rather than in manual scripts. See [Quick Start](#quick-start-automated-prebuild-generation-default-approach).

## Prerequisites

- Unity 6000.3 or later
- Basic understanding of Unity's asset import pipeline
- Familiarity with editor scripting for atlas authoring

## Quick Start: Automated Prebuild Generation (DEFAULT APPROACH)

### Overview

**This is the PRIMARY and DEFAULT way to create SpriteAtlases.** Implement `IPreprocessBuildWithReport` to automatically generate or update SpriteAtlases before each build based on categorization rules. No manual menu clicks required.

### Workflow Steps

**Step 1: Ask User for Delivery Mechanism**

Before generating code, ask: "How do you want to deliver the sprite atlases: (A) Built-in data or (B) Late-binding via Addressables?"

**Step 2: Create Prebuild Script**

Create this script in an Editor folder. Customize based on user's delivery choice:

### Option A: Built-in Data (Immediate Loading)

Built-in Data (Immediate Loading)

### Option B: Late-Binding via Addressables (On-Demand Loading)

> 🚨 **CRITICAL ENFORCEMENT**: When user chooses Addressables, you MUST generate ALL THREE scripts below. Never generate just one or two - all three are required for Addressables delivery to work.

**Required Scripts (ALL THREE MANDATORY):**

1. **Prebuild script** (IPreprocessBuildWithReport) - Generates atlases, creates Addressables entries
2. **Build Addressables script** (IPostprocessBuildWithReport) - Builds Addressables content bundles
3. **Late-binding runtime loader** (MonoBehaviour) - Handles on-demand loading at runtime

See [references/addressables-delivery.md](references/addressables-delivery.md) for complete implementation.

#### Complete Workflow

```
User Request
    ↓
Step 0: Check for existing scripts with [UNITY-SKILL:SPRITEATLAS] identifier
    ↓
    ├─ Found existing scripts?
    │   ↓ YES
    │   Ask user: Update existing / Create new / Abort
    │   ↓
    │   Handle user choice
    │
    └─ NO existing scripts or user chose "Create new"
        ↓
        Ask "Built-in data or Addressables?"
        ↓
        ├─ Option A: Built-in
        │   ↓
        │   Generate 1 script: Prebuild generator (includeInBuild=true)
        │
        └─ Option B: Addressables
            ↓
            Generate 3 scripts:
              1. Prebuild: Generate atlases + create Addressables entries (includeInBuild=false)
              2. Postprocess: Build Addressables bundles
              3. Runtime: Late-binding loader component
```

**Step 3: Customize Categorization Rules**

Edit the `OnPreprocessBuild` method to match your project's sprite organization. Choose one or combine multiple strategies:

| Strategy | When to Use | Implementation |
|----------|-------------|----------------|
| **Folder-based** | Sprites organized by folder structure | `GenerateAtlasByFolder("Assets/Art/UI", "Assets/Atlases/UI.spriteatlasv2")` |
| **Naming convention** | Sprites follow naming patterns | `GenerateAtlasByNaming("Assets/Art", "icon_", "Assets/Atlases/Icons.spriteatlasv2")` |
| **Asset labels** | Sprites tagged with labels |
| **Scene-based** | Sprites used in specific scenes | Query scene references |

**Step 4: Build Your Project**

Atlases are automatically generated/updated during build. **No manual menu clicks required.** This is why prebuild is the default approach.

**For Built-in Data (Option A):**
- Atlases are included in build
- Ready for immediate use at runtime

**For Addressables (Option B) - Additional Required Steps:**

You MUST generate THREE scripts (not just one):

1. **Prebuild script** (IPreprocessBuildWithReport) - Generates atlases and creates Addressables entries automatically
2. **Build Addressables script** (IPostprocessBuildWithReport) - Builds Addressables content bundles
3. **Late-binding runtime loader** (MonoBehaviour) - Handles on-demand loading via SpriteAtlasManager

The build process will:
- Generate atlases (prebuild step)
- Create addressable entries automatically
- Build addressables content bundles (postprocess step)
- At runtime: Late-binding loader automatically loads atlases when sprites are first accessed

### Common Categorization Patterns

**By Folder Structure:**
```csharp
GenerateAtlasByFolder("Assets/Art/UI/Buttons", "Assets/Atlases/UI_Buttons.spriteatlasv2");
GenerateAtlasByFolder("Assets/Art/UI/Icons", "Assets/Atlases/UI_Icons.spriteatlasv2");
GenerateAtlasByFolder("Assets/Art/Characters/Player", "Assets/Atlases/Player.spriteatlasv2");
```

**By Naming Convention:**
```csharp
GenerateAtlasByNaming("Assets/Art", "icon_", "Assets/Atlases/Icons.spriteatlasv2");
GenerateAtlasByNaming("Assets/Art", "bg_", "Assets/Atlases/Backgrounds.spriteatlasv2");
```

### Variant Generation in Prebuild

Generate variant atlases for different resolutions.

## Advanced: Manual Authoring (NOT Default - Use Only When Explicitly Requested)

> ⚠️ **WARNING**: Manual authoring is NOT the default approach. Only use these patterns when the user EXPLICITLY requests manual control or editor preview during development.

> 🚨 **DEFAULT APPROACH**: Use prebuild generation with `IPreprocessBuildWithReport` instead. See [Quick Start](#quick-start-automated-prebuild-generation-default-approach).

**Manual authoring is appropriate ONLY for:**
- Hand-optimized sprite layouts where exact positioning matters
- Custom sprite ordering requirements
- Editor preview during authoring workflow
- Explicitly requested by user

**DO NOT use manual authoring when:**
- User asks to "create sprite atlas" (use prebuild)
- User asks to "optimize sprites" (use prebuild)
- User asks for automated workflow (use prebuild)
- No specific manual control requirement mentioned

For complete manual authoring patterns including master atlas creation, variant creation, and runtime loading, see [references/manual-authoring.md](references/manual-authoring.md).

## Key Requirements (V2-Specific)

1. **🚨 ALWAYS check for existing scripts FIRST**: Before generating code, scan for scripts with `[UNITY-SKILL:SPRITEATLAS]` identifier and prompt user to update or create new
2. **🚨 ALWAYS tag generated scripts**: Include skill identifier at the top of every generated script for future detection
3. **🚨 ALWAYS ask for delivery mechanism**: Ask user "Built-in data or Addressables?" before generating code
4. **🚨 ALWAYS enable Sprite Packer mode**: Set `EditorSettings.spritePackerMode = SpritePackerMode.SpriteAtlasV2` in prebuild script
5. **🚨 ALWAYS use prebuild generation**: Implement `IPreprocessBuildWithReport` as the DEFAULT approach for creating atlases
6. **🚨 ONLY add sprites from Assets/ folder**: Never add sprites from Packages, built-in assets, or external locations
7. **🚨 For Addressables delivery, ALWAYS generate THREE scripts**:
   - Prebuild atlas generator with Addressables setup
   - `IPostprocessBuildWithReport` to build Addressables content
   - Late-binding runtime loader script (extends `SpriteAtlasManager`)
8. **Set includeInBuild correctly**: `true` for built-in data, `false` for Addressables
9. **Two-Step Editor Pattern**: Create with `SpriteAtlasAsset` → Save → Import → Configure via `SpriteAtlasImporter` → SaveAndReimport()
10. **Never use `SpriteAtlas` in editor code** — except `SpriteAtlas.GetPackables()` instance method on a loaded runtime atlas
11. **Variants reference master**: Use `SetMasterAtlas(SpriteAtlas)` with runtime instance loaded via `AssetDatabase.LoadAssetAtPath<SpriteAtlas>()`
12. **Platform format assignment**: Use `format = TextureImporterFormat.ASTC_6x6` directly (no cast)
13. **File extension**: V2 atlases use `.spriteatlasv2` (not `.spriteatlas`)
14. **`SpriteAtlasUtility.PackAtlases()` is optional**: Only for editor preview; build-time packing is automatic

For common errors and invalid patterns, see [references/common-errors.md](references/common-errors.md).

## Detailed Reference

- **Addressables Delivery**: [references/addressables-delivery.md](references/addressables-delivery.md) - Complete late-binding setup with Addressables
- **Manual Authoring**: [references/manual-authoring.md](references/manual-authoring.md) - Manual patterns (NOT default - use only when explicitly requested)
- **Common Errors**: [references/common-errors.md](references/common-errors.md) - Invalid patterns and API corrections
- **API Reference**: [references/api.md](references/api.md) - Complete V2 class documentation
- **Custom Packing**: [references/custom-packing.md](references/custom-packing.md) - `ScriptablePacker` implementation
- **Best Practices**: [references/best-practices.md](references/best-practices.md) - Optimization and common pitfalls

## Namespaces

**Editor Scripts:**
```csharp
using UnityEditor;            // AssetImporter, AssetDatabase
using UnityEditor.U2D;        // SpriteAtlasAsset, SpriteAtlasImporter, SpriteAtlasUtility
using UnityEngine;            // Runtime types (e.g., TextureImporterFormat)
using UnityEngine.U2D;        // SpriteAtlas
```

**Runtime Scripts:**
```csharp
using UnityEngine;            // Core Unity types
using UnityEngine.U2D;        // SpriteAtlas, SpriteAtlasManager
```

Referenced files: 44

View saved version →

---
name: migrate-birp-to-urp
description: Plans, executes, and troubleshoots Unity projects moving from the Built-in Render Pipeline (BiRP/BIRP/Built-in RP) to the Universal Render Pipeline (URP). Use when the user asks to upgrade, convert, switch, or migrate a project, scene, material, or shader to URP/Universal Render Pipeline; fix pink or magenta materials after URP; convert Built-in materials/shaders; move a 2D project to URP 2D; review lighting, quality, post-processing, baked lightmaps, or reflection probes after URP; or diagnose visual problems after a render-pipeline migration.
---
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 "complete" result.

Ask configuration questions only when the project state or user intent leaves a real decision unresolved. If the user says "do not modify files", stay in audit/planning mode and do not perform conversion or asset edits.

### Generic Upgrade Contract

When the user gives a generic migration request and permits changes, drive the next phase from the project state:

1. Do not ask the user to enumerate known Built-in features before inspection. Discover them.
2. If PPv2, baked lighting, reflection probes, particle/fog/smoke materials, or multiple Quality levels exist, include them in the migration automatically.
3. Prefer phase completion over all-in-one completion. Each phase should save/re-query its own outputs and end with `Phase complete`, `Phase partial`, or `Blocked`.
4. If Unity compilation, package installation, domain reload, or a long lighting bake interrupts the pass, report the interruption as a phase boundary and resume from saved partial state in the next turn rather than starting over.
5. Do not rely on the user writing a detailed checklist prompt to get correct behavior. The detailed checklist is for benchmarking or stress testing; normal user prompts should still trigger this phased contract.
6. A generic migration request gives permission to inspect and plan, but it does not prove rollback safety. If no rollback point is confirmed, stop before package install or URP assignment and ask for confirmation. Do not leave the project in a magenta partial state just to reach the backup question.
7. If rollback safety is already confirmed or the user says the project is a disposable copy, continue within the current phase without asking again for routine work.
8. At the end of a phase, give a concise next-phase prompt or say what phase should run next. Ask for confirmation before the next phase only when it introduces a new costly or risky operation, such as a long lighting bake, deletion/cleanup of legacy assets, or a custom shader rewrite.
9. If rollback safety was confirmed and ordinary work inside the active phase remains incomplete, do not ask "would you like me to continue?" Continue repairing that phase until its gate passes, a tool/domain-reload boundary interrupts execution, or a genuinely new risky decision appears.

### Generic Migration Success Gate

Before saying a generic migration is "successful", "complete", or "fully migrated", verify saved project state, not just tool logs:

1. Graphics settings and every relevant Quality level point to the intended URP asset.
2. The URP asset has a valid default renderer in saved state, and current Console output does not contain unresolved render-pipeline errors such as "Default Renderer is missing". If a renderer error appears after assignment, re-query the saved renderer list/default index, clear stale Console output when possible, trigger a fresh scene/camera validation, and continue repair instead of stopping at "URP setup complete".
3. Supported Built-in materials, including particle/fog/smoke materials, have URP-compatible shaders or are explicitly listed as unresolved custom/package shader cases. Textured/colorized source materials must preserve their source maps/colors; a URP shader assignment with missing `_BaseMap` or all-white `_BaseColor` is incomplete if the source `_MainTex` or `_Color` had content. Particle, fog, smoke, steam, decal, VFX, additive, and transparent effect materials should not be blindly forced to `Universal Render Pipeline/Lit`; prefer URP particle/effect shaders such as `Universal Render Pipeline/Particles/Unlit` when appropriate.
4. If the source scene used PPv2, a saved URP `VolumeProfile` exists with persistent non-null override components, the representative scene references it through a URP `Volume`, and legacy PPv2 is disabled for URP visual validation. A saved profile with `components: []`, `{fileID: 0}` component refs, or a scene that still only references the old `PostProcessProfile` is incomplete.
5. If the representative scene uses baked/mixed lighting, an Enlighten/realtime-GI Lighting Settings asset, a Lighting Data asset, lightmaps, light probes, or reflection probes, do not leave routine lighting/probe repair as manual follow-up during a generic full migration. Attempt URP-compatible Lighting Settings assignment, clear/rebake or resume a bake when needed, refresh reflection probes when feasible, then save/reload and verify the scene references the intended lighting state. Creating a `.lighting` asset and calling `Lightmapping.lightingSettings = target` plus `AssetDatabase.SaveAssets()` is not enough; mark/save the scene, reload/re-query, and compare the saved scene `m_LightingSettings` reference or asset GUID. If a long bake or tool interruption prevents this, call the migration partial and resume from that phase.
6. A representative scene has been opened or selected deliberately before migration validation; do not infer baked-lighting or PPv2 absence from a default/test scene. The scene has been captured or inspected after saving/reloading, and Console output has been checked for render-pipeline, shader, or renderer-feature errors.
7. Final wording must match the gate result. Use "complete" only when every gate passes. Use "partial" when URP is set up but PPv2 Volume persistence, legacy PPv2 disablement, lighting bake/probe refresh, or saved-state validation remains. Do not start the final response with "successfully migrated" if any required gate is partial.

Complete-report checklist:

- If the old PPv2 profile contains active `DepthOfField`, the new URP profile must contain a saved `DepthOfField` override or the final report must call it omitted/manual.
- If the old PPv2 profile contains active `AmbientOcclusion`, configure a URP SSAO renderer feature when feasible, or mark AO as manual/partial.
- If the old PPv2 profile contains active `ScreenSpaceReflections`, list SSR as unsupported/manual unless a URP renderer-feature/custom replacement was actually added and validated.
- If the scene still serializes the old Lighting Settings GUID or a non-zero old `m_LightingDataAsset`, lighting is partial.
- If the scene has reflection probes and the URP asset still serializes `m_ReflectionProbeBlending: 0` or `m_ReflectionProbeBoxProjection: 0`, reflections are partial unless intentionally disabled and reported.
- If any checklist item is false, do not use "complete", "fully migrated", or "fully functional on URP" in the final answer.

Unsupported features can remain manual, but name them precisely. Examples include PPv2 Screen Space Reflections needing a URP renderer-feature/custom/third-party replacement, complex custom shader ports, `GrabPass`, replacement shaders, or package-owned rendering code. If any success-gate item fails, continue repairing when allowed or report a partial migration with incomplete items; do not present the project as fully migrated.

Regression guard summary:

- Use the detailed [Execution Regression Checklist](references/implementation-patterns.md#execution-regression-checklist) for actual migration or repair work.
- Verify saved scene references before status claims: URP Volume/profile, Quality assignments, Lighting Settings/Data, URP asset/renderer, and reflection-probe settings.
- Preserve material source data from a pre-conversion snapshot, then restore `_BaseMap`, `_BaseColor`, texture scale/offsets, and relevant maps after shader changes.
- Validate representative visuals for PPv2, foliage, particles/effects, baked lighting, probes, and exposure before final wording.
- Report exact phase status. `Phase complete` is allowed for a passed phase; project-level `complete` is allowed only when every success gate passes.

## Execution path: running C# in the Editor

Every C# step in this skill 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.
- **On an Editor older than 6000.3, expect the Pipeline package not to work at all**, and read the
  symptom correctly rather than retrying. `com.unity.pipeline` uses `IPreprocessBuildWithContext`
  and `BuildCallbackContext`, which Unity introduced in **6000.3**; the package's own manifest
  declares `"unity": "6000.0"`, so it installs happily and then fails to compile. Measured:
  present in 6000.3 / 6000.4 / 6000.5, absent in 6000.0 / 6000.1 / 6000.2 and in the 2022 and 2023
  lines. The symptom is misleading — the server never starts, `unity status` shows no row and no
  error, and the real cause is `CS0246` on those two types in the Editor log. If you see that,
  tell the user the Editor is too old for the Pipeline package rather than debugging the CLI.

  **This matters here more than in most skills:** someone migrating a project off the Built-in
  pipeline is, by definition, often on an older Editor.
- **A render-pipeline migration is not safely authorable blind.** Assigning a URP asset, converting
  materials, and rebaking lighting all need a live Editor. An unreachable Editor is a stop, not a
  cue to hand-edit `ProjectSettings/GraphicsSettings.asset`.

Run C# with `unity command eval --caller plugin --skill migrate-birp-to-urp --code '<snippet>'`. `unity command` defaults to a 30 second
timeout, which matters here: installing URP triggers a package refresh and domain reload that will
outlast it. Treat that as a phase boundary rather than raising the timeout.

### Passing C# to `eval`

`eval` compiles a **statement block, not a file**. Three consequences, all 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 `GraphicsSettings` or `Volume` does not resolve
  (`CS0246` / `CS0103`), and a bare `Object` is ambiguous with `object` (`CS0104`).
- **Extension methods are unavailable**, because they resolve through `using`. Two that this skill
  would otherwise reach for: `camera.GetUniversalAdditionalCameraData()` becomes
  `camera.GetComponent<UnityEngine.Rendering.Universal.UniversalAdditionalCameraData>()`, and LINQ
  calls must be written statically — `System.Linq.Enumerable.FirstOrDefault(sequence, predicate)`
  rather than `sequence.FirstOrDefault(predicate)`.

### Two execution modes — pick by the snippet's shape

The references carry both shapes, and they are not interchangeable:

- **Statement-shaped** (a bare sequence of statements, like the detection snippets above) — pass
  straight to `eval`, fully qualified, with no `using` lines.
- **Class- or method-shaped** (anything declaring a `class`, a `static` method, or a `[MenuItem]`,
  such as the material-snapshot pattern) — these are **project files, not `eval` input**. A class
  declaration cannot be flattened into a statement block. Save the snippet under
  `Assets/Editor/`, let Unity compile it, then invoke its entry point through a one-line `eval`
  call. Keep the `using` directives in that file; they are correct there.

For a multi-step migration the script route is the more reliable one anyway: it survives the domain
reloads that URP installation and material conversion trigger, whereas a long `eval` payload does
not.

### Detecting the active render pipeline

```csharp
var rp = UnityEngine.Rendering.GraphicsSettings.defaultRenderPipeline;
var qrp = UnityEngine.QualitySettings.renderPipeline;
return $"graphics={(rp == null ? "NULL (Built-in)" : rp.GetType().Name + ":" + rp.name)}, "
     + $"activeQualityLevel={(qrp == null ? "inherits Graphics" : qrp.GetType().Name + ":" + qrp.name)}";
```

A `UniversalRenderPipelineAsset` means URP; `HDRenderPipelineAsset` means HDRP; `NULL` on both
means Built-in. **Check the per-quality-level assignment too** — a project can be switched in
Graphics settings while a Quality level still points at a different asset, or at none:

```csharp
var names = UnityEngine.QualitySettings.names;
var rows = new System.Collections.Generic.List<string>();
for (int i = 0; i < names.Length; i++)
{
    var a = UnityEngine.QualitySettings.GetRenderPipelineAssetAt(i);
    rows.Add($"{i}:{names[i]}={(a == null ? "inherits Graphics" : a.name)}");
}
return string.Join(", ", rows);
```

If `GetRenderPipelineAssetAt` is unavailable in the project's Unity version, read
`ProjectSettings/QualitySettings.asset` instead rather than switching levels at runtime —
`SetQualityLevel` mutates project state.

## 0. Pre-Flight: Pipeline Detection and Reference Loading

Before doing anything else, you **must determine the active render pipeline and migration mode**:

1. **Detect Pipeline:** Run the render-pipeline detection snippet from the execution-path section above.
   - If `currentRenderPipeline` or `defaultRenderPipelineAsset` references a `UniversalRenderPipelineAsset` -> **URP**.
   - If no render pipeline asset is assigned -> **Built-in**.
   - If it references an `HDRenderPipelineAsset` -> **HDRP**. Explain that this skill only covers Built-in to URP migration. Basic comparison advice is fine, but do not drive an HDRP migration with this skill.
2. **Load Base Reference:** Read [references/migration-workflow.md](references/migration-workflow.md).
3. **Load Shader References When Relevant:** If the request mentions materials, shaders, magenta materials, rendering errors, image effects, or custom rendering, also read:
   - [references/custom-shader-triage.md](references/custom-shader-triage.md)
   - [references/complex-shader-situations.md](references/complex-shader-situations.md) when inspection or project-file search finds advanced shader/effect patterns
4. **Load Quality Reference When Relevant:** If the request mentions shadows, lighting, baked lighting, lightmaps, reflection probes, quality settings, visual mismatch, or performance after migration, also read [references/quality-settings-map.md](references/quality-settings-map.md).
5. **Load Implementation Patterns When Executing:** If the request permits actual migration changes, post-processing conversion, baked-lighting/probe repair, or resume from a partial migration, also read [references/implementation-patterns.md](references/implementation-patterns.md).
6. **Classify the Request** as one of:
   - Full-project Built-in to URP migration
   - Built-in 2D to URP 2D migration
   - Selected material-only conversion
   - Planning / explanation only
   - Troubleshooting after a previous migration
7. **If the project is already on URP,** switch to troubleshooting mode instead of re-running setup blindly.
8. **Proceed** only after the pipeline and migration path are clear.

## 1. Assess Current Migration State

Before making any changes, **inspect what already exists**:

1. **Inspect pipeline state and assignment points:**
   - Run both render-pipeline detection snippets from the execution-path section above — the Graphics-settings one and the per-quality-level one.
   - If the project has Quality levels, inspect which Render Pipeline Asset each level uses before assuming the project is fully switched.
2. **Inventory migration surfaces:** Use `eval` with `UnityEditor.AssetDatabase.FindAssets` or equivalent asset queries to inventory:
   - materials, including particle/VFX materials that often use built-in particle shaders
   - vegetation materials, including grass, tree, terrain-detail, SpeedTree, billboard, leaf-card, cutout, and wind-driven foliage materials
   - shaders
   - scenes and important prefabs
   - URP assets and renderer assets, if any
   - post-processing profiles / volume profiles
   - Lighting Settings assets, Lighting Data assets, lightmaps, light probes, reflection probes, and mixed/baked lights
3. **Scan for rendering risk markers:** Use available project-file search, `AssetDatabase.FindAssets`, or a short `eval` file scan to search the project for rendering-specific patterns such as:
   - `PostProcessLayer`, `PostProcessVolume`, `UnityEngine.Rendering.PostProcessing`
   - `OnRenderImage(`, `RenderWithShader`, `SetReplacementShader`
   - `#pragma surface`, `GrabPass`, `CGPROGRAM`
   - `CommandBuffer`, custom shader include paths, or package shader namespaces
   - vegetation markers such as `Nature/`, `SpeedTree`, `TreeCreator`, `Grass`, `Foliage`, `_Cutoff`, `_AlphaClip`, `_Cull`, billboard, or wind keywords
4. **If PPv2 is installed but grep finds nothing,** inspect open scenes and profile assets through Unity APIs by component/type. Scene YAML and serialized package references can be missed by text search.
5. **Determine project shape:** Decide whether the project is primarily 3D, primarily 2D, or mixed.
6. **Report Findings:** Summarize the current state before proposing conversion. Example:
   - "The project is still on Built-in, has no URP asset assigned, contains PPv2 references, and includes several custom shaders using surface-shader syntax."

## 2. Gather Requirements

Determine what the user actually wants. If the request is ambiguous, ask.

Use these defaults for common requests:

| User says | Default interpretation |
|-----------|------------------------|
| "Upgrade this project to URP" | Full-project migration |
| "Move this 2D project to URP" | Built-in 2D to URP 2D migration |
| "Convert these materials" | Targeted material conversion |
| "My materials turned pink" | Post-migration shader/material troubleshooting |
| "Lighting looks wrong after URP" | Quality and visual parity troubleshooting |
| "Do not change anything yet" | Planning / audit only |

### Information to Gather

- **Scope:** full project, selected materials, or troubleshooting only
- **Target renderer:** standard URP or URP 2D
- **Validation targets:** which scenes, prefabs, or cameras matter most to the user
- **Risk tolerance:** whether limited manual follow-up is acceptable
- **Rendering dependencies:** custom shaders, Asset Store shaders, PPv2, baked lighting/lightmaps/probes, image effects, command buffers, replacement shaders, or multiple Quality levels
- **Execution permission:** planning only vs actual project changes

## 3. Safety Gate

Before any pipeline-mutating step:

1. **Confirm rollback safety.**
   - NEVER install URP, assign a URP asset, run the Render Pipeline Converter, edit materials, or edit migration scene state before the user confirms a backup, branch, archive, disposable copy, or rollback point.
   - If rollback safety is missing, do not partially switch the project to URP. Stop in planning mode and ask for the rollback confirmation first.
2. **Separate engine-upgrade risk from pipeline-upgrade risk.**
   - If the project is also moving to a new Unity version, recommend doing the engine upgrade first and the pipeline migration second. Do not treat both as a single blind operation.
3. **If rollback safety is confirmed,** treat it as covering the whole migration pass. Do not ask again before each converter; proceed through setup, material conversion, PPv2 migration, lighting/probe work, save/reload verification, and final reporting unless a new risky decision appears.
4. **If the user already authorized a full disposable migration,** do not ask for permission to continue after routine setup or recoverable errors. Continue with the next incomplete migration phase. Ask only when a new destructive cleanup decision appears, a package/domain reload stops execution, or repeated repair attempts hit the validation iteration limit.
4. **If the project is already partially migrated,** identify whether rollback safety was previously confirmed. If yes, resume from the first incomplete item. If no, report the partial state and ask before making additional changes.

## 4. Choose the Migration Path

Use the correct path for the project:

### Path A: Standard 3D Built-in to URP
- Use this for normal 3D Built-in projects moving to standard URP.

### Path B: Built-in 2D to URP 2D
- Use this when the project is primarily 2D and the user expects URP 2D lighting or renderer behavior.
- Do not treat this as the same workflow as standard URP.

### Path C: Targeted Material-Only Conversion
- Use this only when the project is already on URP and the user wants selected materials converted.

### Path D: Troubleshooting an Existing Migration
- Use this when the project is already on URP or the migration has already been attempted.
- Prioritize the highest-impact breakages instead of re-running the entire migration blindly.

## 5. URP Setup Workflow

Follow this exact setup order:

1. **Ensure URP is installed.**
   - Installing URP can trigger package refresh, compilation, and domain reload. Treat this as a phase boundary.
   - Do not spin-wait indefinitely inside an `eval` call on `UnityEditor.PackageManager.Client.Add`. Request installation, then verify through `Packages/manifest.json`, package listing, or the presence of URP types/assets after Unity finishes refreshing.
   - If the package install causes the `eval` call to time out or return nothing, resume in a fresh turn after Unity finishes compiling. Do not restart the whole migration or reinstall URP; inspect the partial state and continue from there.
2. **Create the required URP asset and renderer asset** if they do not already exist.
3. **Assign the URP asset in Graphics settings** and in all relevant Quality levels.
4. **For 2D projects,** create and assign the correct 2D Renderer asset before conversion.
5. **If a URP asset already exists,** inspect and reuse it when appropriate instead of creating duplicates automatically.
6. **Do not continue** until URP is actually the active render pipeline for the target configuration.

## 6. Conversion Workflow

For actual conversion work, follow [references/migration-workflow.md](references/migration-workflow.md).

1. **Choose the correct Render Pipeline Converter path:**
   - `Built-in Render Pipeline to URP`
   - `Built-in Render Pipeline 2D to URP 2D`
2. **Initialize converters and inspect the candidate changes** before converting.
3. **For standard Built-in to URP migration,** prefer the applicable converters described in the reference:
   - `Rendering Settings`
   - `Material Upgrade`
   - `Animation Clip Converter`
   - `Read-only Material Converter`
   - `Post-processing Stack v2 Converter`
4. **For selected-material conversion,** use the targeted material conversion workflow instead of converting the whole project.
5. **Review warnings and failures before converting.**
6. **Run the conversion only after the user confirms the project is safe to change.**
7. **Verify which shader each material actually landed on** — do not assume the converter chose the 3D
   target. `MaterialUpgrader.FetchAllUpgradersForPipeline` returns the 2D provider set alongside the 3D
   one, and both claim `Standard` at equal priority, so on a 3D project a plain `Standard` material can
   silently convert to `Universal Render Pipeline/2D/Mesh2D-Lit-Default` instead of
   `Universal Render Pipeline/Lit`. Nothing errors and the material does not go magenta, so this is
   invisible unless you read the shader name back — measured on 6000.5.8f1.

   Read every converted material's `shader.name` afterwards and confirm it matches the intended target
   from the mapping table. If any landed on a `2D/` shader in a 3D project, restore those materials from
   the rollback point and convert them with a 3D-filtered upgrader list, or with the manual pattern in
   [references/implementation-patterns.md](references/implementation-patterns.md).
7. **After conversion, verify the saved project state.**
   - Re-open or re-query representative assets instead of trusting command output alone.
   - Save both assets and open scenes after scene-level edits. Changes to scene components, camera data, active lighting settings, reflection probes, and PPv2 enable states are not proven by `AssetDatabase.SaveAssets()` alone.
   - Confirm the URP asset is assigned in Graphics and intended Quality levels.
   - For Quality levels, validate by re-querying `QualitySettings.GetRenderPipelineAssetAt(i)` or by reading the saved `customRenderPipeline` entries in `ProjectSettings/QualitySettings.asset`. If they remain `{fileID: 0}`, the Quality levels are not explicitly assigned.
   - Do not call a guessed quality API such as `QualitySettings.SetRenderPipelineAssetAt`; in Unity versions where that API is unavailable, switch to each target level with `QualitySettings.SetQualityLevel(index)`, set `QualitySettings.renderPipeline = urpAsset`, then restore the original level and verify the saved `customRenderPipeline` values.
   - Confirm converted materials actually reference URP shaders.
   - Confirm representative materials that had source albedo textures now have non-null `_BaseMap` values. This check must compare against a pre-conversion material snapshot; do not use post-conversion `_MainTex` as the source of truth.
   - Confirm particle/VFX materials no longer reference Built-in particle shader IDs or legacy shader names; use URP particle shaders such as `Universal Render Pipeline/Particles/Unlit` where appropriate. If material names or paths include `Particle`, `Fog`, `Smoke`, `Steam`, `VFX`, `Additive`, or similar effect terms, preserve transparent/additive behavior rather than defaulting them to URP Lit.
   - Confirm vegetation materials preserve cutout/alpha clipping, render face intent, textures, tint, normals, and expected wind/billboard behavior. If grass/tree cards become solid or static because their specialized shader behavior was lost, material conversion is partial.
   - If PPv2 conversion was attempted, confirm saved URP Volume profiles contain persistent non-null `components` entries and the scene/camera wiring uses URP-compatible components.
   - If baked lighting exists, preserve the old Lighting Data and lightmaps as reference data, then verify whether they still produce acceptable URP visuals. If a new Lighting Settings asset is created, verify the saved scene actually references it after saving/reloading; the asset existing on disk is not enough. In an actual generic migration, attempt rebaking/refreshing when stale baked data or reflection probes affect parity; if that cannot finish in the current turn, report the migration as partial and resume from the lighting/probe phase later.
   - Do not claim "refreshed reflection probes" from intent. Verify new or updated probe outputs, changed saved reflection-probe assets, or successful probe-render tool output. If the existing EXR files remain unchanged, say probes were preserved as reference or still need refresh.
   - If any verification fails, report the item as incomplete/manual follow-up, not as migrated.

## 7. Shader and Material Triage

When materials are magenta, shaders fail to compile, or visuals drift heavily, use [references/custom-shader-triage.md](references/custom-shader-triage.md) first.

1. **Identify affected materials and shaders.**
   - Inspect the exact material shader assignments, not just scene symptoms.
2. **Read Console and Inspector errors before editing shader code.**
3. **Classify the shader case:**
   - supported Built-in shaders that the converter should handle
   - simple custom shaders that might be ported safely
   - complex custom shaders that need a scoped migration plan
   - foliage/vegetation shaders that require cutout, two-sided leaves, billboards, terrain detail rendering, or wind behavior
   - package-owned or Asset Store shaders that may require maintainer documentation, scoped custom porting, or manual follow-up
4. **For complex shader situations,** use [references/complex-shader-situations.md](references/complex-shader-situations.md).
5. **Prefer the smallest safe fix.**
   - Restore rendering on representative materials first.
   - Validate the result before scaling the fix to more assets.
6. **Never bulk search-and-replace shader code across the whole project** unless the mapping is explicit, tested, and scoped.

## 8. Post-Processing, Cameras, and Rendering-Effect Triage

Built-in projects often rely on more than material conversion.

1. **If PPv2 is present,** inspect the converter output and validate the resulting URP volumes, profiles, and camera behavior.
   - Inventory existing `PostProcessVolume`, `PostProcessLayer`, and PPv2 `PostProcessProfile` assets before conversion.
   - Prefer the URP `Post-processing Stack v2 Converter` when available instead of hand-building equivalent profiles from memory.
   - After conversion, verify that saved URP `VolumeProfile` assets contain persistent override components, not an empty `components: []` profile or dangling `{fileID: 0}` component references.
   - If creating a profile by script, `VolumeProfile.Add<T>()` only creates a component object; for persistent profile assets, also call `AssetDatabase.AddObjectToAsset(component, profile)`, mark the profile and component dirty, save assets, reload the asset, and count saved non-null components before reporting success. If the saved profile has `{fileID: 0}` component entries, recreate or repair the profile before claiming migration success.
   - Verify representative scenes contain the intended `Volume` objects and that target cameras have `UniversalAdditionalCameraData` with post-processing enabled when required.
   - If the source scene still only serializes a PPv2 `sharedProfile` reference and no URP `Volume` references the new `VolumeProfile`, PPv2 migration is incomplete even if a URP profile asset exists on disk.
   - If an active URP `Volume` references an empty profile, treat that as incomplete scene wiring, not as active post-processing. Repair the profile or report PPv2 as partial.
   - Check whether old `PostProcessVolume` / `PostProcessLayer` components remain. If they remain, explain whether they are intentionally retained, harmless legacy leftovers, or unresolved migration work.
   - If old PPv2 components are retained only as reference while a URP Volume is active, disable the old PPv2 component/layer for URP visual validation to avoid double post-processing. Do not delete it until parity is accepted or the user approves cleanup.
   - Do not remove PPv2 packages, components, or profiles as a cleanup step until a verified URP replacement exists or the user accepts that those effects will be dropped/manual follow-up.
   - During an actual migration, do not leave common PPv2 parity as a vague manual task if the source profile is available. Create persistent URP overrides for common mappable effects such as Bloom, Color Adjustments/Tonemapping, Vignette, and Depth of Field, then verify the saved profile has non-null components.
   - It is acceptable to mark unsupported or non-equivalent effects as manual follow-up, such as PPv2 Screen Space Reflections or Ambient Occlusion that should become a renderer feature / SSAO setup instead of a direct Volume override.
   - If URP Volume overrides cannot be created reliably, document the PPv2 effects and their URP equivalents instead of claiming they were migrated.
2. **Do not treat transient tool success as post-processing success.**
   - A command log that says "Added Bloom" is not enough. Re-read the saved `VolumeProfile` asset or inspect the scene after saving/reloading.
   - If the saved profile is empty, say the PPv2 setup was documented or partially prepared, not migrated.
3. **If grep finds `OnRenderImage`,** treat it as a custom full-screen effect case.
   - In URP, custom full-screen effects should move toward `ScriptableRenderPass`, a Renderer Feature, or URP custom post-processing instead of staying on the Built-in image-effect path.
4. **If grep finds `RenderWithShader` or `SetReplacementShader`,** treat it as a replacement-shader case.
   - These effects often need a deliberate URP renderer-feature or custom-pass strategy.
5. **If an effect depends on scene color, depth, or normals,** verify the URP-compatible path rather than assuming the Built-in approach still applies.
6. **If custom cameras were stacking effects in Built-in,** validate camera output explicitly after migration instead of assuming parity.
7. **For advanced shader/effect troubleshooting questions, provide concrete replacement patterns.**
   - For `GrabPass`, mention `_CameraOpaqueTexture` / Scene Color, the required URP asset setting, and the limitation that transparent ordering can differ from Built-in.
   - For `OnRenderImage`, mention `ScriptableRendererFeature` plus `ScriptableRenderPass`. When showing a Unity 6-style template, use the reference pattern with a temporary `RTHandle` and `Blitter.BlitCameraTexture`.
   - Never recommend `Blitter.BlitCameraTexture(cmd, source, source, material, pass)` or other source-to-source blits as the main `OnRenderImage` replacement. If you are not going to show the safer temporary-target pattern, omit the code sample and explain the architecture instead.
   - For Surface Shaders, state that `#pragma surface` has no direct URP equivalent and choose Shader Graph or a URP HLSL vertex/fragment rewrite based on effect complexity.
   - Do not stop at "rewrite it"; give the user a practical first porting step and a validation target.

## 9. Quality, Lighting, and Visual Parity Review

Use [references/quality-settings-map.md](references/quality-settings-map.md) when the user mentions visual mismatch, shadows, performance, or quality settings.

1. **Review Graphics settings and each active Quality level.**
   - If a Quality level has no custom URP asset, state whether that level intentionally falls back to Graphics settings or still needs explicit assignment.
   - Do not claim all quality levels are migrated unless each relevant level has been inspected.
   - If using serialized project settings, the saved field is commonly `customRenderPipeline`; writing a guessed field such as `renderPipelineAsset` is not enough unless the saved asset proves the assignment.
   - If assigning through script, use the same pattern as URP's Render Settings converter: cache `QualitySettings.GetQualityLevel()`, call `QualitySettings.SetQualityLevel(index)` for each target level, assign `QualitySettings.renderPipeline = urpAsset`, then restore the original quality level and verify on disk.
2. **Check URP asset settings** that commonly affect parity:
   - shadows
   - shadow distance and cascades
   - MSAA
   - render scale
   - HDR, opaque texture, and depth texture settings when effects depend on them
3. **Do not promise identical lighting automatically.**
   - Built-in and URP can differ in light falloff, baked GI appearance, shadow tuning, reflection probe response, tonemapping, exposure, and post-processing behavior.
4. **For baked lighting scenes,** treat existing lightmaps and Lighting Data as reference material, not guaranteed-final URP output.
   - Inventory `Lightmapping.lightingSettings`, scene `LightmapSettings`, baked/mixed lights, light probes, reflection probes, and any existing `LightingDataAsset`.
   - Preserve baked data until the user has a visual reference or rollback point, but do not keep stale Built-in lightmaps active as the final URP lighting solution if they blow out or distort the scene.
   - If the scene looks blown out, too dark, or mismatched, first isolate post-processing/exposure by disabling legacy PPv2 during URP validation, then review URP Volume exposure/tonemapping/bloom before changing lights.
   - If clearing baked data makes the scene stop being blown out, identify the old lightmaps/Lighting Data as stale or incompatible active data. Then rebake under URP with the final URP asset, renderer, Volume, and Quality settings instead of tuning lights against the stale bake.
   - If creating or assigning URP-compatible `LightingSettings`, mark the lighting settings and active scene dirty, save the scene, reload or re-query, and verify the saved scene references the intended `.lighting` asset. `AssetDatabase.SaveAssets()` alone does not save the scene's `Lightmapping.lightingSettings` reference. Do not report "Baked GI enabled" if the saved scene still points at an Enlighten/realtime-GI settings asset.
   - When visual parity is part of the request and old `LightingData.asset` / reflection-probe EXRs remain from the Built-in bake, treat them as reference data until rebaked/refreshed under URP. Do not claim visual parity is preserved from old bake data alone.
   - Recommend clearing/rebaking lighting and refreshing reflection probes when visual parity matters. Do not claim baked lighting was successfully migrated unless a representative scene has been visually checked after URP setup, and preferably after a URP bake.
5. **For 2D lighting projects,** ensure sprites and tilemaps use URP-compatible lit materials where required.
6. **For performance regressions,** inspect whether the issue is coming from:
   - heavier URP asset settings
   - post-processing
   - extra shadow cost
   - custom shader ports or non-batched shaders
7. **When changing URP asset settings,** re-read the saved asset or query the property after saving before reporting values such as MSAA, additional-light limits, HDR, depth texture, or opaque texture.

## 10. Validation

After setup, conversion, or troubleshooting, validate the result:

1. **Capture the scene:** Capture the Scene View or a specific camera on a representative scene — see [references/capturing-the-editor.md](references/capturing-the-editor.md).
2. **Evaluate the result:**
   - no magenta materials unless unresolved custom shader blockers remain
   - main lighting and shadows behave as expected
   - baked GI/lightmaps, light probes, and reflection probes are acceptable or explicitly marked for rebake/refresh
   - cameras render expected content
   - post-processing or fullscreen effects still behave correctly
   - sprites, tilemaps, or 2D lights work when relevant
3. **Verify persistent project data, not only visual output.**
   - Inspect saved URP assets, renderer assets, scene references, material shader GUIDs/names, Quality settings, and Volume profiles.
   - Confirm the representative scene, not a default/test scene, was opened or otherwise inspected before concluding that baked lighting, PPv2, or reflection probes are absent.
   - For material migration, include particle/VFX materials in the verification. Remaining built-in particle shader IDs or legacy particle shader names mean material migration is incomplete.
   - For PPv2 migrations, saved URP `VolumeProfile` assets must contain the expected override components before reporting them as migrated.
   - If a tool log reports mapped post-processing but the saved profile reloads with `components: []`, override the tool log and report the migration as failed/incomplete.
   - For baked-lighting scenes, inspect Lighting Settings, Lighting Data/lightmap references, light probes, and reflection probes. Compilation success does not prove baked lighting parity. If old lightmaps cause overexposure, clear active baked data and rebake under URP before judging parity. After assigning new lighting settings, verify the saved scene reference, not only the existence of the new `.lighting` asset.
   - If old `LightingData.asset` remains assigned and reflection-probe EXRs were not regenerated or explicitly accepted after visual inspection, classify lighting/probes as preserved or partial rather than refreshed.
4. **Check Console output** with `Unity.GetConsoleLogs` for shader, render pipeline, or renderer-feature errors.
5. **Fix the highest-impact issue first,** then validate again.
6. **Repeat for at most 3 iterations** before reporting remaining blockers or asking the user how they want to proceed.

## 11. Troubleshooting Decision Tree

If the user reports a migration problem, follow this diagnostic flow:

### Project still behaves like Built-in after "migration"
1. Check whether a URP asset is assigned in Graphics settings.
2. Check whether the relevant Quality levels also point to a URP asset.
3. Verify that the active render pipeline is actually URP before troubleshooting anything else.

### Migration stopped after installing URP
1. Treat this as a package-refresh/domain-reload boundary, not a failed full migration by itself.
2. Re-check `Packages/manifest.json` and package state. If URP is installed, do not reinstall it.
3. Inspect for partial assets such as URP assets, renderer assets, converted materials, empty Volume profiles, and scene component changes.
4. If URP is installed/assigned but Built-in materials still dominate or the scene is magenta, material conversion is the immediate next incomplete item. Do not call URP setup complete and stop there if rollback safety has already been confirmed.
5. Continue from the first incomplete verification item: Graphics/Quality assignment, renderer asset validity, material conversion, PPv2-to-URP Volume migration, baked-lighting rebake, then final validation.
6. If the previous chat/export has no final response, report it as incomplete evidence and continue in a fresh chat/turn.

### Materials are magenta / bright pink
1. Check Console and Inspector for shader errors.
2. Confirm whether the material uses a supported Built-in shader, a custom shader, or a package-owned shader.
3. If it is a supported Built-in shader, review the converter path or targeted material conversion first.
4. If the project is already on URP and many supported Built-in materials remain, treat this as incomplete material conversion, not as final visual parity work.
5. If it is a custom or package shader, move into [references/custom-shader-triage.md](references/custom-shader-triage.md) and, when needed, [references/complex-shader-situations.md](references/complex-shader-situations.md).

### Scene is much darker, brighter, or just "wrong"
1. Compare Scene View and Game View captures.
2. Check for double post-processing first: retained PPv2 `PostProcessVolume` / `PostProcessLayer` plus an active URP `Volume` can overexpose or otherwise distort validation captures.
3. Review shadows, ambient/environment lighting, tone mapping, skybox, exposure, bloom, and post-processing.
4. Inspect baked lighting state: Lighting Settings, Lighting Data asset, lightmap references, mixed/baked lights, light probes, and reflection probes.
5. Review quality-level assignments and URP asset settings before rewriting content.
6. If clearing baked data fixes severe overexposure, treat the old lightmaps as stale active data: keep them only as reference/rollback evidence, then rebake under URP.
7. If the scene depends on baked lighting, recommend a URP rebake and reflection-probe refresh before claiming visual parity.
8. Remember that Built-in and URP light falloff can differ; treat that as a tuning task, not proof that conversion failed.

### Post-processing or fullscreen effects disappeared
1. Check whether PPv2 was converted and whether the target camera and volume setup are still valid.
2. Inspect saved URP `VolumeProfile` assets. Empty profiles mean PPv2 effects were not actually migrated.
3. Check whether old `PostProcessVolume` / `PostProcessLayer` components remain active in scenes.
4. Search for `OnRenderImage`, custom blit code, or replacement-shader camera effects.
5. Port the effect using a URP-compatible approach rather than trying to preserve the Built-in callback path unchanged.

### Transparent / refraction / distortion effects broke
1. Inspect whether the shader relied on `GrabPass` or a similar Built-in screen-copy workflow.
2. If so, use [references/complex-shader-situations.md](references/complex-shader-situations.md) and choose a Scene Color / Renderer Feature / custom-pass approach.

### 2D lights are not affecting sprites
1. Confirm the project is actually using the 2D Renderer.
2. Confirm existing sprite materials were upgraded to URP-compatible lit materials where needed.
3. Do not assume dragged-in new sprites prove old project materials are correct.

### Performance regressed after migration
1. Review render scale, shadows, additional lights, MSAA, post-processing, opaque/depth textures, and other URP asset settings.
2. Check whether custom shader ports lost batching compatibility or introduced extra passes.
3. Tune settings before assuming the only answer is a rollback.

### Custom shader compiles but visuals are still wrong
1. Determine whether the issue is simple parameter drift or a structural incompatibility.
2. If the shader came from a surface shader, `GrabPass`, replacement-shader workflow, or custom lighting path, treat it as a complex migration case.
3. Validate one representative material before rolling the approach out project-wide.

## 12. Core Guardrails

- Detect the active render pipeline first; for HDRP, explain the mismatch and offer only basic comparison guidance.
- Do not mutate the project before rollback safety is confirmed; instead stop in planning mode before URP install, asset assignment, converters, material edits, or scene edits.
- Do not treat tool logs or created assets as proof; instead save/reload/re-query Graphics, Quality, materials, Volumes, lighting, probes, Console, and representative scenes before status claims.
- Do not collapse partial phases into project-level completion; instead report `Phase complete`, `Partial migration`, and `Manual follow-up` based on the success gate.
- Do not bulk-rewrite fragile rendering code; instead use scoped mappings for custom shaders, `GrabPass`, `OnRenderImage`, replacement shaders, package-owned render code, and unsupported PPv2 effects.

## 13. Reporting Back

Summarize:

- which migration path was used
- whether the project is still Built-in, partially migrated, or fully on URP
- which converters ran
- what was fixed automatically
- what still needs manual work
- which scenes, materials, or cameras were validated
- what remains risky, especially around complex shaders, package effects, and visual parity
- whether post-processing was fully migrated, partially prepared, or only documented for manual follow-up
- whether Quality levels are explicitly assigned or intentionally relying on Graphics settings fallback
- whether particle/VFX materials were converted or still need URP particle-shader follow-up
- whether baked lighting/lightmaps/reflection probes were preserved as reference, verified visually, rebaked/refreshed, or left as manual follow-up
- whether exposure, tonemapping, ambient fill, and camera/Volume post-processing wiring were visually balanced or still remain partial

Use completion language conservatively. If the report contains any `Partial`, `Manual follow-up`, `not validated`, `may still need`, or unsupported-feature item, state that specific completed phases passed and call the overall migration partial/manual. Do not pair a project-level "complete" claim with manual follow-up bullets.

## References

- [Migration Workflow](references/migration-workflow.md)
- [Custom Shader Triage](references/custom-shader-triage.md)
- [Complex Shader Situations](references/complex-shader-situations.md)
- [Quality Settings Map](references/quality-settings-map.md)
- [Implementation Patterns](references/implementation-patterns.md)

When this skill is activated, proactively read [references/migration-workflow.md](references/migration-workflow.md). If the request involves materials, shaders, magenta materials, custom rendering, or fullscreen effects, also read [references/custom-shader-triage.md](references/custom-shader-triage.md) and [references/complex-shader-situations.md](references/complex-shader-situations.md). If the request involves visual mismatch, lighting, baked lighting, lightmaps, reflection probes, shadows, or performance after migration, also read [references/quality-settings-map.md](references/quality-settings-map.md). If the user permits actual migration changes or asks to continue/repair a partial migration, also read [references/implementation-patterns.md](references/implementation-patterns.md).

Referenced files: 6

View saved version →

---
name: new-unity-project
description: Use when starting a brand-new Unity game or project from scratch — "make/start/create a new game", "bootstrap a Unity project", "I want to build a [genre] game", "scaffold/prototype a game", game jam, greenfield, blank project, project setup. A guided flow that gathers the concept, target platforms, and monetization, installs the Editor in the background while it asks, then creates the project and source control and installs packages — delegating the mechanics to the unity-cli and unity-package-management skills and handing off monetization to the dedicated skills. Does not scaffold gameplay code.
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.
- **`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 matching template; init git.
5. **Packages** — install via the C# Client API.
6. **Save & first commit.**
7. **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) and packages (Step 5).

## 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 7 — 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 as a background task** so it runs while
you continue. See the `unity-cli` skill for exact syntax, module names per platform, and auth /
license setup:

```bash
unity --version
unity auth status --format json      # if signed out:  unity auth login
unity license status --format json   # if none active: unity license activate

# Start in the BACKGROUND, then go straight back to the conversation. Module names per platform
# (android / ios / webgl / …) are in the unity-cli skill.
unity install lts --module <platform-modules> --yes --accept-eula
```

Run that install as a **background task** (don't block on it). If you have nothing left to ask,
it's fine to just wait — the parallelism only helps when there's a conversation to overlap.

## Step 3 — Join: Editor ready

Before creating the project, confirm the background install finished:

```bash
unity editors --installed --format json
```

If it failed, surface the error (see `unity-cli` troubleshooting) and stop — nothing downstream
works without an Editor.

## Step 4 — Create the project + source control

Follow the **`unity-cli`** "Bootstrap a new project from scratch" workflow verbatim:

- List the **real** template ids the Editor offers (`unity templates list`) and pick one matching
  2D/3D and render pipeline from the brief — don't guess ids.
- Create with `unity projects create "<Name>" --path <dir> --editor-version <v> --template <id>`.
- Set up source control — **ask the user which they want**, don't assume: Git (GitHub / GitLab;
  add `--git-lfs` for asset-heavy games) or **Unity Version Control** (`--vcs uvcs`, which handles
  large binary assets natively — no LFS), or a purely local `git init` + Unity `.gitignore`.
  Publish in one step with `unity projects create --vcs … --git-token-stdin --no-initial-commit`
  (tokens on stdin). Pass **`--no-initial-commit`** so the CLI doesn't commit the bare project
  before packages and `.meta` files exist — you make the real first commit/check-in in Step 6.
  See the `unity-cli` workflow for exact flags.

## Step 5 — Packages

Map the brief to a concrete package list and install it via the **`unity-package-management`**
skill (C# PackageManager Client API — **never** hand-edit `manifest.json`). Read that skill for
the genre/platform/monetization → package mapping, the installer script, and the `-quit` gotcha.
Read the final list back to the user before installing; verify `manifest.json` afterward.

## Step 6 — Save & first commit

Open the project once so Unity imports the assets and generates every `.meta` file, then make
the first commit **with whichever VCS you set up in Step 4**:

```bash
unity open "<project-path>"     # imports + generates .meta; for headless/CI use the
                                # "Import & save headlessly" method in unity-package-management
```

- **Git (GitHub / GitLab / local):**
  ```bash
  cd "<project-path>"
  git add -A
  git status                    # Library/ Temp/ obj/ Build/ must NOT be staged
  git commit -m "Initial Unity project: <Name>"
  ```
  Every `.cs`/asset must be committed together with its `.meta`.
- **Unity Version Control (UVCS):** check in through your UVCS client/workspace (created during
  Step 4) — there's no `git` step. Generated folders are still excluded by the ignore rules.

If you published via `--vcs` in Step 4 **without** `--no-initial-commit`, the CLI already made an
initial commit of the bare project — add a follow-up commit here rather than double-committing.

## Step 7 — Hand off

Based on Step 2 monetization, invoke the matching skill for the actual integration:
- IAP → **implement-in-app-purchases**
- Ads → **levelplay-unity-integration**
- Accounts / cloud save / economy / remote config / leaderboards → **build-live-game**

Report the project path, Editor version, installed packages, and next steps.

## Scope — what this skill does NOT do

- **No gameplay scaffolding.** It gets you to a running, empty-but-wired project; building the
  actual game (scenes, controllers, art) is the next conversation — iterate there with the Editor
  via the `unity-cli` MCP server and the Package Manager. Generic genre skeletons tend to produce
  throwaway mocked primitives, so this skill intentionally stops at a clean starting point.
- **No command reference.** Syntax lives in `unity-cli` / `unity-package-management`.

## Checklist

- [ ] Concept brief captured and confirmed (genre, look, gameplay, scope, name)
- [ ] Platforms + monetization recorded; Editor version chosen
- [ ] Editor + platform modules installed (started in the background during Step 2)
- [ ] Project created from a matching template; git initialized with a Unity `.gitignore`
- [ ] Packages installed via the C# Client API; `manifest.json` verified
- [ ] Project opened/saved so `.meta` files exist; first commit made; `Library/` excluded
- [ ] Handed off to the monetization/backend skill if applicable

## Common mistakes

- **Blocking on the Editor install** instead of backgrounding it while you ask questions.
- **Installing the wrong Editor** because the version wasn't confirmed before the background install.
- **Gathering all questions up front** — platform/monetization answers change the modules and packages.
- **Hand-editing `manifest.json`** instead of using the Client API (see `unity-package-management`).
- **Committing `Library/`/`Temp/`/`obj/`/`Build/`**, or scripts without their `.meta` files.
- **Missing Editor modules** — a mobile target needs `android`/`ios`; WebGL needs `webgl`.

View saved version →

---
name: optimize-audio
description: Optimizes Unity 6 audio memory, CPU cost, and playback quality through correct import settings and mixer configuration. Use when the user wants to reduce audio memory usage, choose the right Load Type for short clips versus music versus ambient beds, configure platform-appropriate sample rates and codecs, force 3D audio to mono, or reduce AudioMixer CPU cost from deep group trees or effects running on silent paths.
---
## 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 buffer size:** Use the DSP buffer recipe in [resources/audio-import-api.md](resources/audio-import-api.md) to read buffer size. See DSP Buffer Size Guidelines in [resources/platform-settings.md](resources/platform-settings.md) for recommended values.
4. **Report findings before making changes:** Summarize ALL detected sources, the listener count, and mixer depth to the user. Flag any immediate risks (e.g., stereo clip with `spatialBlend = 1`, Decompress On Load on a clip > 1 MB, reverb on the Master group).

**WAIT for the user to review the assessment before proceeding.**

## 3. Understand Request

Route to the correct section based on what the user needs:

| User Says | Path |
|-----------|------|
| "audio memory too high" / "memory profiler shows audio" | Section 4 — Import settings audit |
| "load times slow" / "decompression stall" | Section 4 — Load Type review |
| "DSP spike" / "mixer CPU" / "audio CPU high" | Section 4B — Mixer audit |
| "3D sound wrong" / "only left channel plays" / "stereo in 3D" | Section 4A — Force To Mono + spatial settings |
| "quality artifacts" / "voice sounds bad" / "Vorbis crackling" | Section 4C — Compression quality tuning |
| "mobile audio battery" / "mobile memory" | Section 4D — Mobile sample rate override |
| "set import settings on all clips" / "batch audio settings" | Section 4 — Bulk import audit |
| "streaming" / "background loading" / "Addressables audio" | Section 4E — Streaming and async load |

If the symptom is ambiguous, ask: "Is the problem audio memory usage, DSP CPU spikes, or audio playback quality?"

## 4. Primary Diagnostic Workflow

Use the findings from Section 2 to determine which sub-section applies. More than one may apply simultaneously.

### 4A. Force To Mono and Spatial Settings

For any AudioSource where `spatialBlend > 0` (3D positioned sound):

1. **Check clip channel count:** Use `eval` to read `audioSource.clip.channels`. If `channels == 2` and `spatialBlend == 1`, only the left channel plays — this is a bug, not a feature.
2. **Recommend Force To Mono:** Use the read importer recipe in [resources/audio-import-api.md](resources/audio-import-api.md) to inspect current settings, then apply Force To Mono using the force-to-mono recipe.
3. **Apply and reimport:** Report before/after channel counts to the user.
4. **Verify spatial blend:** Use `eval` to confirm `audioSource.spatialBlend` is `1.0` (full 3D) and `audioSource.rolloffMode` is set to an appropriate curve.

### 4B. AudioMixer Audit

1. **Measure group depth:** Use `eval` to walk the mixer's group tree and count levels. More than 3 levels (Master → SFX / Music / Voice → sub-bus) adds routing overhead every frame, even when children are silent.
2. **Check effects on silent groups:** Use `eval` to query each group's effects list. Effects such as `AudioReverbFilter` run their DSP at full cost even when no AudioSource routes to that group.
3. **Flag SFX Reverb on parent groups:** This is the most expensive built-in effect. If found on the Master or a high-level group, flag it explicitly.
4. **Present recommendations to the user:**
   - Remove or bypass effects on groups that have no active sources.
   - Use **snapshots** to switch mix states (combat / explore / pause) rather than toggling effects at runtime.
   - Flatten unnecessary sub-buses; redirect sources to a shallower ancestor.

   **WAIT for the user to approve the mixer changes before applying.**

5. **Verify DSP buffer size:** If `bufferLength` from Pre-Flight is very small (< 256), recommend increasing it — see DSP Buffer Size Guidelines in [resources/platform-settings.md](resources/platform-settings.md).

### 4C. Compression Quality Tuning

1. **Read current compression format:** Use the read importer recipe in [resources/audio-import-api.md](resources/audio-import-api.md) to read `compressionFormat` and `quality` for the clips reported by the user.
2. **Apply the platform matrix:** See the Compression Format Matrix in [resources/platform-settings.md](resources/platform-settings.md) for per-platform recommendations.
3. **Warn about lossy sources:** Use the lossy source check recipe in [resources/audio-import-api.md](resources/audio-import-api.md). If the original file is MP3, warn the user that lossy source quality is lost permanently after Unity re-encodes. Recommend WAV or AIFF sources.

### 4D. Mobile Sample Rate Override

1. **Identify SFX clips on mobile target:** Use the scene-component query recipe for `UnityEngine.AudioSource` and filter for non-music, non-dialogue clips.
2. **Read current sample rate setting:** Use the read importer recipe in [resources/audio-import-api.md](resources/audio-import-api.md) to read `sampleRateSetting` and `sampleRateOverride` for each clip.
3. **Apply mobile override:** Use the sample rate override recipe in [resources/audio-import-api.md](resources/audio-import-api.md). See Sample Rate Recommendations in [resources/platform-settings.md](resources/platform-settings.md) for per-use-case rates.
4. **Report savings:** Halving the sample rate halves the PCM memory cost. Report the estimated saving for each clip changed.

### 4E. Load Type and Streaming

1. **Audit Load Type per clip:** Use `eval` to read `clip.loadType` for each clip found in Section 2.
2. **Apply the decision rule:** See Load Type Decision Table in [resources/platform-settings.md](resources/platform-settings.md).
3. **Flag mismatches:** See Load Type Mismatch Flags in [resources/platform-settings.md](resources/platform-settings.md). Report both types of mismatches to the user.
4. **Apply `Load In Background`** for any Streaming clip — use the Load In Background recipe in [resources/audio-import-api.md](resources/audio-import-api.md).

## 5. Validation

After any import setting or mixer change:

1. **Re-read clip stats:** Use `eval` to re-read `clip.loadType`, `clip.channels`, `AudioSettings.outputSampleRate`, and the importer's `compressionFormat` to confirm the change applied after reimport.
2. **Confirm AudioSource routing:** Use the scene-component query recipe for `UnityEngine.AudioSource` and verify `audioSource.outputAudioMixerGroup` is assigned as expected after any mixer restructure.
3. **Report delta:** State the before and after values for each setting changed. Do not assume the change was effective without reading back the applied importer values.
4. **Iterate limit:** Maximum 3 adjust-and-verify cycles before pausing to ask the user for feedback.

## 6. Troubleshooting

### Stereo clip on a 3D AudioSource — only left channel audible

1. Confirm `audioSource.spatialBlend == 1`.
2. Confirm `audioSource.clip.channels == 2`.
3. Enable `forceToMono` in the AudioClip importer and reimport. Unity mixes both channels to mono during import, preserving level with `normalize = true` (keep on).
4. If the user does not want to reimport: set `audioSource.panStereo = 0` as a runtime workaround, but warn this does not recover stereo information.

### Decompress On Load clip causes memory spike

1. Confirm `clip.loadType == AudioClipLoadType.DecompressOnLoad` and `clip.length` is long (> 5 s).
2. Switch to `Streaming` if it is music or ambience, `CompressedInMemory` if played only occasionally.
3. If the clip is short but still large: check `clip.channels` (stereo wastes double the memory) and `clip.frequency` (high sample rate on a mobile target wastes memory). Apply Force To Mono and/or sample rate override.

### AudioMixer CPU spike — DSP thread hot

1. Confirm with the mixer-asset query recipe that the mixer graph exists.
2. Use `eval` to list all groups and their attached effects. Look for reverb, chorus, or EQ on high-level groups.
3. Move expensive effects down to leaf groups that are only active when sources are playing.
4. Use snapshots to bypass effect chains during gameplay states where they are not heard (e.g., bypass reverb during a menu).
5. If the DSP buffer is small (64 or 128 samples), raise it — see DSP Buffer Size Guidelines in [resources/platform-settings.md](resources/platform-settings.md).

### Vorbis quality artifacts on dialogue

1. Confirm `defaultSampleSettings.compressionFormat == AudioCompressionFormat.Vorbis`.
2. Confirm `defaultSampleSettings.quality` — default is 0.5, which is often audible on voice. Raise to 0.7–0.85.
3. On iOS: switch to AAC instead of Vorbis (hardware decode, better quality at equivalent bitrate).
4. Confirm the source file is lossless (WAV or AIFF). MP3 sources cannot recover quality lost before Unity's re-encode.

### AudioListener count is not exactly one

- **Zero listeners:** All audio will be silent. Use `eval` to add an `AudioListener` component to the main camera: `UnityEngine.Camera.main.gameObject.AddComponent<UnityEngine.AudioListener>()`.
- **Multiple listeners:** Unity uses the last enabled one, producing unpredictable spatialization. Use the scene-component query recipe for `UnityEngine.AudioListener` and disable all but the intended one.

### `Load In Background` causes first-play silence

This is expected behavior: the clip has not finished loading when `Play()` is first called. Mitigate with:
1. Preload the clip at scene start by calling `clip.LoadAudioData()` before it is needed.
2. Use `AudioSource.PlayScheduled()` with a slight delay to allow async load to complete.
3. For AudioSources that must play immediately: switch to `CompressedInMemory` (synchronous on first play) rather than `Streaming` with background load.

## 7. Completion

After finishing the audit or optimization:

- Summarize every setting changed with before/after values.
- List any clips or groups that still need attention (e.g., clips that require on-device measurement to confirm savings).
- If the user needs runtime memory measurement, point them at the Memory Profiler package, which reports the largest AudioClips by runtime byte cost.
- If mixer CPU is still high after the audit, point them at the Unity Profiler's Audio module for DSP thread profiling.

## Detailed References

- **Platform settings, compression matrix, load types, sample rates:** [resources/platform-settings.md](resources/platform-settings.md)
- **AudioImporter API recipes and code patterns:** [resources/audio-import-api.md](resources/audio-import-api.md)

## See Also

- **Memory Profiler package** — finds the largest AudioClips by runtime byte cost.
- **Unity Profiler, Audio module** — DSP CPU markers and frame-time budget.
- `audio-setup-mixers` — creating mixers and routing Audio Sources into groups.

Referenced files: 2

View saved version →

---
name: optimize-text-mesh-pro
description: >
  Covers TextMeshPro font stacks, dynamic fallback atlases, padding and
  sampling ratios, SDF16, AutoSize discipline, worldspace vs UGUI, and Memory
  Profiler font-data capture. Use when the user mentions TextMeshPro,
  Text Mesh Pro, TMP (TextMeshPro), font asset, dynamic atlas, TMP localization,
  CJK (Chinese, Japanese, Korean) fonts, font alignment across
  scripts, mixed western and eastern fonts, text rendering performance, profiler
  markers related to text generation or glyph rasterization, font fallback
  strategy, font normalization, multilingual or localized text rendering, SDF
  font quality, or text-related memory issues—not for UI Toolkit layout
  (unity-ui-toolkit) or non-TMP uGUI (unity-ui).
---

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

If the user reports point sizes not matching design specs, check the font asset Scale value. Some imported TMP font assets ship with `Scale = 0.9` instead of `1.0`. The Scale value participates in the point-size-to-pixels math, so a non-1 scale produces non-standard point sizes. Advise the user to **set Scale = 1 on all font assets before adjusting padding ratios**.

---

## Sprite Assets

If the user reports slow loading times for TMP Sprite Assets on mobile, check the source texture's Texture Type. It must be set to **Default** (not Sprite). Sprite type creates child sub-objects that TMP doesn't use; Default avoids them.

---

## AutoSize

If the user reports CPU spikes on text fields that change frequently (timers, counters, chat, dynamic player names), check whether `enableAutoSizing` is on. AutoSize resizes the text whenever the string changes, causing constant CPU spikes.

Advise: **disable AutoSize and hard-code the chosen point size** once layout is locked. Keep AutoSize on only for genuinely static labels that auto-fit on locale change.

---

## Atlas Render Mode: SDF16

If a static font with point size **72 or larger** looks unclear or has fuzzy edges, advise switching the **Atlas Render Mode** to **SDF16**. Higher precision SDF for big glyphs, at slightly more atlas memory.

---

## Font Normalization

If the user reports misaligned Latin + CJK text on the same line, walk them through this procedure:

1. **Window -> TextMeshPro -> Settings -> Import TMP Example & Extras** (one-time per project).
2. Add the **`TMP_TextInfoDebugTool`** component to the TextMeshPro object displaying misaligned text.
3. Enable **ShowLines** toggle - the ascender, descender, and baseline render as overlays.
4. Mix Latin + CJK strings; if the lines diverge, **adjust ascender/descender on the TMP Font Asset** until they align.

> **Caveat**: importing TMP Examples & Extras has been observed to cause an infinite import loop on some project layouts. If it happens, close Unity and re-open - the import resolves on the second attempt.

---

## Material Presets

If the user needs multiple styles (italic, bold, outline, glow) of the same font, advise material presets instead of duplicating font assets. Presets share the same font texture but override shader parameters.

How to create:

1. Select a TMP Text GameObject.
2. In Inspector, find the **Material** section.
3. **Right-click the Material header -> Create Material Preset.**
4. Rename the new material and tweak settings.
5. On the TMP Text component, pick the preset from the **Material Preset dropdown**.

---

## Dynamic OS Atlas Population (TMP 3.2.0-pre.3)

If the user is shipping multilingual builds and concerned about build size, advise evaluating **`Atlas Population Mode = Dynamic OS`** (TMP 3.2.0-pre.3+):

- In Editor: still uses the source font from the project.
- In a player build: **the source font is not included**. At runtime, Unity searches the device for a font with the matching Family + Style name.

Recommended system fonts for CJK:

| Platform | Recommended system font |
|---|---|
| **Android** | NotoSans (covers Chinese, Japanese, Korean glyphs broadly). |
| **iOS** | PingFang for Simplified/Traditional Chinese. iOS uses **unique fonts per language** for CJK (different families for Chinese, Japanese, Korean) - check the fallback chain when shipping a single TMP setup across all three. |

Wins: build size shrinks (no shipped CJK font files) and memory drops (system font is shared with the OS).

---

## Memory Profiler: Include Font Data

If Memory Profiler shows unexpectedly large font asset sizes in the Editor, check whether **Include Font Data** is enabled on the `.ttf` / `.ttc` import settings. The Editor includes the source font file in the asset by default, but on device (especially with Dynamic OS), this cost is not paid.

To make Editor captures match device: on the font file -> deselect **Include Font Data** in the import settings. Memory Profiler will then show overhead **without** the underlying font file.

---

## Worldspace vs Canvas Text

If the user has worldspace text (damage numbers, signs, holograms) using `TextMeshProUGUI`, advise switching to **`TextMeshPro`**. Worldspace Canvas is a known inefficiency.

If a `TextMeshProUGUI` element's `text` changes often (timers, counters, chat), advise **parenting it under a child GameObject with its own Canvas component**. Canvas rebuilds are scoped per-Canvas, so isolating the volatile field cuts rebuild cost on the rest of the UI.

---

## Common Pitfalls

If the user's setup matches any of these, flag it:

- One giant dynamic font asset for all languages instead of static main + dynamic fallback - the dynamic atlas balloons.
- Inconsistent padding ratio across primary + fallback - same line of text looks like two fonts.
- Font asset Scale = 0.9 inherited from import - point sizes won't match design specs.
- Leaving AutoSize on for live counters - hidden CPU spikes.
- World-space `TextMeshProUGUI` inside a worldspace Canvas - extra rebuilds for no benefit; use `TextMeshPro`.
- Forgetting **Clear Dynamic Data On Build** on dynamic fallback fonts - editor-test glyphs ship in the player.
- Capturing Memory Profiler in Editor with Include Font Data on, then being surprised the on-device build is smaller.
- Sprite asset source texture set to Sprite type - mobile loading slows from extra child sub-objects.

---

## References

- TextMeshPro - Atlas Population Mode (Unity Manual): https://docs.unity3d.com/Packages/com.unity.textmeshpro@latest/manual/FontAssets.html

View saved version →

---
name: optimize-web
description: Optimizes Unity 6 WebGL and WebGPU builds for smaller download size, faster initial load, and efficient browser runtime performance. Use when the user's web build is too large, stutters in a specific browser, consumes excessive battery, needs CDN/server compression configured, or needs guidance on resource stripping, shader variant reduction, KTX textures, quality settings, 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.WebGL.optimizationLevel` |
| IL2CPP code generation | `PlayerSettings.GetIl2CppCodeGeneration(NamedBuildTarget.WebGL)` | a bare property |

`UserBuildSettings` lives in the WebGL build-support module, so it only resolves when that module is
installed. Read it in a separate call from the rest, and treat a resolution failure as "the Web
module isn't installed" rather than as a bad snippet.

**`codeOptimization` is the one setting here that does not live in the project file.** It persists to
`Library/EditorUserBuildSettings.asset`, and `Library/` is gitignored by every standard Unity
`.gitignore`, so this value is per-machine and does not travel: teammates and CI do not inherit it.
Two consequences. Read it back through the API and do not look for it in
`ProjectSettings/ProjectSettings.asset` — it is absent there even on a successful apply, so its
absence is not a failure. And if the release build runs in CI, apply it there as a build step rather
than assuming the repository carries it.

### Applying the settings

Most of the writes in this skill are a single batch, and
[resources/WebOptimizer.cs](resources/WebOptimizer.cs) already is that batch. It declares a class
with a `[MenuItem]`, so it is a **project file, not `eval` input** — a class declaration cannot be
flattened into a statement block. Save it under `Assets/Editor/`, let Unity compile, then invoke it
in one line:

```csharp
UnityEditor.EditorApplication.ExecuteMenuItem("Tools/Apply Web Release Settings");
```

Keep its `using` directives; they are correct in a file. For one-off changes — a single quality
level, a frame-rate flip — an inline `eval` statement is fine.

### Verify from disk, not from the objects you just wrote

**Applying a setting and reading it back in the same session proves nothing.** Player Settings are
in-memory objects until something saves them, so every read-back returns the value you just
assigned whether or not it ever reached
`ProjectSettings/ProjectSettings.asset`. A run that skips the save reports success, and when the
Editor session ends the whole change is gone. This was observed, not theorised: a run applied
everything, read back Brotli / High / None, said it was done, and the file on disk never changed.

So after any write:

1. **Save.** `UnityEditor.AssetDatabase.SaveAssets()`. `WebOptimizer.cs` now does this itself; an
   inline `eval` write has to do it explicitly.
2. **Read the values back and report them.** Not "applied successfully" but the actual values, so the
   user can see what is stored. `WebOptimizer.cs` logs all nine.
3. **For anything per-build-target, name the target you read.** Several of these settings exist once
   per target, so a value can be correct for one target and unset for the one being built.

The same trap exists on the file-editing route in reverse: a hand-edited
`ProjectSettings.asset` reads back fine while the running Editor and the build still use the old
value. Verifying after a save and a reimport is what catches both.

**Do not try to reproduce this in batch mode.** A batch Editor invoked with `-quit` saves settings on
exit, so an unsaved write persists anyway and the run looks correct. Both a saving and a non-saving
version of the script pass under `-quit`. The bug only appears in a live Editor session, which is
where it was found. Concluding from a green batch run that the save is unnecessary is the wrong
conclusion from a test that cannot see the defect.

## 0. Pre-Flight

1. **Confirm Web build target:** Read, with the Pre-Flight snippet above, `EditorUserBuildSettings.activeBuildTarget` — must be `WebGL`; if not, warn the user.
2. **Read compression and stripping settings:** Read `compressionFormat`, `decompressionFallback`, `stripEngineCode` and the managed stripping level with the Pre-Flight snippet above. Note the stripping level is `PlayerSettings.GetManagedStrippingLevel(NamedBuildTarget.WebGL)` — there is no `PlayerSettings.managedStrippingLevel` property.
3. **Read exception and optimization settings:** Read `PlayerSettings.WebGL.exceptionSupport` from the Pre-Flight snippet above. For the wasm code optimization level use `UnityEditor.WebGL.UserBuildSettings.codeOptimization` — the `PlayerSettings.WebGL.codeOptimization` and `optimizationLevel` spellings do not exist and will not compile.
4. **Read frame rate settings:** Read, with the Pre-Flight snippet above, `Application.targetFrameRate` and `QualitySettings.vSyncCount`.
5. **Read additional player settings:** Read, with the Pre-Flight snippet above, `PlayerSettings.WebGL.dataCaching`, `PlayerSettings.WebGL.debugSymbolMode`, `PlayerSettings.WebGL.maximumMemorySize`, and `PlayerSettings.GetApiCompatibilityLevel`.
6. Proceed only after compression, stripping, frame rate, and player settings are confirmed.

## 1. Assess Current State

1. **Check Build Report:** Instruct the user to open `Window > General > Build Report` after a build and identify the largest asset and code size contributors.
2. **Verify server configuration:** Ask the user to confirm whether the hosting server sends `Content-Encoding: br` (Brotli) or `Content-Encoding: gzip` headers, and whether `Content-Type: application/wasm` is set for `.wasm` files.
3. **Check frame rate config:** Confirm, with the Pre-Flight snippet above, `Application.targetFrameRate` — should be `-1` for Web (let the browser drive).
4. **Check memory settings:** Read, with the Pre-Flight snippet above, `PlayerSettings.WebGL.initialMemorySize` and `PlayerSettings.WebGL.memoryGrowthMode`.
5. Report findings before making recommendations.

## 2. Understand Request

| User Says | Default Interpretation |
|-----------|----------------------|
| "build too large" / "download too slow" | Strip Engine Code on; Managed Stripping High; Disk Size + LTO; Brotli |
| "Decompression Fallback" / "slow startup" | Decompression Fallback off; fix server to send Content-Encoding |
| "stutter in Chrome" / "stutter in Safari" | Profile in browser DevTools; Safari caps at 60 fps |
| "excessive battery in browser" | `OnDemandRendering` on static screens; `targetFrameRate = -1` |
| "exceptions too large" | None for release; Wasm 2023 exceptions if browser baseline allows |
| "set up CDN" | Addressables remote groups + Brotli/Gzip on CDN |
| "WebAssembly 2023" | Enable when browser baseline supports it — smaller and faster |
| "memory growth slow" | Tune Initial Memory Size to peak estimate; use Geometric growth mode |
| "KTX" / "Basis Universal" / "texture formats unknown GPU" | KTX2 with Basis Universal; ETC1S for size, UASTC for quality |
| "strip unused code" / "remove unused packages" | Web Stripping Tool + remove unused packages + shader stripping |
| "quality settings for web" | Quality Level to Very Low or Low; lower quality = faster load |
| "shader variants too many" | Graphics settings: auto lightmap/fog modes; strip instancing + BRG variants; audit Always Included Shaders |
| "video not playing" / "audio issues" | Video: URL-only or StreamingAssets; Audio: no AudioEffects on Web, use Mono, compress |
| "profiler symbols" / "can't read Wasm stacks" | Embed profiling symbols via build processor or emscriptenArgs |
| "iOS crashes" / "Safari memory" | iOS memory limits; set Initial Memory Size high rather than growing; Gigacage 2GB limit pre-iOS 18 |

## 3. Web Build Optimization Workflow

### IMPORTANT: One-click optimization script

**Always offer to generate this script for the user.** Unity's official web optimization docs provide a single editor menu script that applies all recommended release settings at once. Place in `Assets/Editor/WebOptimizer.cs` — see [resources/WebOptimizer.cs](resources/WebOptimizer.cs) for the template.

Adapt the script to the user's project needs (e.g. keep exceptions if they use `try/catch`, switch Brotli to Gzip for HTTP hosting). This script is the single most impactful action for a new web project — it prevents settings from being missed.

### Player Settings audit

Verify and set these values through `eval`:

| Setting | Release recommendation |
|---|---|
| **Compression Format** | **Brotli** (HTTPS hosting); Gzip for HTTP |
| **Decompression Fallback** | **Off** when server is correctly configured |
| **Strip Engine Code** | **On** |
| **Managed Stripping Level** | **High** (release) / Medium (dev) |
| **Code Optimization** | **Disk Size with LTO** (release) / Build Times (dev) |
| **WebAssembly Language Features** | **2023** if browser baseline allows |
| **Enable Exceptions** | **None** (smallest); Explicitly Thrown Only if `try/catch` required |
| **Initial Memory Size** | Tune to peak estimate; too small causes expensive growth |
| **Memory Growth Mode** | **Geometric** |
| **API Compatibility Level** | **.NET Standard 2.1** — smaller than .NET Framework |
| **IL2CPP Code Generation** | **Optimize Size** — smaller Wasm at slight runtime cost |
| **Debug Symbols** | **Off** for release; on for development builds only |
| **Data Caching** | **On** — caches asset data in browser IndexedDB for faster repeat loads |
| **Strip Unused Mesh Components** | **On** — removes unused vertex attributes |
| **Maximum Memory Size** | **2048 MB** default; up to 4096 for complex 3D (Firefox and Chrome < 119 have issues above 2048) |
| **vSyncCount** | 0 (browser handles pacing) |
| **targetFrameRate** | -1 (use `requestAnimationFrame`) |

### Compression and server configuration

| Compression | Use when | Notes |
|---|---|---|
| **Brotli** | HTTPS or localhost | Best ratio; browsers accept only over secure contexts |
| **Gzip** | HTTP delivery, legacy CDNs | Universal |
| **None** | Local dev / file:// | Largest payload; do not ship |

Configure the server to:
- Serve `.br` files with `Content-Encoding: br`.
- Serve `.gz` files with `Content-Encoding: gzip`.
- Set `Content-Type: application/wasm` for `.wasm`, `application/javascript` for `.js`.
- Enable HTTP/2 or HTTP/3 to parallelize chunk fetches.

If the host cannot inject `Content-Encoding`: set **Decompression Fallback = On** as a fallback only — it adds ~150 KB JS and slows startup.

### Exception handling

| Setting | Build size | Use |
|---|---|---|
| **None** | Smallest | Release builds where uncaught exceptions are acceptable |
| **Explicitly Thrown Only** | Modest | Default for projects that catch exceptions |
| **Full** | Largest, slowest | Rarely needed; avoid for release |

Wasm 2023 introduces a cheaper exception model; switching from Explicitly Thrown Only (legacy) to Wasm exceptions reduces both size and cost when browser targets support it.

### Remove unused resources

Three categories to audit for build size reduction:

**1. Unused packages** — Check `Packages/manifest.json` and the Package Manager **In Project** and **Built-in** views. Remove or disable packages the project does not use. The Input System package is a significant size contributor if unused.

**2. Shader stripping** — Configure in `Edit > Project Settings > Graphics`:

| Setting | Recommendation |
|---|---|
| **Lightmap Modes** | Automatic (strips unused lightmap shader variants) |
| **Fog Modes** | Automatic (strips unused fog shader variants) |
| **Instancing Variants** | Strip Unused |
| **Batch Renderer Group Variants** | Strip All (if BRGs are not used) |
| **Always Included Shaders** | Audit and remove any shaders the project does not reference |

Test after stripping — ensure no referenced shaders were removed.

**3. Web Stripping Tool** (`com.unity.web.stripping-tool`) — Analyzes the WebAssembly binary and identifies unused Unity engine submodules (e.g. 3D graphics in a 2D-only game). Install via Package Manager, profile the build, then configure which submodules to exclude. Can yield substantial size reductions beyond what Managed Stripping Level achieves alone.

### Quality settings for Web

Lower quality levels reduce load time and improve runtime performance. Set via `Edit > Project Settings > Quality`:

- Use **Very Low** or **Low** as the default Web quality level.
- Set it with `eval`: `UnityEngine.QualitySettings.SetQualityLevel(0, true);` where 0 = Very Low.
- Consider creating a Web-specific quality level that disables features unnecessary in-browser (real-time shadows, post-processing effects, high particle counts).

### Frame rate on Web

- Set it with `eval`: `UnityEngine.Application.targetFrameRate = -1;` — let the browser use `requestAnimationFrame`.
- Note: **Safari caps at 60 fps** in WebGL; high-refresh targets do not apply.
- Use `OnDemandRendering.renderFrameInterval` to drop to 5–10 fps on static/idle screens to save battery.

### KTX / Basis Universal textures

KTX2 with Basis Universal supercompression ships a single texture file that transcodes at load time to the optimal GPU format for the browser's device (BC7 on desktop, ASTC on mobile, ETC2 on older Android). This avoids shipping separate texture variants for each GPU family — critical for Web where the target hardware is unknown.

| Topic | Guidance |
|---|---|
| **Package** | Install `com.unity.cloud.ktx` (KtxUnity) via Package Manager |
| **When to use** | Runtime-loaded textures via Addressables or asset bundles served to unknown GPU targets |
| **When NOT to use** | Textures baked into the player build — Unity already selects the correct format at build time |
| **Supercompression** | Use **ETC1S** for smallest size (lossy, good for diffuse/albedo); **UASTC** for higher quality (near-lossless, better for normals/UI) |
| **Encoding** | Encode offline with `toktx` or `basisu` CLI; do not encode at runtime |
| **Linear data** | Set `--assign_oetf linear` when encoding normal maps, masks, or data textures to avoid incorrect sRGB conversion |
| **Mip maps** | Generate mips at encode time (`--genmipmap`) — browser-side mip generation is expensive |
| **Loading** | Use `KtxTexture.LoadFromStreamingAssets` or load bytes via UnityWebRequest and call `KtxTexture.LoadFromBytes` |
| **Memory** | Transcoded textures are standard GPU textures; memory cost equals the target format, not the KTX2 file size |
| **Orientation** | Always include `--lower_left_maps_to_s0t0` to match Unity's UV convention |

**`toktx` CLI examples:** See [resources/toktx-examples.sh](resources/toktx-examples.sh) for commands covering albedo (ETC1S), normals/detail (UASTC), ICC profile errors, and linear data.

### Streaming on Web

- Use Addressables with **remote groups** hosted on a CDN with Brotli / Gzip.
- Avoid bundling the entire game into the initial download; stream levels on demand.
- Target < 30 MB initial download for "instant play"; level data follows.
- For streamed textures targeting mixed GPU hardware, prefer KTX2 bundles over per-platform variants — one bundle serves all browsers.

### Profiling Web builds

| Tool | Use | Notes |
|---|---|---|
| **Chrome DevTools > Performance** | CPU flamegraph; main-thread analysis | Default first stop for WebGL hitches; inspect Wasm call stacks |
| **Chrome DevTools > Memory** | Heap snapshot; allocation timeline | Find JS/Wasm memory leaks; compare snapshots before/after scene load |
| **Firefox Profiler** | Cross-platform; shareable URLs; native + Wasm view | Better Wasm symbolication than Chrome in some cases; shareable profile URLs for team review |
| **Safari Web Inspector** | iOS Safari and macOS Safari debugging | Required for Safari-specific issues; WebGL/Wasm runtime differs from Chromium |
| **Unity Profiler over WebSocket** | Connect to a development build; standard markers | Use for Unity-side markers (GC, rendering, scripts); does not capture browser-side overhead |

**Symptom → tool quick reference:**

| Symptom | First-line tool | Second-line tool |
|---|---|---|
| WebGL hitch / stutter | Chrome DevTools > Performance | Firefox Profiler |
| Memory climbing over time | Chrome DevTools > Memory | Unity Memory Profiler (WebSocket) |
| Slow initial load | Chrome DevTools > Network | Build Report Inspector |
| Safari-only rendering issue | Safari Web Inspector | Compare with Chrome DevTools |

**Embedding profiling symbols** — browser profilers show mangled Wasm function names by default. To get readable C# method names in Chrome/Firefox flamegraphs, either enable `Player Settings > Publishing > Debug Symbols` for dev builds, or add a build processor:

```csharp
using UnityEditor;
using UnityEditor.Build;
using UnityEditor.Build.Reporting;

public class WebProfilingBuildProcessor : IPreprocessBuildWithReport
{
    public int callbackOrder => 0;
    public void OnPreprocessBuild(BuildReport report)
    {
        PlayerSettings.SetAdditionalIl2CppArgs("--compiler-flags=--profiling-funcs");
    }
}
```

**Emscripten built-in profilers** — enable one at a time via `PlayerSettings.WebGL.emscriptenArgs`:

| Flag | What it shows |
|---|---|
| `--cpuprofiler` | CPU profiler overlay in browser |
| `--memoryprofiler` | Visual memory map (white=allocated unused, pink=stack, blue=dynamic, green=fragmented) |
| `--threadprofiler` | Thread activity profiler |

**GPU debugging** — No Frame Debugger support on Web. Use [Spector.js](https://spector.babylonjs.com/) as a browser-based alternative — it captures draw calls and WebGL state.

**Firefox `about:memory`** — type `about:memory` as a URL in Firefox, click Measure to see per-tab breakdown: WASM code size, WASM heap, .data file, web audio. Watch for WASM heap > 300 MB (crash risk, especially on iOS Safari).

Editor Play Mode does not represent browser runtime; always measure in browser. Chrome and Safari GC and JIT behavior differ — test both.

### Web memory directives

- Disable **Read/Write Enabled** on textures and meshes — it duplicates data into the WASM heap.
- Reduce `.data` file size by moving assets to Addressables or AssetBundles.
- Use compressed texture formats (KTX2/Basis) to reduce both download and decoded memory cost.

### iOS Safari memory limits

- **iOS < 18:** WebContent process limit ~1.5 GB. WASM memory (Gigacage) capped at 2 GB. Typed arrays share this pool. On iPhone X (iOS 16) heap growth caps at ~512 MB, but setting Initial Memory Size to 512 MB–1.5 GB upfront works.
- **iOS 18+:** Limits largely lifted; iPhone 11 can allocate ~4 GB.
- On iOS, set **Initial Memory Size** to the target peak rather than relying on growth — Safari handles large upfront allocations better than incremental growth.
- WASM heap > 300 MB risks crashes on older iOS; target < 200 MB for broad compatibility.

### Video and audio on Web

- **Video:** Playback only works from a URL (server with CORS enabled) or from StreamingAssets. On iOS the server must support HTTP range requests for streaming. Use browser-compatible formats (MP4/H.264).
- **Audio:** AudioEffects (mixer effects) require compute shaders — **not available on WebGL**. Mixers and MixerGroups work for volume control only. Set audio to **Mono** to improve loading. If `about:memory` shows web audio > 100 MB, audio is likely uncompressed — switch to Vorbis.

### Canvas and DPI

If the canvas is scaled up it takes the new resolution. Use `devicePixelRatio` in the web template to offset DPI scaling and avoid rendering at unnecessarily high resolution.

## 4. Validation

1. Re-read the Player Settings with the Pre-Flight snippet (compression, stripping, exceptions, targetFrameRate).
2. Rebuild the player and compare Build Report file sizes with baseline.
3. Verify in at least Chrome and Safari (GC and JIT behavior differ).
4. Max **3 iterations** before asking the user for feedback.

## 5. Troubleshooting

### Build still large after enabling Strip Engine Code

1. Is **Managed Stripping Level** set to Medium or Low? → Set to High for release.
2. Are plug-ins using reflection to access engine modules that would otherwise be stripped? → Add a `link.xml` to preserve needed symbols.
3. Is **Exceptions** set to Full? → Full adds the largest code overhead; switch to None or Explicitly Thrown Only.

### Brotli not working — Decompression Fallback required

1. Is the server sending `Content-Encoding: br`? → Without this header the browser won't decompress; the fallback JS decompressor is then needed.
2. Is the build hosted over HTTP (not HTTPS)? → Brotli requires a secure context; degrade to Gzip for HTTP hosting.

### Stutter in Safari but not Chrome

1. Does the project set `Application.targetFrameRate = 60`? → On Safari WebGL this conflicts with browser pacing; set to `-1`.
2. Are there shaders that behave differently on Safari's WebGL implementation? → Test on device; Safari's WebGL/Wasm runtime differs from Chromium — some GLSL constructs are handled differently.

### Memory growth slow path triggered

1. Is **Initial Memory Size** too small for the project's peak? → Wasm memory growth requires a full buffer copy; set Initial Memory Size to a realistic peak estimate.
2. Is **Memory Growth Mode** set to Linear? → Switch to **Geometric** for saner growth curve.

### Frame rate set to 60 but browser runs erratically

1. Is `Application.targetFrameRate = 60` set in code? → On Web this conflicts with `requestAnimationFrame` browser pacing. Set to `-1`.
2. Is `vSyncCount` non-zero? → Set to 0; the browser handles pacing.

### Firefox cache rejecting large files

Firefox limits individual cache entries via `browser.cache.disk.max_entry_size`. If the build exceeds this (default ~50 MB), assets won't cache. Solution: use Addressables to split into bundles < 51 MB, or instruct users to increase the setting in `about:config`.

### Local dev server setup

For testing builds locally with proper MIME types:

```bash
# Python (HTTP)
python -m http.server 55553 -d path/to/build

# Node.js (install serve-handler)
npx serve path/to/build -l 3001
```

For Brotli testing, use HTTPS — Brotli requires a secure context. Generate a self-signed cert with OpenSSL for local testing.

## 6. Completion

- Summarize: initial download size delta, settings changed (compression, stripping, exceptions, targetFrameRate), server configuration confirmed.
- List follow-up actions: CDN setup for Addressables remote groups, Safari testing, Wasm 2023 feature set upgrade when browser baseline allows.

## See also

These point at Unity tooling rather than other skills, because the topics they cover are not in
this plugin:

- **Addressables package** — remote groups served over a CDN, when the download budget needs content
  moved out of the initial payload.
- **Unity Profiler, connected to the browser** — the cross-platform profiling methodology. Section 3
  covers the Web-specific part of attaching it.
- **Shader variant stripping** (Graphics settings → Shader Stripping, and `ShaderVariantCollection`)
  — variant count feeds directly into Wasm size, so it is worth checking when stripping alone hasn't
  moved the number.
- **Project Settings → Player** — the same flags this skill reads, if the user would rather see them
  in the inspector than have them reported.
- Mobile browser battery behaviour follows the same frame-rate and quality-level guidance in
  Sections 3 and 4; there is no separate mobile path here.

Referenced files: 2

View saved version →

---
name: physics-3d-collision
description: 3D PhysX collision and trigger diagnostics for MonoBehaviour-based Unity projects. Primary scope: OnCollisionEnter / OnTriggerEnter not firing, objects passing through each other, Physics.Raycast missing, ragdoll explosion, AddForce stops working after settling, MeshCollider rules, and similar 3D PhysX symptoms. Adjacent topics (2D physics, OTS / Unity Physics package): provides a brief best-effort answer with a scope disclaimer and a documentation link, rather than refusing outright. When dedicated specialist skills (physics-2d, physics-dots) are installed, those should handle their respective domains and this skill defers to them.
---

# 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 2D APIs (`Rigidbody2D`, `Collider2D`, `OnCollisionEnter2D`, etc.).
3. **One-sentence docs link** at the end.

Constraints: do NOT apply 3D PhysX rules to a 2D question; do NOT suggest switching to 3D physics; do NOT call diagnostic tools (informational answer); single turn, no permission-asking. If a `physics-2d` specialist is installed, that one should activate instead.

### Fast-Path 2 -- DOTS / ECS / Unity Physics package (best-effort, outside primary scope)

**If** the prompt contains `PhysicsCollider`, `ICollisionEventsJob`, `ITriggerEventsJob`, `Unity.Physics`, "Unity Physics" (the package), `Havok`, DOTS, ECS, or `Entities`:

Provide a brief best-effort answer using DOTS APIs. Structure:

1. **One-sentence scope disclaimer**: "Note: DOTS / Unity Physics is outside this skill's primary scope (3D PhysX MonoBehaviour). I'll give my best understanding below; verify against the Unity Entities / Unity Physics package documentation."
2. **Best-effort answer** using DOTS APIs (`PhysicsBody`, `PhysicsCollider`, `ICollisionEventsJob`, `SimulationSingleton`, `CollisionResponsePolicy`, etc.).
3. **One-sentence docs link** at the end.

Constraints: do NOT apply MonoBehaviour Rigidbody rules (`Rigidbody.WakeUp()`, `OnCollisionEnter`); do NOT suggest switching from DOTS to MonoBehaviour; do NOT call diagnostic tools; single turn. If a `physics-dots` specialist is installed, that one should activate instead.

### Fast-Path 3 -- Two kinematic triggers not firing OnTriggerEnter

**If** both objects are kinematic AND both are triggers: see **CRITICAL FACT** above. Apply that response. Do NOT investigate, do NOT fetch docs, do NOT run `Physics.Simulate()`.

### Fast-Path 4 -- Ragdoll explodes on frame 1 with no applied forces

**If** the prompt describes a ragdoll, jointed body, or character launching/exploding on the first frame with no applied forces:
- Cause: overlapping colliders cause a one-frame depenetration velocity spike.
- Fix: shrink ragdoll colliders so none overlap at the starting pose. This is the ONLY recommended primary fix. State it explicitly.
- Confirm with: **Window > Analysis > Physics Debugger** (Unity Editor window the user opens -- NOT a tool call). It highlights overlapping pairs in red on frame 1.
- Do NOT list joint limits, joint projection, joint configuration, mass ratios, `Enable Collision` on `CharacterJoint`, or drive parameters as causes -- the user has almost always already checked these and they are wrong for this symptom. The cause is overlapping colliders, full stop.
- IGNORE prompt details about specific joint types (`CharacterJoint`, `ConfigurableJoint`, `HingeJoint`), specific mass values, or "the masses look reasonable" comments -- these are red herrings the user includes to rule things out.
- Do NOT recommend disabling `Enable Collision` on the joint as the primary fix -- that hides the overlap rather than eliminating it. Shrink colliders.
- Do NOT call any tools to inspect the ragdoll. Write the diagnosis and stop.

### Fast-Path 5 -- CharacterController + OnCollisionEnter not firing

**If** the moving object has a `CharacterController` and the user expects `OnCollisionEnter`:
- `OnCollisionEnter` cannot fire on a `CharacterController`-driven object. Use `OnControllerColliderHit(ControllerColliderHit hit)` instead.
- Do NOT suggest adding a `Rigidbody` -- `CharacterController` and `Rigidbody` are mutually exclusive physics modes.

### Fast-Path 6 -- AddForce stopped working after object settled

**If** `AddForce` (or `AddTorque`) stopped working after the object landed/settled/stopped:
- Cause: Rigidbody fell asleep (velocity dropped below `Physics.sleepThreshold`).
- Fix: call `Rigidbody.WakeUp()` before `AddForce`, or apply a force above the sleep threshold.
- Apply the code edit directly. Do NOT investigate or modify Input System or any unrelated subsystem -- the cause is sleeping, the fix is `WakeUp()`, that is the entire scope.

### Fast-Path 7 -- All physics frozen but raycasts still work

**If** all physics callbacks have stopped and `AddForce`/gravity have no effect, but `Physics.Raycast` still returns hits:
- Cause: `Time.timeScale = 0`. Fix: restore `Time.timeScale = 1f` (typically in pause-menu / cutscene controller).

### Fast-Path 8 -- Raycast origin inside the target collider

**If** `Physics.Raycast` returns false AND `Debug.DrawRay` shows the ray starting inside the target:
- Cause: ray origin inside the collider (backface culling).
- Fix (recommended): offset the origin outside the collider bounds. Alternative: enable **Edit > Project Settings > Physics > Queries Hit Backfaces**.

### Fast-Path 9 -- Raycast misses inactive GameObject or disabled Collider

**If** `Physics.Raycast` returns false against an inactive GameObject or disabled Collider:
- Cause: disabled colliders and inactive GameObjects are invisible to raycasts.
- Fix: ensure `gameObject.activeInHierarchy` is true AND `Collider.enabled` is true before raycasting.

### Fast-Path 10 -- Raycast misses a trigger

**If** `Physics.Raycast` does not detect a trigger collider:
- Cause: `Physics.Raycast` ignores triggers by default.
- Fix: pass `QueryTriggerInteraction.Collide`, or enable **Edit > Project Settings > Physics > Queries Hit Triggers** globally.

### Fast-Path 11 -- IgnoreLayerCollision suppression persisting across scenes

**If** `Physics.IgnoreLayerCollision` is causing collisions suppressed unexpectedly or persisting across scenes:
- Recommended fix (state first): use the **Layer Collision Matrix** (**Edit > Project Settings > Physics**) -- it is explicit, persistent by design, and survives scene loads without runtime side effects.
- Code-only fallback: `Physics.IgnoreLayerCollision(layerA, layerB, false)` at scene load.

---

## Tool Budget

For cases not covered by Fast-Paths above: **maximum 5 tool calls before committing to an answer**. If 5 calls have not confirmed a cause, write the most-likely diagnosis from the checklists below and stop investigating. Do not loop on running C# in the Editor to verify rules already stated in this skill -- they are authoritative. NEVER fetch documentation to verify a fact stated in this skill.

---

## 1. Identify Your Symptom

**Check the Fast-Path table above first.** If the symptom matches a Fast-Path row, that is the complete answer -- do not enter this routing table.

| Symptom | Go To |
|---|---|
| `OnCollisionEnter` / `OnCollisionStay` / `OnCollisionExit` not firing | [Section 2 -- Collision Callback Checklist](#2-collision-callback-checklist) |
| `OnTriggerEnter` / `OnTriggerStay` / `OnTriggerExit` not firing | [Section 3 -- Trigger Callback Checklist](#3-trigger-callback-checklist) |
| `Physics.Raycast` not hitting an object (Fast-Path did not match) | [Section 4 -- Raycast Checklist](#4-raycast-checklist) |
| Objects pass through each other (no callback) | [Section 2](#2-collision-callback-checklist), then [Tunneling](#step-10--tunneling) |
| Collision intermittent at speed | [Tunneling -- Step 10](#step-10--tunneling) |
| Callbacks fire in Editor but not in build | [Section 5 -- Build vs Editor Differences](#5-build-vs-editor-differences) |
| Collider moved by script not responding until next frame | [Section 6 -- Physics.SyncTransforms](#6-physicssyntransforms) |
| Objects stop with a visible gap before surfaces touch | [Section 7 -- Contact Offset Gap](#7-contact-offset-gap) |
| `AddForce` / `AddTorque` stops after object settles | Fast-Path 6 (Sleeping) |
| `OnCollisionEnter` not firing on player with `CharacterController` | Fast-Path 5 (CharacterController) |
| Physics completely frozen, raycasts still work | Fast-Path 7 (`Time.timeScale = 0`) |

---

## 2. Collision Callback Checklist

**First-match wins**: stop at the first step that confirms the cause.

### Step 1 -- Rigidbody rule

At least one of the two colliding GameObjects must have a **`Rigidbody`** (not `Rigidbody2D`). Two static colliders never generate `OnCollisionEnter`. Both GameObjects and all parents up the hierarchy should be checked. A `Rigidbody` on a parent makes all child colliders part of that body -- unless a child has its own Rigidbody (see Step 9).

### CharacterController Exception
<a name="charactercontroller-exception"></a>

If the moving object has a **`CharacterController`**, `OnCollisionEnter` will never fire. `CharacterController.Move()` bypasses the Rigidbody system and reports impacts via:

```csharp
void OnControllerColliderHit(ControllerColliderHit hit) { /* ... */ }
```

Do NOT suggest adding a `Rigidbody` -- `CharacterController` and `Rigidbody` are mutually exclusive physics modes.

### Step 2 -- Interaction matrix

| Object A | Object B | `OnCollisionEnter` fires? |
|---|---|---|
| Dynamic Rigidbody | Dynamic Rigidbody | **Yes** |
| Dynamic Rigidbody | Static Collider (no Rb) | **Yes** |
| Dynamic Rigidbody | Kinematic Rigidbody | **Yes** (on the dynamic object only) |
| Kinematic Rigidbody | Kinematic Rigidbody | **No** |
| Kinematic Rigidbody | Static Collider | **No** |
| Static Collider | Static Collider | **No** |

If both objects are Kinematic, or one is Static and the other Kinematic, no callback is generated. **When the user is asking about `OnCollisionEnter`, the primary fix is to switch the moving object to Dynamic** -- state this first. Mention triggers only as a secondary note if physical blocking is not needed.

### Step 3 -- Layer Collision Matrix

Open **Edit > Project Settings > Physics**. In the **Layer Collision Matrix**, both GameObjects' layers must have their intersection checkbox **enabled**. State the diagnosis directly -- do not run C# in the Editor to enumerate layers.

NEVER use `Physics.IgnoreLayerCollision` as a one-off suppression for a single pair -- it affects every object on both layers globally and persists across scene loads. INSTEAD define rules in the Layer Collision Matrix.

NEVER rely on `Physics.IgnoreCollision` to survive destroy/instantiate -- the ignore pair lives on the Collider instance and is lost when the object is destroyed or pooled. INSTEAD re-call `Physics.IgnoreCollision` on `Awake` / `OnEnable` for every new instance.

### Step 4 -- `isTrigger` mismatch

`OnCollisionEnter` requires **both** colliders to have `isTrigger = false`. If either is a trigger, Unity fires `OnTriggerEnter` instead. Inspect **Is Trigger** on every collider in both objects.

### Step 5 -- Collider enabled and active

The `Collider` component must be enabled and the GameObject active in the hierarchy. Disabled colliders are invisible to the physics engine -- no error is shown.

### Step 6 -- Script location

The MonoBehaviour containing `OnCollisionEnter` must be on the **same GameObject** that owns the Collider or Rigidbody. Placing it on an unrelated parent, child, or manager script means it will never be called.

### Step 7 -- MeshCollider rules

PhysX enforces strict rules on MeshColliders. Violations are silent.

| Situation | Result | Fix |
|---|---|---|
| Non-convex `MeshCollider` on a **dynamic** Rigidbody | Silently ignored | Enable Convex, or replace with compound primitives |
| Two non-convex `MeshColliders` against each other | No collision | Make at least one Convex, or use a primitive on the simpler shape |
| Convex `MeshCollider` on a dynamic Rigidbody | Works -- contact at the convex hull | Expected; visualize hull via Gizmos > Physics |
| Non-convex `MeshCollider` vs static geometry | Works -- valid for static | No fix needed |
| `MeshCollider` with inverted normals | Contacts push objects into the collider | Fix normals in DCC tool, or enable Convex (auto-corrects winding) |

### Step 8 -- Non-uniform scale distorting child colliders

If a parent transform has non-uniform scale (e.g., `(1, 2, 1)` or root import correction `(0.01, 0.01, 0.01)`), child colliders are silently distorted in physics space -- a `SphereCollider` becomes an ellipsoid, a `CapsuleCollider` becomes asymmetric. Visual looks correct; collisions happen at the wrong shape.

**Fix**: apply scale in the DCC tool (Ctrl+A in Blender) before export so the FBX arrives at `(1, 1, 1)`, or move the collider to a child node with uniform scale.

### Step 9 -- Child Rigidbody breaking the compound

A Rigidbody on a parent makes all descendant colliders part of its body -- until the hierarchy hits another Rigidbody. A child Rigidbody silently splits the compound body. Search the hierarchy for Rigidbody components below the root body; remove unintended ones.

### Step 10 -- Tunneling
<a name="step-10--tunneling"></a>

Intermittent callbacks on fast-moving objects usually indicate tunneling -- the Rigidbody moves far enough in one physics step to skip past the collider entirely. Set via **Rigidbody > Collision Detection** in the Inspector.

| Mode | m_CollisionDetection | Coverage |
|---|---|---|
| `Discrete` | 0 | Default; tunnels at speed |
| `Continuous` | 1 | Sweeps vs **static colliders only**; degrades to Discrete vs dynamic Rigidbodies |
| `Continuous Dynamic` | 2 | Sweeps vs static AND vs other `ContinuousDynamic` Rigidbodies (more expensive) |
| `Continuous Speculative` | 3 | Speculative contacts; works vs everything; cheaper than CCD; can fire occasional ghost contacts |

**Picking a mode:**
- Fast object vs **static geometry** (thin floors, walls, terrain): `Continuous Speculative` is the recommended default. `Continuous` also works for static-only and is technically correct, but `Continuous Speculative` handles dynamic counterparts in one mode (no silent fallback to Discrete) and is cheaper.
- Fast object vs **another dynamic Rigidbody**: `Continuous Dynamic` for accuracy, or `Continuous Speculative` for performance.
- When in doubt: `Continuous Speculative`.

**Naming**: write the full Inspector name verbatim. `Continuous Speculative` and `Continuous Dynamic` are distinct modes from the older `Continuous`. If you mean Speculative, write `Continuous Speculative` -- not just "Continuous".

**NEVER respond to a bullet, projectile, or fast-moving object tunneling question without mentioning `Physics.SphereCast` as an alternative.** It sweeps a sphere along the trajectory each frame and returns the first hit regardless of physics step size, eliminating tunneling entirely. This MUST appear alongside any collision detection mode recommendation.

### Step 11 -- Overlapping colliders at simulation start

If on frame 1 with no applied forces: **stop** -- this is Fast-Path 4. Apply that response.

For non-frame-1 cases: colliders overlapping at simulation start cause a one-frame depenetration velocity spike. ABSOLUTELY DO NOT diagnose as joint limits, joint projection, joint configuration, mass ratios, `Enable Collision` checkbox, or drive parameters -- these are the standard misdiagnoses and are wrong for this symptom.

**Primary fix**: shrink colliders so none overlap at the starting pose. Confirm with **Window > Analysis > Physics Debugger**. **Temporary workaround only**: `Rigidbody.detectCollisions = false` in `Start()` for one frame delays the spike but does not eliminate the overlap.

### Step 12 -- 2D/3D method signature confusion

Using a 2D suffix on a 3D callback silently does nothing:

```csharp
void OnCollisionEnter(Collision col) { }     // 3D -- correct
void OnCollisionEnter2D(Collision2D col) { } // 2D -- never called in a 3D scene
```

Search the script for `2D` in the method name. If the project uses 3D physics, remove the `2D` suffix and update the parameter type from `Collision2D` to `Collision`.

---

### Investigation Hygiene

**Never leave project settings in a modified state.** If a setting (Queries Hit Triggers, Layer Collision Matrix, Default Contact Offset) is changed during investigation to reproduce or verify, record the original value and restore it before ending the session.

---

## 3. Trigger Callback Checklist

**First-match wins**: stop at the first step that confirms the cause.

### Step 1 -- `isTrigger` on at least one collider

`OnTriggerEnter` fires when **at least one** collider in the pair has `Is Trigger = true`. If neither is a trigger, Unity fires `OnCollisionEnter` instead.

### Step 2 -- Rigidbody rule

At least one GameObject must have a `Rigidbody`. Two static triggers never fire `OnTriggerEnter`.

| Object A | Object B | `OnTriggerEnter` fires? |
|---|---|---|
| Trigger + Dynamic Rb | Static Collider | **Yes** |
| Trigger + Dynamic Rb | Trigger + Dynamic Rb | **Yes** |
| Trigger + Dynamic Rb | Kinematic Rb | **Yes** |
| Trigger + Kinematic Rb | Trigger + Kinematic Rb | **Yes** -- see CRITICAL FACT and Fast-Path 3 |
| Trigger (no Rb) | Static Collider (no Rb) | **No** |

### Step 3 -- Layer Collision Matrix

**Edit > Project Settings > Physics** -- both layers must be allowed to interact.

### Step 4 -- Correct method signature

```csharp
void OnTriggerEnter(Collider other) { }     // 3D -- correct
void OnTriggerEnter2D(Collider2D other) { } // 2D -- wrong for 3D
```

### Step 5 -- Script on the right GameObject

The callback script must be on the **trigger GameObject** or the **entering object**, not on an unrelated parent or manager.

---

## 4. Raycast Checklist

**First-match wins**: stop at the first step that confirms the cause.

### Step 1 -- Ray origin inside the target collider

**`Physics.Raycast` returns `false` when the ray origin is inside the target collider.** This is the root cause when `Debug.DrawRay` shows the ray starting inside an object. State this and the fix immediately.

```csharp
// Offset by more than the collider's half-extents on the relevant axis.
Ray ray = new Ray(transform.position + Vector3.up * 0.5f, Vector3.down);
```

### Step 2 -- LayerMask excludes the target

If a `layerMask` is passed, the target layer must be included. Two debug approaches:

```csharp
// Option A -- hit everything to confirm ray path is correct
Physics.Raycast(ray, out hit, distance, Physics.DefaultRaycastLayers);

// Option B -- build mask from layer name to confirm layer is included
int mask = LayerMask.GetMask("Enemy");
Physics.Raycast(ray, out hit, distance, mask);
```

Both should be mentioned when advising on a LayerMask miss. The production mask must include the target layer -- via `LayerMask.GetMask("LayerName")` or `1 << LayerIndex`.

### Step 3 -- QueryTriggerInteraction

Already covered by Fast-Path 10. State the fix and stop:
```csharp
Physics.Raycast(ray, out hit, distance, layerMask, QueryTriggerInteraction.Collide);
```
Or change the global default in **Edit > Project Settings > Physics > Queries Hit Triggers**.

### Step 4 -- Collider disabled or object inactive

Already covered by Fast-Path 9. State the fix (`activeInHierarchy = true`, `Collider.enabled = true`) and stop. Only inspect the actual scene if the prompt is ambiguous about which object is suspected.

### Step 5 -- Non-convex MeshCollider on a dynamic Rigidbody

Unity silently ignores a non-convex `MeshCollider` on a dynamic Rigidbody for collision and raycasts. Enable Convex, or replace with compound primitives.

### Step 6 -- Back-face hits

By default, `Physics.Raycast` does not detect hits on the back face of a mesh. If the ray enters from inside (e.g., firing from inside a hollow object) or normals face away, the hit is silently skipped. **Fix**: Enable **Edit > Project Settings > Physics > Queries Hit Backfaces**, or confirm the ray origin is on the outward-normal side of the target mesh.

---

### XR / UI Raycasts

- **`GraphicRaycaster`** hits UI Canvas elements only.
- **`Physics.Raycast`** hits 3D colliders only.

NEVER use `GraphicRaycaster` when the target is a 3D collider. INSTEAD `Physics.Raycast` for world-space 3D targets.

---

## 5. Build vs Editor Differences

| Cause | Symptom | Fix |
|---|---|---|
| IL2CPP stripping MonoBehaviour | Callback script removed from build | Add `[Preserve]` to the class, or add a `link.xml` to preserve the assembly |
| PhysX initialization order | Objects collide before physics has settled | One-frame delay in `Start()` via coroutine, or manual simulation: `Physics.simulationMode = SimulationMode.Script` + `Physics.Simulate(Time.fixedDeltaTime)` (Unity 2022.2+); `Physics.autoSimulation = false` on older versions |
| Layer names referenced by string in code | Layer-based filtering fails if a layer name differs between Editor and build | Reference layers by index, not string name, in production code |
| `Time.fixedDeltaTime` platform difference | Physics step rate differs between platforms | Set **Edit > Project Settings > Time > Fixed Timestep** explicitly |

---

## 6. Physics.SyncTransforms

When a collider is moved by writing to `transform.position` directly (not via `Rigidbody.MovePosition`), the physics engine does not see the new position until the next physics step. Same-frame queries use the old position.

```csharp
transform.position = newPos;
Physics.SyncTransforms(); // forces immediate broadphase update
Physics.Raycast(ray, out hit); // now sees the new position
```

NEVER call `Physics.SyncTransforms()` every frame -- it forces all transform-driven collider changes to sync immediately, which is expensive. ALWAYS mention both: (1) `Rigidbody.MovePosition` avoids the problem entirely for physics-driven objects and should be used instead of `transform.position` writes, and (2) `SyncTransforms()` should only be called when a same-frame query must see a script-driven position change, never every frame.

---

## 7. Contact Offset Gap

Colliders stop with a small visible gap before touching. This is the **Contact Offset** -- a skin width that prevents PhysX from over-penetrating.

- **Global default**: **Edit > Project Settings > Physics > Default Contact Offset** (default: `0.01`).
- **Per-collider**: `Collider.contactOffset` in the Inspector or via script.

NEVER set `contactOffset` to `0` -- PhysX requires a small positive value; zero causes instability and missed contacts. Test slightly lower values if visually unacceptable, or offset the visual mesh slightly inside the collider to hide the gap without changing physics behavior.

---

## 8. Time.timeScale and Physics Simulation

When `Time.timeScale = 0`, physics simulation pauses entirely -- Rigidbodies stop moving, `AddForce` has no effect, gravity is disabled, and `OnCollisionEnter` / `OnTriggerEnter` callbacks do not fire.

**Geometry queries are not affected**: `Physics.Raycast`, `Physics.OverlapSphere`, etc. operate on collider geometry directly and continue at `timeScale = 0`. If callbacks have stopped but raycasts still work, `Time.timeScale = 0` is the cause.

**Fix**: Restore `Time.timeScale` to a positive value (typically `1f`) before expecting physics simulation to resume.

---

## 9. Rigidbody Sleeping

If "AddForce stopped working after object settled/landed", apply Fast-Path 6 directly. Do NOT investigate Input System or other unrelated subsystems.

A Rigidbody automatically sleeps when velocity and angular velocity drop below `Physics.sleepThreshold` for several fixed frames. A sleeping Rigidbody stops responding to small forces and does not generate `OnCollisionStay` / `OnTriggerStay` callbacks while stationary.

**Detect**: `Rigidbody.IsSleeping()` returns true; Inspector shows zero velocity in Play Mode.

**Fixes:**
1. Call `Rigidbody.WakeUp()` before applying a force.
2. Increase the applied force above the sleep threshold.
3. `Rigidbody.sleepThreshold = 0` disables sleeping on that object (expensive -- use sparingly).
4. Global: **Edit > Project Settings > Physics > Sleep Threshold**.

---

## 10. Validation

Attach [CollisionDebugger.cs](resources/CollisionDebugger.cs) to both objects in a suspect pair; remove after diagnosis.

| Console output | Diagnosis |
|---|---|
| Neither object logs | Issue in Steps 1-3 (Rigidbody, Layer Matrix, or interaction type) |
| One object logs, the other does not | Script placement issue -- see Section 2 Step 6 / Section 3 Step 5 |
| `[2D Collision]` fires | 2D components present on an intended 3D setup |

---

## 11. Troubleshooting & Resources

-> [references/troubleshooting.md](references/troubleshooting.md)

Referenced files: 2

View saved version →

---
name: setup-multiplayer-services
description: >-
  Guides the development of online multiplayer experiences where players connect, group, and interact in real-time using Unity Multiplayer Services.
  Use when the user asks for topology choice, player grouping, hosting, matchmaking, discovery, network setup,
  and session-based play (rooms, parties, lobbies) using the Unity Multiplayer Services APIs.
  Not for leaderboards, cloud saves, or backend features that involve no real-time connection
  between players; those belong to the build-live-game skill.
---

# 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.
- **[dgs-entrypoint.md](references/dgs-entrypoint.md)** — Dedicated server: `Unity.Services.Multiplayer.Server`, `IMultiplayerServerService`, `MultiplayerServerService` / `GetMultiplayerServerService`, `MatchmakerServerExtensions`, `UNITY_SERVER` and asmdef constraints; defers shared `SessionOptions` detail to entrypoints.
- **[workflows-prerequisites.md](references/workflows-prerequisites.md)** — Package and cloud prerequisites by workflow (tables).
- **[underlying-services.md](references/underlying-services.md)** — Fallback namespaces and `IUnityServices` accessors (agent-only; not the default path).

Referenced files: 6

View saved version →

---
name: setup-vivox-voice-chat
description: Add and configure in-game voice chat and text chat for Unity multiplayer games using Unity Vivox. Covers microphone setup and mic permissions on Android/iOS, voice activity detection (VAD) tuning, voice volume and mute controls in a settings UI (VoiceVadMinimumVolume, mic slider, mute button, speaking indicator), proximity/3D spatial voice for FPS/co-op games, team/party/lobby/guild voice channels, push-to-talk, muting self and other players, whisper/direct messages, in-game text chat, and Vivox SDK init + Unity Authentication sign-in. Use when the user asks to add voice chat, voice comms, microphone/mic support, a voice-chat settings UI, mute button, VAD threshold, push-to-talk, proximity or spatial voice, team voice, party chat, lobby chat, direct messages, or mentions Vivox, VivoxService, com.unity.services.vivox, JoinGroupChannelAsync, JoinPositionalChannelAsync, LoginAsync, or migrating from legacy Vivox (Client.Instance / LoginSession / AccountId).
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 `20502 VxXmppServerErrorServiceUnavailable`. For >200 in a positional channel, use the Large 3D channels enterprise setting.

Leave with `VivoxService.Instance.LeaveChannelAsync(channelName)` or `LeaveAllChannelsAsync()`. See [references/voice-channels.md](references/voice-channels.md) for `Channel3DProperties` fields and mic-permission handling on Android/iOS.

## Text Messaging

**Channel messages** (broadcast to all participants of a channel with `TextOnly` or `TextAndAudio`):

- Send: `VivoxService.Instance.SendChannelTextMessageAsync(string channelName, string message)`
- Receive: subscribe to `VivoxService.Instance.ChannelMessageReceived` (`Action<VivoxMessage>`)

**Directed messages** (peer-to-peer, no channel required):

- Send: `VivoxService.Instance.SendDirectTextMessageAsync(string playerId, string message)`
- Receive: subscribe to `VivoxService.Instance.DirectedMessageReceived` (`Action<VivoxMessage>`)

**Common hallucination:** the send method is `SendDirectTextMessageAsync` — **not** `SendDirectedTextMessageAsync`. The event, however, **is** `DirectedMessageReceived`. Note the asymmetry.

`VivoxMessage` fields: `ChannelName` (null for directed), `SenderDisplayName`, `SenderPlayerId`, `MessageText`, `ReceivedTime`, `Language`, `FromSelf`, `MessageId`.

Edit/delete APIs (`EditChannelTextMessageAsync`, `DeleteChannelTextMessageAsync`, `EditDirectTextMessageAsync`, `DeleteDirectTextMessageAsync`) and history (`GetChannelTextMessageHistoryAsync`, `GetDirectTextMessageHistoryAsync`) are covered in [references/text-chat.md](references/text-chat.md). Chat history retention is 7 days by default.

## Required Event Subscriptions

Subscribe to events **before** the corresponding async call. `LoggedIn` may fire immediately for reconnects; `ChannelJoined` fires as the join completes.

| Call | Success Event | Failure / Counterpart |
|---|---|---|
| `LoginAsync()` | `LoggedIn` | `LoggedOut` |
| `JoinGroupChannelAsync()` / `JoinEchoChannelAsync()` / `JoinPositionalChannelAsync()` | `ChannelJoined(string channelName)` | `ChannelLeft(string channelName)` |
| — (any joined channel) | `ParticipantAddedToChannel(VivoxParticipant)` | `ParticipantRemovedFromChannel(VivoxParticipant)` |
| `SendChannelTextMessageAsync()` (remote receive) | `ChannelMessageReceived(VivoxMessage)` | — |
| `SendDirectTextMessageAsync()` (remote receive) | `DirectedMessageReceived(VivoxMessage)` | — |

**Always unsubscribe in `OnDestroy` / `OnDisable`.** `VivoxService.Instance` is a persistent singleton — event handlers on destroyed MonoBehaviours will double-fire and NRE on scene reload.

Per-participant events (`ParticipantMuteStateChanged`, `ParticipantSpeechDetected`, `ParticipantAudioEnergyChanged`) live on the `VivoxParticipant` instance you receive from `ParticipantAddedToChannel` — not on `VivoxService.Instance`. See [references/events-and-participants.md](references/events-and-participants.md).

## Access Tokens (Brief)

The default path uses **UGS Authentication** — Vivox mints access tokens automatically from your UGS project once `AuthenticationService.Instance.SignInAnonymouslyAsync()` (or another sign-in method) has completed. **No manual token code is required** for standard flows.

Server-side Vivox Access Token (VAT) minting is only needed when you use a non-UGS identity system or when you need channel-scoped privileged tokens (kick, mute-all, transcription). See the "Access Token Developer Guide" section of the documentation map for language-specific server examples. Do not embed HMAC signing keys in the client.

## Validation

After writing code that uses this package:

1. Verify the project compiles without errors and that `using Unity.Services.Vivox;` resolves.
2. Confirm init order: `UnityServices.InitializeAsync` → `AuthenticationService.Instance.SignInAnonymouslyAsync` → `VivoxService.Instance.InitializeAsync` → `VivoxService.Instance.LoginAsync`.
3. No v4 legacy patterns: no `Client.Instance`, no `AccountId`, no `ChannelId`, no `ILoginSession`, no `IChannelSession`. All access goes through `VivoxService.Instance`.
4. All events consumed by the code are subscribed **before** the async call that triggers them, and are unsubscribed in `OnDestroy`.
5. Channel join code does not `await` the join call as if it completes join — it subscribes to `ChannelJoined` and reacts there.
6. Directed message send uses `SendDirectTextMessageAsync` (NOT `SendDirectedTextMessageAsync`). Directed message receive uses `DirectedMessageReceived`.
7. Android builds request `RECORD_AUDIO` at runtime before joining an audio channel; iOS builds have `NSMicrophoneUsageDescription` in the plist.
8. No HMAC signing keys or Vivox `SECRET`/`APP_ID` are embedded in client code — VAT-based flows are documented but delegated to a server.

Referenced files: 5

View saved version →

---
name: shader-graph-create-custom-node
description: "Generates custom Shader Graph nodes from HLSL code. Use when the user wants to create a new Shader Graph node or make existing HLSL code 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

View saved version →

---
name: sprite-editor
description: Edits Unity sprite properties by generating C# editor scripts using ISpriteEditorDataProvider APIs. Handles sprite rectangles, borders, pivots, outlines, and slicing operations (automatic, grid, isometric). Use when working with sprite assets, sprite sheets, texture atlases, 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: 12

View saved version →

---
name: sprite-segment-3x3grid
description: Analyze Sprite textures and output a 3x3 grid representation based on color matching. Segments a Sprite into a 3x3 grid, identifies the majority color of the center cell, and outputs a text pattern showing which cells match the center color. Use when analyzing sprite patterns, documenting sprite structure, or describing sprite 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`, `sprite.rect.height` for dimensions
- Divide width and height by 3 to get cell dimensions

## References

Code Template: "scripts/SpriteGridAnalysis.cs"

## Use Cases

- **Documentation**: Describe sprite patterns in a compact text format
- **Testing**: Verify expected sprite structure in automated tests
- **Analysis**: Quickly identify sprites with similar color distributions
- **Debugging**: Understand why sprites look different than expected
- **Asset Cataloging**: Generate searchable metadata for sprite assets

## Notes

- This analysis works best with sprites that have distinct color regions
- For sprites with gradients or many colors, consider increasing color tolerance
- The Y-axis is flipped from Unity's texture coordinates to produce top-to-bottom output
- Transparent pixels can be treated as a distinct "color" or ignored based on use case

Referenced files: 1

View saved version →

---
name: tilemap-palette-create
description: Creates a Tile Palette asset. Use when the user wants to organize tiles for 2D level design or create a new Tile Palette from scratch. The user can specify the Grid layout, eg. Rectangular, Hexagonal, Isometric.
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

View saved version →

---
name: tilemap-ruletile-createempty
description: Creates an empty RuleTile asset without Sprite or Spritesheet inputs. Use ONLY when the user wants a blank RuleTile, HexagonalRuleTile, or IsometricRuleTile for custom rule configuration AND has not provided or referenced any sprites. If the user mentions existing sprites, terrain art, edge tiles, or a tiles folder, use tilemap-ruletile-createfromsegment instead, never this skill.
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

View saved version →

---
name: tilemap-ruletile-createfromsegment
description: Use when the user wants tiles that auto-tile (autotile) as they paint, wants a RuleTile built from existing terrain or edge sprites, or asks to make sprites "tile correctly" or "connect properly". Also converts sprite-segment-3x3grid output patterns into Unity RuleTile TilingRules: 3x3 grid text patterns (X, ., *) become TilingRule neighbor configurations, mapping '.' to 'This' rules and 'X' to 'DontCare', sorted by specificity (more 'This' rules first). Use when creating RuleTiles from sprite analysis or defining tile neighbor rules programmatically. Sprites must be provided 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 |
|------------|---------------------------------|----------|
| 8          | `. . . / . * . / . . .`        | First    |
| 5          | `. . . / . * . / X X X`        | ...      |
| 3          | `X X X / X * X / . . .`        | ...      |
| 0          | `X X X / X * X / X X X`        | Last     |

## Sprite Assignment

Each TilingRule is assigned at most 1 Sprite:
- Set `m_Output` to `TilingRuleOutput.OutputSprite.Single`
- Assign the sprite to `m_Sprites[0]`

The RuleTile's `m_DefaultSprite` is set to the sprite from the bottom-most (least specific) rule. Since rules are sorted by specificity descending, this is the last rule in the list. This sprite is used when no TilingRule matches.

## Algorithm Summary

1. **For each Sprite**: Run `sprite-segment-3x3grid` and store the pattern
2. **Filter**: Discard patterns not in Common Tile Patterns (unless user opts out)
3. **Deduplicate**: Remove duplicate patterns (first sprite wins)
4. **Parse**: Split by ` / ` for rows, then by space for cells
5. **Extract Neighbors**: `.` -> add position with `This` (1); `X` -> skip
6. **Create TilingRule**: Populate `m_Neighbors` and `m_NeighborPositions`
7. **Assign Sprite**: Set single sprite output
8. **Sort**: Order by specificity descending
9. **Apply**: Add sorted rules to RuleTile asset
10. **Default Sprite**: Set `m_DefaultSprite` to the last (least specific) rule's sprite

## Scripts

Implementation and usage examples are in the `scripts/` folder:

| File | Description |
|------|-------------|
| [`TilemapRuleTileCreateFromSegment.cs`](scripts/TilemapRuleTileCreateFromSegment.cs) | Core implementation with `CreateRuleTileFromSprites`, `CreateTilingRuleFromPattern`, `ParsePattern`, and `ApplyRulesToTile` |
| [`RuleTileGenerator.cs`](scripts/RuleTileGenerator.cs) | Editor window example (`Tools > Generate RuleTile from Sprites`) |
| [`ManualWorkflowExample.cs`](scripts/ManualWorkflowExample.cs) | Manual two-step workflow for finer control over analysis |

### Quick Usage

```csharp
// Get sprites and create rules in one call
var rules = TilemapRuleTileCreateFromSegment.CreateRuleTileFromSprites(
    sprites, matchThreshold: 0.75f, colorTolerance: 0.04f);

// Apply to RuleTile
var ruleTile = ScriptableObject.CreateInstance<RuleTile>();
TilemapRuleTileCreateFromSegment.ApplyRulesToTile(ruleTile, rules);
```

## Common Tile Patterns

| Tile Type                                            | Pattern                          | This Count |
|------------------------------------------------------|----------------------------------|------------|
| Fully surrounded (inner tile)                        | `. . . / . * . / . . .`          | 8          |
| Top left corner missing                              | `X . . / . * . / . . .`          | 7          |
| Top right corner missing                             | `. . X / . * . / . . .`          | 7          |
| Bottom left corner missing                           | `. . . / . * . / X . .`          | 7          |
| Bottom right corner missing                          | `. . . / . * . / . . X`          | 7          |
| Top corners missing                                  | `X . X / . * . / . . .`          | 6          |
| Bottom corners missing                               | `. . . / . * . / X . X`          | 6          |
| Left corners missing                                 | `X . . / . * . / X . .`          | 6          |
| Right corners missing                                | `. . X / . * . / . . X`          | 6          |
| Top Left and Bottom Right diagonal corners missing   | `X . . / . * . / . . X`          | 6          |
| Top Right and Bottom Left diagonal corners missing   | `. . X / . * . / X . .`          | 6          |
| Top Left, Top Right and Bottom Left corners missing  | `X . X / . * . / X . .`          | 5          |
| Top Left, Top Right and Bottom Right corners missing | `X . X / . * . / . . X`          | 5          |
| Top Left, Bottom Left and Bottom Right corners missing | `X . . / . * . / X . X`        | 5          |
| Top Right, Bottom Left and Bottom Right corners missing | `. . X / . * . / X . X`       | 5          |
| Cross Section                                        | `X . X / . * . / X . X`          | 4          |
| Flat edge (Bottom)                                   | `X X X / . * . / . . .`          | 5          |
| Flat edge (Top)                                      | `. . . / . * . / X X X`          | 5          |
| Flat edge (Left)                                     | `. . X / . * X / . . X`          | 5          |
| Flat edge (Right)                                    | `X . . / X * . / X . .`          | 5          |
| L-Shape, Point Right                                 | `X X X / . * . / . . X`          | 4          |
| L-Shape, Point Bottom                                | `. . X / . * X / X . X`          | 3          |
| L-Shape, Point Left                                  | `X . . / . * . / X X X`          | 4          |
| L-Shape, Point Top                                   | `X . X / X * . / X . .`          | 3          |
| L-Shape Inverse, Point Left                          | `X X X / . * . / X . .`          | 4          |
| L-Shape Inverse, Point Bottom                        | `X . . / X * . / X . X`          | 3          |
| L-Shape Inverse, Point Right                         | `. . X / . * . / X X X`          | 4          |
| L-Shape Inverse, Point Top                           | `X . X / . * . / . . X`          | 5          |
| T-Shape, face down                                   | `X X X / . * . / X . X`          | 3          |
| T-Shape, face top                                    | `X . X / . * . / X X X`          | 3          |
| T-Shape, face left                                   | `X . X / . * X / X . X`          | 3          |
| T-Shape, face right                                  | `X . X / X * . / X . X`          | 3          |
| Horizontal bridge                                    | `X X X / . * . / X X X`          | 2          |
| Vertical bridge                                      | `X . X / X * X / X . X`          | 2          |
| Corner piece, Bottom Right                           | `X X X / X * . / X . .`          | 3          |
| Corner piece, Bottom Left                            | `X X X / . * X / . . X`          | 3          |
| Corner piece, Top Left                               | `. . X / . * X / X X X`          | 3          |
| Corner piece, Top Right                              | `X . . / X * . / X X X`          | 3          |
| Edge end, Bottom Right                               | `X X X / X * . / X . X`          | 2          |
| Edge end, Bottom Left                                | `X X X / . * X / X . X`          | 2          |
| Edge end, Top Left                                   | `X . X / . * X / X X X`          | 2          |
| Edge end, Top Right                                  | `X . X / X * . / X X X`          | 2          |
| Single isolated tile, Left                           | `X X X / . * X / X X X`          | 1          |
| Single isolated tile, Right                          | `X X X / X * . / X X X`          | 1          |
| Single isolated tile, Top                            | `X . X / X * X / X X X`          | 1          |
| Single isolated tile, Bottom                         | `X X X / X * X / X . X`          | 1          |
| Center                                               | `X X X / X * X / X X X`          | 0          |

## Notes

- Always run `sprite-segment-3x3grid` first -- this skill depends on its output
- Rules are evaluated in order; first matching rule wins
- A rule with 0 `This` conditions matches any configuration (use as fallback)
- The center cell (`*`) is always ignored in neighbor calculations
- Unity's RuleTile supports up to 8 neighbors in a standard 3x3 grid
- For hexagonal or isometric grids, use `HexagonalRuleTile` or `IsometricRuleTile`

## Prerequisites

- **`sprite-segment-3x3grid` skill**: generates the input patterns. It ships in this
  same plugin as `sprite-segment-3x3grid`, so it is always available — invoke
  it rather than treating it as an unmet dependency.
- **com.unity.2d.tilemap.extras package**: Required for RuleTile class

## See Also

- `sprite-segment-3x3grid` - required prerequisite; generates the input patterns
- `Packages/com.unity.2d.tilemap.extras/Runtime/Tiles/RuleTile/RuleTile.cs` for RuleTile implementation
- Unity Manual: [Rule Tile](https://docs.unity3d.com/Packages/com.unity.2d.tilemap.extras@latest)

Referenced files: 3

View saved version →

---
name: ui
description: Unity UI expert for menus, HUDs, screens, panels, buttons, labels, and all visual interface elements. Handles questions about UI in scenes or prefabs (how many elements, what exists, structure analysis), styling changes (colors, borders, backgrounds, fonts, spacing, rounded corners), layout adjustments, and UI generation. Routes to UI Toolkit, uGUI, or IMGUI based on project context. Use for ANY request to build, edit, or understand game UI (menus, HUDs, settings or pause screens) when no framework is named: consult this skill to detect which UI system the project uses before writing any UI code, even for a request that looks simple enough to build directly.
---

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-imgui`
- For legacy editor tools using OnGUI/immediate mode
- Only use when project has existing IMGUI editor code or user explicitly requests IMGUI
- **Understands**, **edits**, and **generates** EditorWindow, inspectors, PropertyDrawers built with OnGUI
- Not for runtime game UI — for new editor tools, use UI Toolkit unless the project already uses IMGUI exclusively

### Figma design import — not available here

Importing a Figma design requires Unity's Figma integration service, which only exists
inside Unity AI Assistant. There is no client-side equivalent, so do not promise it.

If the user brings a Figma URL, say the automated import is not available here and offer
the alternative: ask them to describe or screenshot the screen, then build it with the
appropriate framework skill above.

## Common Guidelines (All UI Systems)

### Scope Discipline

**Do only what is requested:**
- Question → answer without making changes
- Targeted edit → modify only what's specified
- Generation → create only requested files
- Don't proactively add scripts unless explicitly asked

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

### Conventions

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

| Type | Convention |
|------|------------|
| Element names | Follow project patterns, or camelCase |
| File organization | Match existing project structure |

### Workflow

1. **Determine UI system** — Use routing logic above
   - For Figma requests, tell the user the automated import is not available here, then
     work from their description or screenshot and continue with framework detection
2. **Activate specialized skill** — Route to `ui-uitk`, `ui-ugui`, or `ui-imgui`
3. **Skill handles request** — Understanding, editing, or generation as appropriate

## Handling Mixed Projects

Many Unity projects use multiple UI systems simultaneously (e.g., UI Toolkit for runtime game UI plus editor tools). When you detect multiple systems:

- **For runtime UI requests** (menus, HUDs, game screens) → Route to whichever runtime system (UITK or uGUI) is already in use
- **For editor tool requests** (custom inspectors, editor windows):
  - **Prefer UI Toolkit** (CreateGUI) for new editor UI — it's the modern approach
  - Only use IMGUI if the project's existing editor tools use IMGUI exclusively, or user explicitly requests IMGUI
  - Check for existing editor `.uxml` files to confirm UITK usage
- **If creating new runtime UI in a mixed project** → Match the pattern used by similar existing UI; if there is no similar existing UI and the user has no preference, use uGUI

View saved version →

---
name: ui-imgui
description: Unity IMGUI (Immediate Mode GUI) expert for legacy editor tools using OnGUI/immediate mode. Generates and modifies IMGUI EditorWindows, custom Inspectors, PropertyDrawers, and scripts with IMGUI code (OnGUI, OnInspectorGUI). Use when maintaining existing IMGUI editor code or when user explicitly requests IMGUI/OnGUI. Do not use for NEW editor windows or tools: new editor UI defaults to UI Toolkit (ui-uitk) unless the project already uses IMGUI exclusively or the user asks for OnGUI by name.
---

**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 SerializedProperties
serializedObject.Update/ApplyModifiedProperties → undo support
```

### PropertyDrawer
```
[CustomPropertyDrawer attribute] → targets type or attribute
OnGUI(Rect, SerializedProperty, GUIContent) → draws property
GetPropertyHeight() → custom height if needed
```

## Key Rules

- **Cache GUIStyle objects** — never create new GUIStyle in OnGUI (causes memory allocation every frame)
- **Use SerializedProperty** — for proper undo/redo support in inspectors
- **Call ApplyModifiedProperties()** — after any serialized object changes
- **Use EditorGUILayout** — for editor scripts (auto-layout)
- **Use GUILayout** — for runtime OnGUI
- **Begin/End pairs** — always match BeginHorizontal with EndHorizontal, etc.
- **Editor folder required** — scripts fail to build if not in Editor folder

## Layout Basics

**Horizontal grouping:**
```csharp
EditorGUILayout.BeginHorizontal();
// elements appear side by side
EditorGUILayout.EndHorizontal();
```

**Vertical grouping:**
```csharp
EditorGUILayout.BeginVertical("box");
// elements appear stacked, with box style
EditorGUILayout.EndVertical();
```

**Scroll view:**
```csharp
scrollPos = EditorGUILayout.BeginScrollView(scrollPos);
// scrollable content
EditorGUILayout.EndScrollView();
```

**Foldout section:**
```csharp
showSection = EditorGUILayout.Foldout(showSection, "Section Name");
if (showSection)
{
    EditorGUI.indentLevel++;
    // section content
    EditorGUI.indentLevel--;
}
```

## Common Patterns

**Button with action:**
```csharp
if (GUILayout.Button("Do Something"))
{
    // action here
}
```

**Property field with label:**
```csharp
EditorGUILayout.PropertyField(myProperty, new GUIContent("Label"));
```

**Object reference field:**
```csharp
myObject = (MyType)EditorGUILayout.ObjectField("Label", myObject, typeof(MyType), true);
```

**Disabled group:**
```csharp
EditorGUI.BeginDisabledGroup(condition);
// disabled elements
EditorGUI.EndDisabledGroup();
```

## Best Practices

- Use `SerializedObject` and `SerializedProperty` for undo support
- Cache property references in `OnEnable()`
- Use `EditorUtility.SetDirty()` only for non-serialized changes
- Use `Undo.RecordObject()` before modifying objects directly
- Use `EditorStyles` for consistent appearance
- Use `GUILayout.FlexibleSpace()` to push elements apart

See `references/templates.md` for complete script templates.
See `references/gui-elements.md` for full element reference.

Referenced files: 2

View saved version →

---
name: ui-ugui
description: Unity uGUI (Canvas-based) UI expert. Understands, edits, and generates 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` — 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 structure with proper anchoring, or make targeted edits.
6. **Confirm result** — Verify the change worked before moving on.

## Canvas Setup

Every UI needs a Canvas:

```
Canvas (Screen Space - Overlay or Camera)
├── CanvasScaler (Scale With Screen Size recommended)
├── GraphicRaycaster
└── [UI Content]
```

**CanvasScaler settings:**
- Default to UI Scale Mode "Scale With Screen Size" unless the project has a specific reason for "Constant Pixel Size" (e.g., pixel-art, fixed-resolution targets)
- Reference Resolution: Match project standards (e.g., 1920x1080)
- When creating a Canvas with Screen Space - Camera, **read the camera's reference resolution** first
- Match Width Or Height: 0.5 (balanced)
- If an existing Canvas uses "Constant Pixel Size", flag it and ask the user before changing
- Prefer anchors and Layout Groups over absolute pixel positions for layout

## Layout Components

**Layout Groups control child sizing:**
- When a parent has a Layout Group, it manages child RectTransforms
- Children's anchors and sizeDelta may be overridden by the parent
- Understand whether the parent or child controls size before setting values

**Vertical/Horizontal Layout Groups:**
- Control Child Size: determines if parent sets child dimensions
- Child Force Expand: determines if children stretch to fill space
- If Control Child Size is off, children must have explicit sizes

**Avoiding layout conflicts:**
- Do not manually set child anchors/size when parent controls them
- Do not add Layout Group to an element that should have fixed size
- Nested Layout Groups require careful configuration of each level
- When layout is wrong, check parent settings before modifying child
- ContentSizeFitter on the **same** object as a Layout Group that has Control Child Size enabled = conflict
- ContentSizeFitter on a child whose parent has Control Child Size enabled = ContentSizeFitter is overridden (wasted)
- When using ContentSizeFitter with a Layout Group parent, disable Control Child Size on the parent for the relevant axis
- Common pattern: ScrollView Content should have ContentSizeFitter + VerticalLayoutGroup where VLG controls children but ContentSizeFitter sizes the Content itself

**Grid Layout Group:**
- For inventory grids, card layouts
- Cell Size must be set explicitly — children are sized to match
- Constraint controls row/column limits

**Content Size Fitter:**
- Horizontal/Vertical Fit: Preferred Size
- Use on containers that should size to their content
- Requires a layout element or text component to provide preferred size

## RectTransform Anchoring

**Elements must have non-zero size to be visible:**
- Set explicit width/height via sizeDelta, or
- Use stretch anchors with proper offsets, or
- Let a parent Layout Group control size (with Control Child Size enabled)

**Anchor configuration order:**
1. Set anchor preset first (corner, edge, or stretch)
2. Then set position/offset values
3. Verify the resulting size is non-zero

**Common patterns:**
- **Stretch anchors** — for responsive elements that fill available space
- **Corner anchors** — for fixed-position, fixed-size elements
- **Edge anchors** — for elements that stretch in one direction only

**Positioning from natural language descriptions:**
When the user describes a position (e.g., "top right", "bottom bar", "left side"):
1. Determine if it's a **corner** (fixed point), an **edge** (stretch along one axis), or **fill** (stretch both axes)
2. Set anchor min and anchor max — for corners these are the same point; for edges/fill they span a range
3. **Set pivot to match the anchor point** — pivot must align with where the element is anchored, not left at the default (0.5, 0.5). A "top right" element needs pivot at the top-right corner; a "top bar" needs pivot at the top edge center
4. Set position/offset values **after** anchors and pivot are configured

**Visibility checklist:**
- Width and height are both greater than zero
- Element is within parent bounds
- Element is not obscured by siblings (check hierarchy order)
- Image component has a sprite or color with alpha > 0

## Common Components

| Component | Use Case |
|-----------|----------|
| `Image` | Backgrounds, icons |
| `RawImage` | Render textures, videos |
| `Text (TMP)` | All text (use TextMeshPro) |
| `Button` | Clickable elements |
| `Toggle` | Checkboxes, radio buttons |
| `Slider` | Value ranges |
| `ScrollRect` | Scrollable content |
| `InputField (TMP)` | Text input |

## Best Practices

- Use TextMeshPro for all text (not legacy Text)
- WorldSpace UI that have text should also use Text Mesh Pro, be sure to review the project and import the TMP essentials if they are not present in the project
- If the TextMeshPro Essentials were imported be sure to close the TMP Importer Windows and the Import Unity Package Window once the assets are imported
- Organize hierarchy logically (Header, Content, Footer)
- Use Layout Groups instead of manual positioning where possible
- Set Raycast Target = false on non-interactive images
- Use sprite atlases for performance

**Never use** `EditorApplication.ExecuteMenuItem("Window/TextMeshPro/Import TMP Essential Resources")`, unless the user asks for an interactive TMP Essentials installation. It opens a modal dialog that blocks whatever invoked it until a human dismisses it.

**Do not use** `AssetDatabase.ImportPackage()` for TMP resources, instead `TMP_PackageResourceImporter.ImportResources()` is the canonical non-interactive API.

## Interaction Readiness

Before completing any UI that contains interactive elements, verify:

1. **EventSystem** must exist in the scene (exactly one)
2. **GraphicRaycaster** must be on the Canvas
3. **Raycast Target = true** on interactive elements (and false on non-interactive ones to avoid blocking)
4. **Button.onClick should be wired** (via inspector or script) — only when scripts or logic were requested

If the first three are missing, interactive elements will exist visually but fail silently.

## Understanding

When the user asks questions about existing UI:

**Read the hierarchy first.** Don't assume — always inspect the scene or prefab before answering.

**Analyze structure:**
- Identify the Canvas and its render mode
- Map the parent-child relationships
- Identify which Layout Groups control which children
- Check RectTransform anchor configurations

**Answer questions about:**
- "What does this button do?" → Explain component, hierarchy position, event wiring
- "How is this laid out?" → Describe Layout Groups, anchoring, hierarchy
- "Why is this invisible?" → Check size, anchors, parent bounds, component state
- "What controls this element's size?" → Trace Layout Group settings or anchors

## Editing

For targeted changes to existing UI:

**Read before editing.** Always inspect the current state first.

**Edit workflow:**
1. Verify the target object exists
2. Identify the specific property or component to change
3. Make the minimal change required
4. Verify the result before proceeding

**Never destroy to fix:**
- Destroying objects cascades to null references elsewhere
- Fix properties in place rather than recreating
- If an element must be removed, update all references first

## C# (Only When Requested)

- Use fully qualified UI types to avoid namespace conflicts
- Use `[SerializeField]` for inspector references
- Cache component references in Awake()
- Use events/delegates for button callbacks
- Place scripts in same folder as prefabs (follow project patterns)

**Component references:**
- Verify referenced objects exist before accessing them
- Handle cases where serialized references may be null
- When wiring up references, confirm the target component is present

## Error Recovery

When something goes wrong:

**Stop and diagnose:**
- Identify the exact error or symptom
- Determine the root cause before attempting fixes
- Do not make speculative changes

**Fix incrementally:**
- Address one issue at a time
- Verify each fix before moving to the next
- Keep track of what was changed

**Avoid destructive patterns:**
- "Start fresh" strategies destroy working elements along with broken ones
- Rebuilding entire hierarchies creates more problems than it solves
- Prefer surgical fixes to wholesale replacements

**When stuck:**
- Re-verify the current state of the hierarchy
- Check if previous changes were actually applied
- Consider if the approach itself is wrong rather than the implementation

Referenced files: 1

View saved version →

---
name: ui-uitk
description: Unity UI Toolkit expert for Unity 6.0+. Understands, edits, and generates UXML and USS files with flex-based layouts. Use for requests involving .uxml, .uss, UI Toolkit, UIElements, UIDocument, UI runtime binding, Custom UI Elements, Manipulators or PanelSettings.
---

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` — USS patterns and examples
- `references/svg-icons.md` — SVG icon generation (only when generating icons)
- `references/common-issues.md` — Common mistakes to avoid
- `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` — 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` — 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` — 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.
- Watch for the mistakes that survive a parse but render wrong — those will not appear
  in the Console at all, so the user has to eyeball the UI. `references/common-issues.md`
  lists them.

## Generation

When creating new UI:

**Generate only what is requested:**

| Request | Output |
|---------|--------|
| USS only | `.uss` file only |
| UXML only | `.uxml` file only |
| UI screen / menu / panel | `.uss` + `.uxml` only |
| "with code" / "with logic" / "functional" | `.uss` + `.uxml` + `.cs` |

**These do NOT imply C#:**
- "proper buttons" → well-styled Button elements
- "currency display" → a Label element
- "working UI" → valid UXML/USS that renders
- "inventory screen" → visual layout only
- "inventory system" / "equipment system" / "crafting system" → Ask: "Should items be draggable?" If yes, see `references/pointermanipulator-guide.md` for patterns

**Generation workflow:**
1. **Analyze** — Determine exactly what files are needed. No extras.
2. **Search** — Find existing USS, UXML, assets. Don't assume paths.
3. **Follow project patterns** — Match folder structure and naming conventions.
4. **Reuse** — Check for shared stylesheets. Reuse if appropriate.
5. **Write USS first** — Verify against restrictions below.
6. **Write UXML** — Reference the USS, verify structure.
7. **Write the files out complete** — never partial content; see Validation above for
   how errors come back and why one round of files beats several.
8. **Scene setup** — Assign PanelSettings if adding UI to scene.
9. **Data binding** — If requested, add C# script with runtime data binding patterns (see `references/ui-runtime-binding.md`). Generate the scriptable object asset if needed. Assign the asset to the UI element root in UXML or via datasource in C#.

**Color, visibility, and specification rules:**
- **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). When using design tokens, check that text and background variables provide adequate contrast.
- **Honor exact values:** User-specified hex colors, pixel dimensions, spacing — use exactly as given. Do not approximate or substitute.

**Styling / Theme**
When styling UI or adjusting theme make sure to not only apply to the elements directly in the current UXML but also to the core elements of UI Toolkit which are composed of several child elements usually.

## Conventions

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

| Type | Convention | Good | Bad |
|------|------------|------|-----|
| `name` attribute | camelCase | `submitButton` | `submit-button` |
| `class` attribute / USS | kebab-case | `.submit-button` | `.submitButton` |
| File paths | Feature folders | `Assets/UI/Inventory/` | `Assets/Scripts/UI/` |

**Output format:**
```uxml Filename.uxml
<ui:UXML>...</ui:UXML>
```
```uss Filename.uss
.class { ... }
```

## USS Restrictions

Unity's USS is a subset of CSS. These properties do NOT exist — NEVER use them:

| NEVER Use | Use Instead |
|-----------|-------------|
| `border` shorthand | `border-width`, `border-color` separately |
| `gap` | `margin` on children |
| `z-index` | DOM order or parent nesting |
| `pointer-events` | `picking-mode` UXML attribute |
| `filter` | Not supported |
| `outline` | `border-*` properties |
| `box-shadow` | Nested elements or background image |
| `:first-child`, `:last-child`, `:nth-child` | Explicit classes |
| `[attribute]` selectors | Explicit classes |
| `transition-property: <value>` | Omit entirely, or `none`/`initial`/`inherit` only |
| `linear-gradient()`, `radial-gradient()` | Custom `VisualElement` with Painter2D (see `references/painter2d.md`) |

**Inline styles:** NEVER use `style="..."` in UXML. All styling in USS only.

**External URLs:** NEVER use `url()` with external paths. Only `url("project://database/Assets/...")`.

**Prefer flexible layouts over hardcoded sizes:**
- Use `flex-grow`, `flex-shrink`, or `%` instead of fixed `width`/`height` values
- Let elements flow naturally and be constrained by their parent container
- Set explicit pixel sizes only on root containers or when a fixed size is truly required
- Child elements should adapt to available space rather than define their own dimensions

## USS Brevity

- No default values (`flex-direction: column` is default)
- No default fonts
- No redundant constraints (`width: 100px` doesn't need `min-width`/`max-width`)
- No overlapping properties (`flex: 1` already sets grow/shrink)
- Simplest selector that works
- Never duplicate selectors

## UXML

Every file must:
1. Declare namespace: `<ui:UXML xmlns:ui="UnityEngine.UIElements">`
2. Link stylesheet(s): `<ui:Style src="Screen.uss" />`
3. Have exactly one top-level container
4. **No `style="..."` attributes** — use USS only

```uxml
<ui:UXML xmlns:ui="UnityEngine.UIElements">
  <ui:Style src="Panel.uss" />
  <ui:VisualElement name="root" class="panel">
    <!-- content -->
  </ui:VisualElement>
</ui:UXML>
```

## Events and Interactivity
- Use Pointer Manipulators for event handling and interactivity on a VisualElement (see `references/pointermanipulator-guide.md`)
- If drag and drop is requested then write a pointer Manipulator and attach it to the relevant Visual Element in UXML or via C#.
- For simple click events, you can use the `clickable` manipulator in UXML
- For more advanced interactions, create use more traditional event callbacks in C# and attach them to elements as needed

**For inventory and crafting systems:**
- When users request an "inventory system", "equipment system", or "crafting system", ask explicitly: "Should players be able to drag and drop items?"
- If yes, read `references/pointermanipulator-guide.md` for inventory/crafting-specific patterns
- If no or unclear, create static layout only

## Assets

**Do NOT reference `UnityDefaultRuntimeTheme.tss`** or Unity's built-in theme icons.

**Icon priority:**
1. Reuse existing project icons
2. Generate SVG (see `references/svg-icons.md`)
3. Image generators (last resort)

**Reference format:**
```uss
background-image: url("project://database/Assets/UI/Textures/icon.png");
```

## Scene Setup

**PanelSettings is required** — UI won't render without it.

1. Search for existing PanelSettings asset
2. If none, create generic: `Assets/UI/PanelSettings.asset`
3. Assign to UIDocument's `Panel Settings` field

Skip for Editor UI (EditorWindow, PropertyDrawer).

## C# (Only When Requested)

- Style via USS classes (`AddToClassList()`) — never use `element.style.*` as inline styles have higher specificity than USS selectors, making them impossible to override via stylesheets, and add per-element memory overhead
- UITK uses TextCore text assets — use `FontAsset`, `TextStyleSheet`, and `TextSettings`, not their TextMeshPro equivalents (`TMP_FontAsset`, etc.)
- Place scripts in same folder as UXML/USS

Referenced files: 7

View saved version →

---
name: unity-cli
description: Use when interacting with Unity CLI from the terminal, or to control a running/connected Unity Editor from the command line — create or modify GameObjects, edit scenes and assets, inspect the hierarchy, and run C# in a live Editor instead of hand-editing scene or asset files. Also install, upgrade or uninstall editors, create, list or open projects, manage modules, manage licenses, check auth status, read logs, browse Unity releases, build/test projects, configure the Unity MCP server for AI agents, or run any other Unity CLI operation. For a guided idea-to-running-project flow for a brand-new game, use the new-unity-project skill instead.
allowed-tools:
  - Bash
---

# Unity CLI

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

### 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`, and `unity list` can't connect at all. Don't fall back to blind file-editing: run `unity pipeline list` to confirm, then fix the compile errors and restart Unity. Full recovery loop in [integration-advanced.md → Recovering from Safe Mode](references/integration-advanced.md#recovering-from-safe-mode-connection-fails-because-of-compile-errors).

> **Running as a sandboxed coding agent and `unity status` reports no instances?** A restrictive sandbox can hide an Editor that is genuinely running from this CLI's view of it — don't treat that alone as proof the Editor is down. Full detail in [integration-advanced.md → Sandboxed agent tooling can hide a running Editor](references/integration-advanced.md#sandboxed-agent-tooling-can-hide-a-running-editor).

## Install the CLI (if not already installed)

First check if the CLI is available:

```bash
which unity && unity --version
```

If not found, install it:

**macOS / Linux**
```bash
curl -fsSL https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.sh | UNITY_CLI_CHANNEL=beta bash
```

**Windows (PowerShell)**
```powershell
$env:UNITY_CLI_CHANNEL='beta'; irm https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.ps1 | iex
```

After installing, open a new shell so `unity` is on PATH, then verify with `unity --version`. If the install script fails or the binary is still not found, tell the user and stop; if the command itself fails with a permissions error or crash, the installation may be broken — suggest re-running the install script.

---

## Global flags

These work on every command:

| Flag | Description |
|---|---|
| `--format <fmt>` | Output format: `human` (default), `json`, `tsv`, `ndjson`, `github`. Also via `UNITY_FORMAT` env var. |
| `--json` | Global shorthand for `--format json`, accepted on every command (e.g. `unity status --json`, `unity doctor --json`). `--format` takes precedence when both are supplied. |
| `--no-banner` | Suppress the branded header — use in scripts |
| `--no-pager` | Turn off paging. Governs both pagers: the external one over the long listings (`unity command`, `releases`, `editors`, `changelog`, `logs`) and the interactive one in `unity projects list`. Also via `UNITY_NO_PAGER` (presence-based — any value, including `0`, disables it). |
| `--non-interactive` | Disable all interactive prompts — use in CI |
| `--quiet` | Suppress non-essential output |
| `--verbose` | Print full error details (stack trace + cause chain) on failure. Also via `UNITY_VERBOSE`. |
| `--proxy <url>` | HTTP/HTTPS/SOCKS/PAC proxy URL for this invocation. Also via `UNITY_PROXY`. Takes precedence over standard `HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY` env vars and the persisted `proxy.json` setting. |
| `--proxy-disable` | Disable proxy for this invocation, ignoring all sources (env vars, persisted config, system settings). |
| `--log-proxy` | Log one redacted entry per outbound request to `proxy-request.json` — for reproducing proxy issues. Also via `UNITY_LOG_PROXY=1` or the `proxyRequestLogging` setting. |
| `--no-log-proxy` | Opt a single invocation out of proxy request logging when it's enabled globally. |
| `--color <auto\|always\|never>` | Control colored output for this invocation, overriding `NO_COLOR`/`FORCE_COLOR` and TTY auto-detection. Governs every ANSI-emitting surface (help, tables, spinners, errors), not just `human` output. |
| `--no-color` | Shorthand for `--color never`. Whichever of `--color`/`--no-color` appears last on the line wins. |

**Always use `--format json` when you need to parse output programmatically.**

**`unity projects list` is the only command that pages IN-PROCESS.** It shows 10 projects per screen and waits for a keypress between screens, and only when stdout is a terminal. Paging is off for redirected stdout, under `--format json` and `--format ndjson`, and under `--all`, `--watch`, or `--no-pager` / `UNITY_NO_PAGER`.

**Not every machine format bypasses that one.** Only `json` and `ndjson` get their own non-interactive rendering; on a terminal, `--format tsv` and `--format github` fall through to the human table and page like `human` does — so `--format tsv` on a TTY yields neither TSV nor unpaged output. Redirect stdout (the usual case for a machine format) or pass `--no-pager`. Note this is the **opposite** of the external pager below, which is `human`-only: the two mechanisms differ here, and `projects list` is the surprising one.

**The long listings page through an external pager, like `git log`.** `unity command` (the bare listing), `unity releases`, `unity editors`, `unity changelog`, and `unity logs` pipe human output through `less -RFX` on a terminal — colors kept, no screen clear, and `-F` quits by itself when the output already fits one screen, so short listings show no pager UI. `$UNITY_PAGER` then `$PAGER` override the choice and run through a shell, so `PAGER="less -S"` works; a blank value is ignored rather than treated as an opt-out. Quitting with `q` exits cleanly with the command's own exit code. Unlike `projects list`'s pager this one is **`human`-only**, and it never engages for redirected stdout, any machine format (`json`, `tsv`, `ndjson`, `github`), `--quiet`, `TERM=dumb`, the streaming modes (`editors --watch`, `logs --follow`), a named `unity command <name>`, or inside `unity shell`. A broken pager costs the paging, not the output: a `$PAGER` naming something that is not there is resolved before anything spawns, and one that spawns and then dies has its output reprinted to the terminal, decided from the pager's exit status (a clean exit is a normal `q` and discards; a failure status reprints). The exception is a pager that exits *successfully* without reading — `PAGER=true`, or anything that lingers and then exits 0 — which nothing distinguishes from a `q`, and which `git` loses too. A pager that starts and merely *waits* is not treated as broken, so the CLI waits with it.

A branded Unity header (logo, wordmark, CLI version) renders on the landing surfaces — bare `unity`, `unity --help` / `-h`, `unity help`, and above the first-run consent prompt. It's shown only on a TTY, prints at most once, and degrades to compact, uncolored text on narrow terminals, without Unicode, or under `NO_COLOR`. Piped output is unaffected. Use `--no-banner` to suppress it in scripts. Bare `unity` prints usage and exits 0.

## Environment variables

All CLI env vars use the `UNITY_` prefix. A CLI flag always overrides the corresponding env var.

| Variable | Mirrors flag | Description |
|---|---|---|
| `UNITY_FORMAT` | `--format` | Output format (`human`, `json`, `tsv`, `ndjson`, `github`). `HUB_FORMAT` is a deprecated alias. |
| `UNITY_EDITOR_VERSION` | `--editor-version` | Editor version (e.g. `2023.3.0f1`, `latest`, `lts`). |
| `UNITY_ARCHITECTURE` | `--architecture` | Chip architecture (`x86_64`, `arm64`). |
| `UNITY_PROJECT_PATH` | path argument | Project path — used by `open`, and also honored by `status` and the cloud commands. |
| `UNITY_QUIET` | `--quiet` | Suppress non-essential output. |
| `UNITY_VERBOSE` | `--verbose` | Show full error details on failure. |
| `UNITY_NON_INTERACTIVE` | `--non-interactive` | Disable interactive prompts. |
| `UNITY_NO_BANNER` | `--no-banner` | Suppress the branded banner. |
| `UNITY_NO_PAGER` | `--no-pager` | Turn off paging — both the external pager over the long listings and `unity projects list`'s interactive one. Presence-based: any value counts, including `0`. |
| `UNITY_PAGER` | — | The pager to use for the long listings, overriding `$PAGER` and the `less -RFX` default. Runs through a shell, so flags work (`less -S`). A blank value is ignored, not an opt-out. |
| `PAGER` | — | Same as `UNITY_PAGER`, consulted only when that is unset or blank. |
| `LESS` / `LV` / `LESSCHARSET` / `MORE` | — | Passed to the pager only when you have not set them, defaulting to `FRX`, `-c`, `utf-8`, and `FRX`. `LESSCHARSET` keeps multi-byte glyphs readable where the locale does not declare UTF-8; `MORE` exists because `more` on macOS/BSD is `less` under another name and reads `$MORE`, so without it `PAGER=more` waits for a keypress even for one line. |
| `UNITY_RUN_TIMEOUT` | `--timeout` | Timeout for `unity run` in seconds. |
| `UNITY_TEST_TIMEOUT` | `--timeout` | Timeout for `unity test` in seconds. |
| `UNITY_CLOUD_ORG` | `--cloud-org` | Active Unity Cloud organization id or name for a single call. |
| `UNITY_SERVICE_ACCOUNT_ID` | — | Service account client ID for non-interactive (CI) auth. |
| `UNITY_SERVICE_ACCOUNT_SECRET` | — | Service account client secret for non-interactive (CI) auth. |
| `UNITY_PROXY` | `--proxy` | HTTP/HTTPS/SOCKS/PAC proxy URL. Takes precedence over `HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY` and the persisted `proxy.json` setting. |
| `UNITY_NO_UPDATE_CHECK` | — | Disable the background "update available" check (see `unity config update-check`). |
| `UNITY_NO_CONSENT_PROMPT` | — | Suppress the one-time first-run analytics consent prompt *without* recording a choice — for wrapper scripts on an interactive terminal that must never absorb the prompt. Analytics stay off until you run `unity analytics opt-in`. Unlike `UNITY_NON_INTERACTIVE`, it changes nothing else about command behavior. |
| `UNITY_NO_CRASH_REPORT` | — | Disable anonymous crash/error reporting (Sentry) entirely. |
| `UNITY_LOG_PROXY` | `--log-proxy` | Log one redacted entry per outbound request to `proxy-request.json`. Truthy values: `1`, `true`. |
| `UNITY_NO_ELEVATE` | `--no-elevate` | Windows: skip the elevated (UAC) install helper for `install` / `install-modules`, so the install service runs unelevated. The Editor's NSIS installer still asks for elevation on demand if Windows requires it for your account — an administrator token always does; a standard user never does. |
| `UNITY_INSTALL_RETRIES` | `--retries` | Number of times `install-modules` retries a module whose download/validation fails. `0` disables retries. |

**CI service account auth:** Set both `UNITY_SERVICE_ACCOUNT_ID` and `UNITY_SERVICE_ACCOUNT_SECRET` to skip the browser OAuth flow — this keeps the secret out of the process argument list and shell history. These map to the `--client-id` / `--secret-from-stdin` inputs of `unity auth login`, but reading the credentials from the environment isn't a full login: it doesn't run the interactive flow or persist credentials to the keyring.

## Getting help

Append `-h` or `--help` to any command or subcommand, at any level: `unity --help`, `unity projects create --help`.

## Exit codes

| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Bad arguments |
| 3 | Authentication failure |
| 4 | Precondition not met (e.g. no license active, floating server not configured) |
| 6 | Command-specific failure |
| 8 | `unity test` only — the tests ran and one or more **failed**. Every other way a test run fails (compile error, unavailable license, editor crash, `--timeout`) keeps `6`, so CI can retry an infrastructure failure and never retry a failing test. |
| 130 | Interrupted — Ctrl+C / SIGINT (128 + 2) |
| 143 | Terminated by SIGTERM (128 + 15) — e.g. `kill` or a CI/runner timeout. Emitted by long-running commands that install a signal handler to clean up first (currently `unity build`, which scrubs the temporary Android keystore). |

The `cloud` and `auth` commands map an authentication failure (expired/missing session, rejected sign-in) to `3`, and any other operational failure (network, server error) to `6` — so scripts can reliably tell "sign in again" apart from a genuine command failure.

---

## Commands

The full per-command reference — syntax, flags, and examples — lives in grouped files under
[`references/`](references/). **Read the file for the command group you need**; all the global
flags, environment variables, and exit codes above apply throughout. Every command also supports
`-h` / `--help` (see [Getting help](#getting-help)).

| Commands | Reference file |
|---|---|
| `auth` (login / logout / status / list / switch / default / consumers / revoke), `license` (activate / return / server), `cloud` (org / project) | [auth-license-cloud.md](references/auth-license-cloud.md) |
| `editors` (list / running / add / default / path / install-path / info / upgrade / prune / verify / module), `install`, `uninstall`, `modules`, `install-modules` | [editors-install.md](references/editors-install.md) |
| `projects` (list / create / new / clone / open / link / require / upgrade / export / import / pin / size / clean / exec), `releases`, `templates` (list / info / create / pack / delete) | [projects-templates.md](references/projects-templates.md) |
| `config` (proxy / update-check / get / set / list / unset), `hub install` | [config-hub.md](references/config-hub.md) |
| `run`, `test`, `build` | [build-run-test.md](references/build-run-test.md) |
| `logs`, `doctor`, `env`, `version`, `cache`, `ci init`, `analytics`, `changelog`, `language`, `completion`, `bug`, `self-update`, `self-uninstall`, `diagnose proxy` | [diagnostics-maintenance.md](references/diagnostics-maintenance.md) |
| `mcp` (+ `configure`), `skill` (install / refresh / show), `plugin` (install / remove / upgrade / list / changelog), connected editors (`pipeline` / `command` / `status` / `list`), `shell` | [integration-advanced.md](references/integration-advanced.md) |
| `vcs` — `setup` / `status` / `sync` / `switch` / `doctor` / `providers` / `merge-setup` / `conflicts` / `explain` / `resolve` / `diff` / `blame` / `summarize` / `affected` / `hooks`, `vcs git` (`migrate-lfs` / `worktree`), `vcs uvcs` (`locks` / `changesets` / `review`) | [version-control.md](references/version-control.md) |
| `collaboration` (alias `collab`) — `annotations` / `attachments` / `thumbnail` / `reactions` / `read` / `subscribe` / `jira` | [collaboration.md](references/collaboration.md) |

## Common workflows

### Edit a scene, GameObject, or asset — `unity status` first

**Before editing any scene, GameObject, prefab, or asset, run `unity status` to detect a connected Editor.** If one is reachable, drive it with live commands instead of touching project files — the Editor applies changes to the *actual active scene* and keeps its in-memory state in sync.

```bash
unity status                       # is an Editor connected? (look for state "ready")
unity command                      # discover the scene/GameObject commands THIS Editor exposes
# then drive it with the commands it lists — for example, if your Editor exposes them:
unity command create_gameobject    # act on the live, active scene
unity command save_scene           # persist the active scene
```

Command names are defined by the Editor, so run `unity command` (or `unity list`) to see the exact set — don't assume a name.

> **Never hand-edit `.unity`, `.prefab`, or `.asset` YAML while a live Editor is reachable.** Raw-file edits are:
> - **error-prone** — fileIDs and GUIDs are assigned by hand and easy to get wrong;
> - **invisible** to the running Editor until a reimport, so the change silently fails to take effect; and
> - **prone to hitting the wrong file** — e.g. writing to `SampleScene.unity` while the Editor's active scene is actually `Demo2.unity`, producing valid-looking YAML that changes nothing the user sees.

**Rule out two false negatives before concluding no Editor is reachable — both look identical to a genuinely closed Editor, and both are easy to get wrong under time pressure:**

- **Safe Mode.** If an Editor *is* running for this project but `unity status` / `unity command` won't connect, it may be stuck in **Safe Mode** from a compile error rather than genuinely absent. Run `unity pipeline list` — if it reports Safe Mode, editing the C# source to fix the compile errors (and then restarting Unity) *is* the correct move, not a fallback. See [integration-advanced.md → Recovering from Safe Mode](references/integration-advanced.md#recovering-from-safe-mode-connection-fails-because-of-compile-errors).
- **A sandboxed agent shell.** If your own shell commands run inside a restrictive sandbox — the normal case for a coding agent like this one — the sandbox can hide a genuinely running Editor from `unity status` the same way. This applies to **every** scene/GameObject/prefab/asset task that reaches this preflight, not only ones that obviously need a live Editor: a task you could otherwise finish without any CLI involvement (e.g. generating an asset through ordinary Editor APIs) can still get funneled into "no Editor" here and derailed. Don't treat "no instances" as proof the Editor is down, and don't quietly improvise a third path — like driving a separate headless Editor process to approximate what a live connection would have done — as a substitute for a disclosed file edit. Say plainly that your sandbox may be blocking your view of a real Editor, and ask whether one is actually open before falling back. Full detail: [integration-advanced.md → Sandboxed agent tooling can hide a running Editor](references/integration-advanced.md#sandboxed-agent-tooling-can-hide-a-running-editor).

Only fall back to editing files directly once you've ruled out both of the above — and say so explicitly ("no live Editor detected, editing the file directly").

### Bootstrap a new project from scratch

> For a **guided** end-to-end experience — concept questions, installing the Editor in the
> background while you plan, package selection, and monetization handoff — use the
> **`new-unity-project`** skill. This section is the raw CLI recipe that skill builds on; use it
> directly when you just want the commands.

Take an idea to a running, version-controlled project using only the CLI. Decide the **target
platforms first** — they determine which Editor modules you install in step 2. You can add
modules later (`unity install-modules`), but a project can't build for a platform until that
platform's module is installed, so it's simplest to decide up front.

```bash
# 1. Confirm the CLI works and you're signed in and licensed (see references/auth-license-cloud.md).
unity --version
unity auth status --format json      # if signed out:      unity auth login
unity license status --format json   # if none active:      unity license activate

# 2. Pick and install an Editor with the modules your target platforms need.
#    Default to the latest LTS (most stable, ~2 years of patches). Reach for a Tech-stream
#    release (--stream tech) only for a feature not yet in LTS; treat --stream beta/alpha as
#    evaluation-only, never for a project you intend to ship. A deadline argues for LTS.
#    (lts / latest aliases work wherever a version is accepted.)
unity releases --stream lts --limit 5 --format json
unity install lts --module android --module ios --yes --accept-eula   # add --module webgl, etc.
unity editors --installed --format json                               # confirm it landed

# 3. List the real template ids this Editor offers — don't guess them.
unity templates list --editor lts --format json
#    Common ids: com.unity.template.3d, com.unity.template.2d, and a URP template (id varies by version).

# 4. Create the project. The first positional arg is the NAME; --path sets the parent directory.
#    All options supplied, so it won't prompt; add --non-interactive in CI.
unity projects create "MyGame" --path ~/UnityProjects \
  --editor-version lts --template com.unity.template.3d
```

**Source control — let the user choose.** The CLI publishes the new project to a fresh remote in
one step for any provider. **Always pass tokens on stdin** (`--git-token-stdin`) so secrets never
land in shell history or the process list. Pick based on the project — don't default to one:

- **Git — GitHub / GitLab** (`--vcs github` / `--vcs gitlab`). Ubiquitous. For asset-heavy games
  add **Git LFS** (`--git-lfs`) so large binaries don't bloat history.
- **Unity Version Control — UVCS** (`--vcs uvcs`). Unity's own VCS, built for large binary game
  assets: it handles them natively (**no LFS needed**) and supports file locking — often the
  better fit for art-heavy projects or larger teams. Auth uses your Unity sign-in; `--vcs-region`
  selects the region.

```bash
# Git (GitHub) — drop --git-lfs if the game isn't asset-heavy. Add --no-initial-commit if you
# want to add packages/assets BEFORE the first commit (see the new-unity-project flow).
unity projects create "MyGame" --path ~/UnityProjects \
  --editor-version lts --template com.unity.template.3d \
  --vcs github --git-namespace my-org --git-repo my-game \
  --git-visibility private --git-default-branch main --git-token-stdin --git-lfs

# Unity Version Control (UVCS) — handles binaries natively, so no LFS:
unity projects create "MyGame" --path ~/UnityProjects \
  --editor-version lts --template com.unity.template.3d \
  --vcs uvcs --git-namespace my-org --git-repo my-game --vcs-region <region>
```

Feed the token to `--git-token-stdin` from a secret store, never a literal — e.g.
`… --git-token-stdin <<<"$GIT_TOKEN"` where `$GIT_TOKEN` comes from your CI/secret manager
(UVCS uses your Unity sign-in, so no token is needed).

**Working with a UVCS workspace day to day: a few wrapped reads, everything else straight through
to `cm`.** The split is deliberate and worth teaching, because guessing wrong wastes a user's time:

- **`unity vcs uvcs <verb>`** wraps the reads that **join `cm`'s data to your project** —
  `locks` (who holds a lock, *and which locks cover files you have already changed*),
  `changesets`, and `review`. Those joins are the thing `cm` cannot do for you, and they come in a
  stable envelope, so prefer them whenever something *parses* the output.
- **`unity uvcs <args>`** forwards the whole command line to `cm` verbatim, `--help` and
  `--format` included. That is the supported route, not a workaround: `cm` owns and versions this
  vocabulary, so wrapping it would pin a paraphrase that goes stale. Reach for it for **partial
  checkout**, **shelves**, and **taking or releasing a lock**, and when a human reads the output.

```bash
unity vcs uvcs locks                       # who holds what, and what collides with your changes
unity uvcs lock list                       # the raw listing, cm's own flags and output
unity uvcs partial update /Assets/Levels   # cm's own vocabulary, unchanged
unity uvcs shelve -c "wip: lighting pass"
```

Every verb, flag and trap: [version-control.md](references/version-control.md).

`unity cm <args>` is the same passthrough under cm's own name. Both need the `cm` client; install
it with `unity plugin install plastic` if a command says it is missing.

**Beyond setup, the `vcs` group covers the whole day-2 loop** — `status`, `sync`, `switch`,
`merge-setup`, `conflicts` / `explain` / `resolve`, `diff`, `blame`, `summarize`, `affected`,
`hooks`, `doctor`, `providers` — and the Unity semantics are the reason to reach for it over raw
`git`. Full reference, with the flags and the traps:
[version-control.md](references/version-control.md).

**Git tokens belong to the user's credential manager, not the CLI.** When no token flag or env var
is given, the CLI asks `git credential fill` and uses whatever the configured helper returns; it
stores nothing it is passed or told. Don't suggest the CLI can save a Git token, and don't reach for
a token flag when the user already has a working credential helper. If they want a different token
per organization, that is `git config --global credential.useHttpPath true` plus a multi-account
helper such as [Git Credential Manager](https://github.com/git-ecosystem/git-credential-manager).
The CLI passes the full repo URL so the helper can discriminate, but it never installs or
reconfigures a helper. `UNITY_GITHUB_TOKEN` / `UNITY_GITLAB_TOKEN` are one token per provider, so a
CI job spanning several orgs should pass `--git-token-stdin` per invocation instead. See
[references/projects-templates.md](references/projects-templates.md) for the full
source-control flag set. For a purely local Git repository instead, initialize git with a
Unity-appropriate ignore so the multi-GB `Library/` and other generated folders are never committed:

```bash
cd ~/UnityProjects/MyGame
git init -b main
# Download (do not pipe to a shell) a maintained Unity .gitignore:
curl -fsSL https://raw.githubusercontent.com/github/gitignore/main/Unity.gitignore -o .gitignore

# Asset-heavy game? Keep large binaries out of git history with Git LFS:
git lfs install
git lfs track "*.psd" "*.fbx" "*.wav" "*.mp3" "*.png"   # adjust to your asset types
git add .gitattributes

git add -A
git status                             # sanity-check: Library/ Temp/ obj/ Build/ must NOT be staged
git commit -m "Initial Unity project: MyGame"
git ls-files | grep -c '^Library/'     # must print 0
```

**What the CLI does and doesn't cover.** The CLI handles editor, project, and source control.
It does **not** manage UPM (Unity Package Manager) packages — to add packages beyond the
template headlessly, use the **`unity-package-management`** skill (C# PackageManager Client
API). For monetization/backend, hand off to the dedicated skills: `implement-in-app-purchases`
(IAP), `levelplay-unity-integration` (ads), or `build-live-game` (accounts, cloud save,
economy, remote config, leaderboards). Open the project to start working:
`unity open ~/UnityProjects/MyGame`.

### Find and install a missing editor

```bash
# 1. Check what's installed
unity editors --installed --format json

# 2. Browse available LTS versions
unity releases --lts --limit 5 --format json

# 3. Install
unity install 6000.0.47f1 --yes --accept-eula
```

### Open a project with the correct editor

```bash
# 1. Check the project's required editor version
unity projects info /path/to/MyProject --format json
# Look at "editorVersion" in the result

# 2. Confirm that editor is installed
unity editors --installed --format json

# 3. Open (warns if the editor version is missing)
unity open /path/to/MyProject
```

### CI: activate a license, then build

```bash
# 1. Sign in non-interactively with a service account
unity auth login --client-id "$UNITY_SERVICE_ACCOUNT_ID" --secret-from-stdin <<<"$UNITY_SERVICE_ACCOUNT_SECRET"

# 2. Activate the entitlement license (or use --serial / --floating)
unity license activate

# 3. Build
unity build /path/to/MyProject \
  --editor-version 6000.0.47f1 \
  --target StandaloneLinux64 \
  --execute-method Builder.PerformBuild \
  --allow-install
echo "Exit code: $?"

# 4. Return the seat when done (floating/assigned)
unity license return --yes
```

### CI: headless build

Prefer the dedicated `unity build` command (handles batch mode, logging, and CI flags):

```bash
unity build /path/to/MyProject \
  --editor-version 6000.0.47f1 \
  --target StandaloneLinux64 \
  --execute-method Builder.PerformBuild \
  --allow-install
echo "Exit code: $?"
```

Or use `unity run` (batch mode is automatic — never pass `-batchmode`/`-quit`):

```bash
unity run /path/to/MyProject \
  --editor-version 6000.0.47f1 \
  --allow-install \
  -- -executeMethod Builder.PerformBuild -logFile build.log
echo "Exit code: $?"
```

### CI: run tests and publish results

```bash
unity test /path/to/MyProject \
  --editor-version 6000.0.47f1 \
  --mode EditMode \
  --report-format junit \
  --output ./test-results.xml \
  --allow-install \
  --timeout 600
case $? in
  0) echo "All tests passed" ;;
  8) echo "Tests failed — report to developers, do not retry" ;;
  *) echo "Run did not complete — infrastructure failure, safe to retry" ;;
esac
```

Exit `8` means the run finished and reported failing tests; any other non-zero code means it never produced a verdict. Under `--format json` the same split is `errors[0].code`: `TESTS_FAILED` versus `TEST_RUN_ERROR` / `TEST_TIMED_OUT`.

`--report-format junit` makes `--output` a JUnit-schema report, which GitHub Actions and GitLab ingest as native test results with no converter step. It is written even when tests fail. Drop the flag for the NUnit3 default, or use `--report-format nunit,junit` to get both from one run. Add `--coverage` to collect coverage via the Unity Code Coverage package — it warns and carries on if the project doesn't have the package. See [build-run-test.md](references/build-run-test.md).

### Debug the CLI

```bash
# Check auth + installed editors + recent errors in one command
unity doctor --format json

# Follow live logs during an install
unity logs --follow --level info
```

---

## Notes

- `--non-interactive` and `--yes` together suppress all prompts — use both in CI.
- `--format json` always produces machine-readable output; prefer it over parsing human text. Error envelopes are pretty-printed with the same 2-space indent as success envelopes.
- **Read failures from stdout, not stderr.** A failed command still writes a complete document to stdout: under `--format json` an envelope with `success: false` and a populated `errors` array (`errors[0].code` is the stable token to branch on); under `--format ndjson` the usual terminal `{"type":"result","success":false,…}` frame. **Branch on `success`, never on `data`** — `data` is usually `null` on a failure, but not always: a partial `unity editors add` failure carries a row per path, and an ambiguous `unity auth switch` carries `data.candidates` for you to disambiguate with. Check `success` and the exit code — never treat empty stdout as a failure signal, and do not parse stderr, which carries only human diagnostics in these formats. A handful of commands have not migrated yet and still print `{"error": "…"}` to stderr with empty stdout; if stdout is empty on a non-zero exit, that is a known bug in that command rather than a shape you should code against.
- `unity <version> [path]` is a shorthand for `unity open [path] --editor-version <version>`. Works with `lts`, `latest`, or a full version string like `6000.0.47f1`.
- The CLI supports kubectl-style plugins: any `unity-<name>` binary on PATH is callable as `unity <name>`.
- Terminal output is hardened against control-character / escape-sequence injection from server-provided values (project titles, editor versions, module names) — C0 controls and non-SGR escape sequences are stripped from table/list/tree output, and now also from Commander usage errors, the `unity bug` log-archive warning, and `unity projects add`/`remove` machine (tsv) output, while SGR color/style codes are preserved.
- The CLI reports anonymous crashes and errors via Sentry to help fix bugs (no IP address or hostname; home-directory paths and token-like values scrubbed before send), aligned with the Unity Hub. Opting in to analytics additionally attaches an anonymized machine id; opted-out users stay fully anonymous. Set `UNITY_NO_CRASH_REPORT` to disable reporting entirely. Separately again, every run sends one anonymous `cli telemetry` usage ping regardless of analytics/consent state — see [diagnostics-maintenance.md](references/diagnostics-maintenance.md#analytics--usagetelemetry-consent).
- The CLI is currently in **beta** (latest: `1.0.0-beta.9`). It moved to 1.0 versioning at `1.0.0-beta.1`; it's still a beta, so keep `UNITY_CLI_CHANNEL=beta` in the install command until GA ships, after which that part can be dropped.
- As of `0.1.0-beta.8` the CLI checks in the background for a newer version and prints an unobtrusive "update available" notice (interactive sessions only; never delays a command). Turn it off with `unity config update-check off` or the `UNITY_NO_UPDATE_CHECK` env var.
- Outbound HTTP from every CLI command honors the resolved proxy (see `unity config proxy`). An invalid `--proxy` value (malformed URL or unsupported scheme) fails with a usage error (exit 2) instead of being silently ignored. Inspect what the CLI actually resolved with `unity env --format json` or `unity doctor --format json` — both surface the active proxy URL, its source, and auth source.

Referenced files: 11

View saved version →

---
name: unity-package-management
description: Use when adding, removing, upgrading, or discovering Unity (UPM) packages programmatically from outside the Editor — headless or CI package installs via the C# UnityEditor.PackageManager.Client API, verifying package ids/versions against the Unity registry, or choosing which packages a game needs by genre, platform, and monetization. The Unity CLI does not manage UPM packages, so this skill covers that gap. Triggers on "install a Unity package", "add com.unity.*", "set up packages headless/CI", "which packages for a [genre] game".
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 _request;
        static double _deadline;

        // Invoke with: -executeMethod ProjectBootstrap.PackageInstaller.Install  (NO -quit)
        public static void Install()
        {
            if (PackagesToAdd.Length == 0 && PackagesToRemove.Length == 0)
            {
                Debug.Log("[PackageInstaller] Nothing to do.");
                EditorApplication.Exit(0);
                return;
            }

            Debug.Log($"[PackageInstaller] Adding: {string.Join(", ", PackagesToAdd)}");
            _request = Client.AddAndRemove(packagesToAdd: PackagesToAdd, packagesToRemove: PackagesToRemove);
            _deadline = EditorApplication.timeSinceStartup + TimeoutSeconds;
            EditorApplication.update += Poll;
        }

        static void Poll()
        {
            if (_request == null) return;

            if (!_request.IsCompleted)
            {
                if (EditorApplication.timeSinceStartup > _deadline)
                {
                    EditorApplication.update -= Poll;
                    Debug.LogError("[PackageInstaller] Timed out waiting for UPM.");
                    EditorApplication.Exit(2);
                }
                return;
            }

            EditorApplication.update -= Poll;

            if (_request.Status == StatusCode.Success)
            {
                var names = _request.Result.Select(p => $"{p.name}@{p.version}");
                Debug.Log($"[PackageInstaller] Resolved: {string.Join(", ", names)}");
                EditorApplication.Exit(0);
            }
            else
            {
                Debug.LogError($"[PackageInstaller] Failed: {_request.Error?.message}");
                EditorApplication.Exit(1);
            }
        }
    }
}
```

`AddAndRemove` installs the whole set in a single UPM resolution pass — faster and less
error-prone than one `Client.Add` per package.

**Add / remove / upgrade with one script:**
- **Add**: list the id in `PackagesToAdd`.
- **Remove**: list the id in `PackagesToRemove`.
- **Upgrade / pin**: add the id with `@<version>` (e.g. `com.unity.cinemachine@2.9.7`). Without
  a version, resolution picks the latest compatible release.

## Discovering / verifying packages

To confirm an id exists or list its versions before adding it, search the registry. The
in-Editor `Client.SearchAll()` / `Client.Search("<id>")` calls are also async, so they use the
**same poll-and-`Exit` pattern and the same headless run** as the installer. Write
`Assets/Editor/ProjectBootstrap/PackageSearch.cs`:

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

namespace ProjectBootstrap
{
    public static class PackageSearch
    {
        const double TimeoutSeconds = 120;
        static SearchRequest _request;
        static double _deadline;

        // Invoke with: -executeMethod ProjectBootstrap.PackageSearch.SearchAll  (NO -quit)
        public static void SearchAll()
        {
            _request = Client.SearchAll();                 // or Client.Search("com.unity.cinemachine")
            _deadline = EditorApplication.timeSinceStartup + TimeoutSeconds;
            EditorApplication.update += Poll;
        }

        static void Poll()
        {
            if (_request == null) return;
            if (!_request.IsCompleted)
            {
                if (EditorApplication.timeSinceStartup > _deadline)
                {
                    EditorApplication.update -= Poll;
                    Debug.LogError("[PackageSearch] Timed out.");
                    EditorApplication.Exit(2);
                }
                return;
            }
            EditorApplication.update -= Poll;

            if (_request.Status == StatusCode.Success)
            {
                foreach (var p in _request.Result.OrderBy(p => p.name))
                    Debug.Log($"[PackageSearch] {p.name}@{p.versions.latestCompatible}  {p.displayName}");
                Debug.Log($"[PackageSearch] {_request.Result.Length} packages found.");
                EditorApplication.Exit(0);
            }
            else
            {
                Debug.LogError($"[PackageSearch] Failed: {_request.Error?.message}");
                EditorApplication.Exit(1);
            }
        }
    }
}
```

`_request.Result` is a `PackageInfo[]`; each entry exposes `name`, `displayName`, `description`,
and `versions` (`.latest`, `.latestCompatible`, `.all`). For a terminal-only check without the
Editor (a **known** id, not free-text search), query the registry directly — see
[references/select-packages.md](references/select-packages.md#discovering-and-verifying-packages).

## Run it headless (direct Editor invocation, no `-quit`)

Resolve the Editor binary from the version, then run it in batch mode. The script owns quitting
via `EditorApplication.Exit`, so do **not** pass `-quit`:

```bash
VERSION="<version>"          # e.g. 6000.0.47f1 (or an installed version)
PROJECT="<project-path>"
METHOD="ProjectBootstrap.PackageInstaller.Install"   # or ...PackageSearch.SearchAll

# Install directory of that editor (Hub layout), via the unity CLI
ED=$(unity editors path "$VERSION" --format json | python3 -c "import sys,json;print(json.load(sys.stdin)['data']['path'])")

# Resolve the executable per-OS (handles both "dir containing Unity.app" and the ".app" itself)
case "$(uname)" in
  Darwin) if [ -d "$ED/Unity.app" ]; then UNITY_BIN="$ED/Unity.app/Contents/MacOS/Unity";
          elif [[ "$ED" == *.app ]]; then UNITY_BIN="$ED/Contents/MacOS/Unity";
          else UNITY_BIN="$ED/Unity"; fi ;;
  Linux)  UNITY_BIN="$ED/Editor/Unity" ;;
  *)      UNITY_BIN="$ED/Editor/Unity.exe" ;;   # Windows (Git Bash / MSYS); use Editor\Unity.exe in PowerShell
esac

"$UNITY_BIN" -batchmode -projectPath "$PROJECT" -executeMethod "$METHOD" -logFile -
echo "Exit code: $?"   # 0 = success, 1 = UPM error, 2 = timeout
```

`-logFile -` streams the Editor log (including the `[PackageInstaller]` / `[PackageSearch]`
lines) to stdout so you can watch resolution progress and read any UPM error. If
`unity editors path` output shape differs on your build, get the directory from
`unity editors --installed --format json` instead.

## Verify

```bash
# Every requested id should appear as a dependency
cat "<project-path>/Packages/manifest.json"
```

Confirm the run exited `0` and each package from the list is present in `manifest.json`. If a
package fails to resolve, `_request.Error.message` is logged; read it and check the id/version
against the registry. The Editor's own log (including the `[PackageInstaller]` lines) is the
stdout you streamed with `-logFile -` above — read it there, not via `unity logs` (which shows
the CLI's own log, not the Editor's).

## Import & save headlessly (generate `.meta` files)

After a script or tool writes new `.cs`/asset files, Unity must **import** them so it generates
the `.meta` file each asset needs — and every `.cs`/asset MUST be committed together with its
`.meta`. Merely opening the project once (`unity open "<project-path>"`) imports and generates
them; use this method when you need it **headless** (in a script or CI).

Unlike the package installer, this is **synchronous** — it finishes before returning — so it's
safe to run via `unity run` (its injected `-quit` is harmless; the method also calls
`EditorApplication.Exit` for a clean exit code). Write
`Assets/Editor/ProjectBootstrap/ProjectSaver.cs`:

```csharp
using UnityEditor;
using UnityEngine;

namespace ProjectBootstrap
{
    public static class ProjectSaver
    {
        // Invoke with: -executeMethod ProjectBootstrap.ProjectSaver.SaveAll
        public static void SaveAll()
        {
            AssetDatabase.Refresh(ImportAssetOptions.ForceUpdate);
            AssetDatabase.SaveAssets();
            Debug.Log("[ProjectSaver] Assets imported and saved.");
            EditorApplication.Exit(0);
        }
    }
}
```

```bash
unity run "<project-path>" --editor-version <version> \
  -- -executeMethod ProjectBootstrap.ProjectSaver.SaveAll
```

## Notes

- These editor scripts are a bootstrap convenience. Leave them in
  `Assets/Editor/ProjectBootstrap/` (they do nothing unless invoked) or delete them after
  setup — your call; mention it to the user.
- All scripts live under `Editor/` because they use `UnityEditor`; they never ship in a build.
- Monetization / backend packages (`com.unity.purchasing`, `com.unity.services.levelplay`, the
  UGS packages) install through this same mechanism, but do the actual **integration** via the
  dedicated skills: **implement-in-app-purchases**, **levelplay-unity-integration**,
  **build-live-game**.

Referenced files: 1

View saved version →

---
name: urp-postprocessing
description: Sets up, configures, and debugs URP post-processing effects using the Volume framework. Use when the user asks about bloom, tonemapping, color adjustments, depth of field, vignette, motion blur, or other Volume overrides in a URP project.
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)
    report.AppendLine("Warning: HDR is disabled on the URP Asset. Tonemapping won't work; Bloom requires threshold < 1.");

// 3. Check camera post-processing
var cam = UnityEngine.Camera.main;
if (cam == null)
    throw new System.Exception("No Main Camera found.");
if (!cam.TryGetComponent<UnityEngine.Rendering.Universal.UniversalAdditionalCameraData>(out var camData))
    throw new System.Exception("Missing UniversalAdditionalCameraData on camera. Is URP active?");
if (!camData.renderPostProcessing)
    report.AppendLine("Warning: Post-processing is disabled on the camera. Enable via camData.renderPostProcessing = true.");

// 4. Check volume layer mask
var volumes = UnityEngine.Object.FindObjectsByType<UnityEngine.Rendering.Volume>(UnityEngine.FindObjectsSortMode.None);
foreach (var vol in volumes)
{
    if (!vol.enabled) { report.AppendLine($"Warning: Volume '{vol.name}' is disabled."); continue; }
    if ((camData.volumeLayerMask & (1 << vol.gameObject.layer)) == 0)
        report.AppendLine($"Warning: Volume '{vol.name}' on layer {vol.gameObject.layer} is not in camera's volumeLayerMask.");
    // 5. Check profile and overrides
    var profile = vol.sharedProfile;
    if (profile == null) { report.AppendLine($"Warning: Volume '{vol.name}' has no profile assigned."); continue; }
    if (profile.components.Count == 0)
        report.AppendLine($"Warning: Volume '{vol.name}' profile has no overrides.");
}

// Return the findings: logs land in the Editor console, the returned value comes back to you
return report.Length == 0 ? "Post-processing setup looks correct." : report.ToString();
```

## 1. Volume Setup

Effects are added as **VolumeComponent overrides** on a **VolumeProfile** (a `ScriptableObject`).

**Global Volume** (most common): GameObject with `Volume` component, `isGlobal = true`, `profile` assigned. Affects every camera whose `volumeLayerMask` includes the Volume's layer.

**Local Volume (optional, but takes precedence)**: GameObject with trigger `Collider` + `Volume` component, `isGlobal = false`. Properties:
- `priority` (float) — higher values override lower when volumes overlap.
- `blendDistance` (float) — outer distance in world units to start blending from (0 = no blend, instant transition at collider boundary).
- `weight` (float, 0–1) — scales the volume's overall influence.

## 2. Post-Processing Effects

All effects are `VolumeComponent` subclasses added as overrides on a `VolumeProfile` via `profile.Add<T>()`. Check existence with `profile.Has<T>()` or `profile.TryGet<T>(out var t)`. Remove with `profile.Remove<T>()`.

Every property is a `VolumeParameter`. You **must** set `overrideState = true` before setting `value`, otherwise the Volume system ignores it.

When configuring a specific effect, load the full API reference:
- [references/effect-reference.md](references/effect-reference.md) — All VolumeComponent properties by effect (Bloom, Tonemapping, ColorAdjustments, DepthOfField, Vignette, MotionBlur, FilmGrain, ChromaticAberration, SplitToning, LensDistortion, WhiteBalance, PaniniProjection, LiftGammaGain, ShadowsMidtonesHighlights, ColorCurves, ChannelMixer)

For code templates:
- [references/code-templates.md](references/code-templates.md) — Global Volume setup, camera post-processing, and profile modification templates

## 3. Anti-Hallucination Rules

### Required Usings

These apply when you write a `.cs` file into the project. **A snippet passed to `eval` cannot
carry them** — qualify the types instead (see "Passing C# to `eval`" above).

```csharp
using UnityEngine.Rendering;           // Volume, VolumeProfile, VolumeComponent, VolumeParameter
using UnityEngine.Rendering.Universal;  // Bloom, Tonemapping, ColorAdjustments, UniversalRenderPipeline, etc.
```

### Wrong → Correct API Mapping

| WRONG | CORRECT |
|-------|---------|
| `PostProcessVolume` | `Volume` (from `UnityEngine.Rendering`) |
| `PostProcessLayer` | `UniversalAdditionalCameraData.renderPostProcessing` (bool) |
| `UnityEngine.Rendering.PostProcessing` | `UnityEngine.Rendering.Universal` |
| `profile.GetSetting<T>()` | `profile.TryGet<T>(out var t)` (returns bool) |
| `profile.AddSettings<T>()` | `profile.Add<T>()` (returns T; throws if already exists — check `profile.Has<T>()` first) |
| `volume.sharedProfile` (to modify at runtime) | `volume.profile` (auto-clones the asset into an instance) |
| `VolumeManager.instance.stack.GetComponent<T>()` | `volume.profile.TryGet<T>(out var t)` |

### Key Facts
- **`overrideState = true`** is required on every `VolumeParameter` you set. The volume system skips parameters where `overrideState` is `false`. This is the #1 scripting mistake.
- **`sharedProfile`** = returns the asset directly (edits persist to disk). **`profile`** = auto-clones into an instance if needed (safe for runtime edits). Check with `volume.HasInstantiatedProfile()`.
- **`profile.Add<T>(bool overrides = false)`** — pass `true` to auto-enable `overrideState` on all parameters of the added component.

## 4. Debugging Checklist

When post-processing isn't working, check in order:

1. `cam.TryGetComponent<UniversalAdditionalCameraData>(out var data)` succeeds and `data.renderPostProcessing` is `true`?
2. Volume exists in scene with a non-null `profile` (or `sharedProfile`) assigned?
3. Overrides added via `profile.Add<T>()` AND `overrideState = true` on each property you set?
4. Volume's `GameObject.layer` is included in camera's `data.volumeLayerMask`? (Default mask is layer 0 "Default" only.)
5. `volume.isGlobal = true` (for global), or camera is inside the Volume's trigger `Collider` (for local)?
6. Camera `data.renderType` is `CameraRenderType.Base`, not `Overlay`? (Overlay cameras composite onto the Base camera's output.)
7. `UniversalRenderPipeline.asset.supportsHDR` is `true`? Required for Bloom and Tonemapping.
8. Viewing in **Game view**? Scene view has a separate post-processing toggle in its toolbar.

## 5. Common Recipes

Format: Effect property=value. Bloom values are threshold/intensity/scatter.

**Cinematic (Film):** Tonemapping mode=ACES, ColorAdjustments contrast=15 saturation=-10, Bloom threshold=0.9 intensity=0.5 scatter=0.7, Vignette intensity=0.3 smoothness=0.4, FilmGrain type=Medium1 intensity=0.2

**Stylized/Vibrant:** Tonemapping mode=Neutral, ColorAdjustments saturation=20 contrast=10, Bloom threshold=0.8 intensity=1.5 scatter=0.6, SplitToning highlights=warm shadows=cool

**Horror/Dark:** ColorAdjustments postExposure=-0.5 saturation=-30 contrast=20, Vignette intensity=0.5 smoothness=0.3 color=dark-red, FilmGrain type=Large01 intensity=0.4, ChromaticAberration intensity=0.15

**Clean/Mobile:** Tonemapping mode=Neutral, ColorAdjustments postExposure=0.2, Bloom threshold=1.0 intensity=0.3 (subtle). Avoid FilmGrain, MotionBlur, DepthOfField on mobile.

## 6. Final Confirmation

After setup, report to user:

```
Post-Processing Setup Complete
- Volume: [Global/Local] on "[GameObject Name]"
- Profile: [Asset Path]
- Effects: [List with key property=value pairs]
- Camera: [Name] — renderPostProcessing=true, volumeLayerMask includes layer [N]

View results in Game view (not Scene view).
Undo all changes with Edit > Undo (Ctrl+Z).
```

Referenced files: 2

View saved version →

---
name: validate-urp-render-graph-renderer-feature
description: Use when the user wants to review or validate a Unity 6+ URP ScriptableRendererFeature that uses the Render Graph API. Checks for correctness issues - resource wiring, material binding, execution structure, descriptor usage, global resource exposure, and Render Graph best practices.
---
# 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 intended as an input/read resource is instead used as a write target without justification
- a destination/write target is confused with a sampled input
- auxiliary textures are used without being clearly sourced or wired
- a required texture resource is missing from the pass setup
- read/write resource roles are ambiguous or inconsistent

### 3. Execution Structure / Static Render Function
Check that:
- the render function is declared as `static`
- the execution structure matches the target pass type and API style
- pass data is wired correctly into execution
- resources are accessed in the correct stage
- execution logic is consistent with the intended render pass behavior
- every `PassData` field used by the render function is explicitly assigned during pass setup for the current recording
- the implementation does not rely on default values or previously assigned `PassData` state
- resource handles stored in `PassData` are assigned fresh for the current frame/pass recording and are not left dangling from prior usage

Flag as an issue when:
- the render function is not `static`
- the implementation uses an instance method where the API pattern expects a static render function
- pass data or required resources are accessed through instance state instead of the pass data/context provided to the static function
- execution flow does not match the expected render graph or pass execution pattern
- a `PassData` field is read in the render function but is not clearly assigned during pass setup
- only some `PassData` fields are reassigned while others may retain stale values from previous pooled usage
- a resource handle stored in `PassData` may survive from a previous frame or pass due to incomplete reassignment
- the implementation risks using a dangling or stale handle because pass data is not fully initialized each time it is recorded

Prefer:
- explicitly assigning every `PassData` field used by the pass during each `RecordRenderGraph(...)` call
- treating `PassData` as transient per-recording data, not persistent state
- avoiding partial initialization of pooled pass data objects

### 4. Render Graph Descriptor Validation
Check that:
- the implementation does **not** create a new `TextureDesc` by default when an appropriate graph-derived descriptor can be used directly
- when a texture should match the active render target, the descriptor is sourced from the relevant render graph resource first, such as:
  - `resourceData.activeColorTexture.GetDescriptor(renderGraph)`
  - or another appropriate existing graph-backed resource
- only the fields that actually need to differ are modified after sourcing the descriptor
- descriptor fields such as name, depth bits, format, and MSAA are intentionally preserved or intentionally overridden
- any manual reconstruction of descriptor data is justified by a specific requirement

Flag as an issue when:
- the code creates a fresh `TextureDesc` without first attempting to reuse a graph-derived descriptor
- width and height are manually copied into a new descriptor structure by default
- `cameraTargetDescriptor` is used as the primary source when a render-graph-derived descriptor is available and more accurate
- important properties such as MSAA, graphics format, or compatibility with the active render target are dropped accidentally
- descriptor reconstruction is used as a convenience shortcut rather than a necessary divergence from the source resource

Preferred rule:
- **Do not create a new `TextureDesc` unless a graph-derived descriptor cannot be used directly or the texture must intentionally diverge from the source resource.**

Preferred pattern:
1. get the descriptor from the relevant render graph resource
2. modify only the fields that must change
3. create the texture from that derived descriptor whenever possible

Examples:

#### Preferred
```csharp
RenderTextureDescriptor desc = resourceData.activeColorTexture.GetDescriptor(renderGraph);
desc.depthBufferBits = 0;
desc.name = "New name";
// other desired paramters
passData.targetTexture = renderGraph.CreateTexture(desc);
```

### 5. Manual Copy Pass Simplification
Check that:
- simple texture copy operations are not implemented as full custom raster passes when a built-in Render Graph helper is sufficient
- passes that only read one texture and write it unchanged to another target are simplified where appropriate
- the implementation prefers the most appropriate built-in helper for the target API/platform context
- `AddCopyPass(...)` is not recommended by default if a more compatible `AddBlitPass(...)` overload should be preferred in the current environment

Flag as an issue when:
- a raster pass exists only to copy one texture into another
- the pass uses no material and no custom processing
- the render function only performs a simple blit/copy equivalent
- the implementation uses a full custom raster pass where a built-in copy/blit helper would express the same behavior more directly

Prefer:
- the appropriate `AddBlitPass(...)` overload for straightforward copy-like operations when that is the recommended and more compatible path
- `AddCopyPass(...)` only when it is explicitly appropriate and supported for the target API/platform context
- a custom raster pass only when the copy requires additional logic or non-trivial behavior

### 6. Manual Blit Pass Simplification
Check that:
- straightforward fullscreen material blits are not implemented as custom raster passes when `renderGraph.AddBlitPass(...)` would express the same behavior more directly
- custom raster passes are only used for blits when additional logic or non-trivial behavior is actually required
- simple source-to-destination material blits use the most direct render graph helper available

Flag as an issue when:
- a raster pass reads one source texture and writes one destination texture
- the pass uses a material but no additional custom pass logic
- the render function only performs a simple fullscreen blit
- `renderGraph.AddBlitPass(...)` would provide an equivalent result more clearly

Prefer:
- `renderGraph.AddBlitPass(...)` for straightforward fullscreen material blits
- a custom raster pass only when extra logic, multiple operations, conditional behavior, or special setup is actually required

### 7. Global Resource Exposure
Check that:
- textures and buffers are not exposed globally unless explicitly requested or clearly required by a downstream consumer
- when global exposure is required in a render graph pass, the implementation uses the appropriate render graph publication mechanism
- direct command buffer global state mutation is not used as a substitute for render graph resource publication
- global exposure is not extending resource lifetime unnecessarily or reducing aliasing opportunities without justification

Flag as an issue when:
- `SetGlobalTextureAfterPass` is used without a clear consumer
- `context.cmd.SetGlobalTexture(...)` is used inside a render graph pass where render graph resource publication is the appropriate mechanism
- global exposure is used as a convenience shortcut instead of explicit pass-to-pass wiring
- hidden coupling is introduced unnecessarily
- a globally exposed texture may be kept alive longer than necessary due to downstream `UseGlobalTexture(...)` or `UseAllGlobalTextures()` usage, increasing memory pressure or reducing aliasing opportunities

Prefer:
- no global exposure by default
- explicit resource wiring where possible
- `builder.SetGlobalTextureAfterPass(...)` only when global publication is truly required in render graph
- resource lifetimes that remain as local and short-lived as possible

### 8. Renderer Feature Input Declaration
Check that:
- the `ScriptableRendererFeature` and its associated pass declare required pipeline inputs using `ConfigureInput(...)` when needed
- the requested input flags match the feature’s intended behavior and visible resource usage
- the pass does not rely on pipeline-provided inputs without declaring them when required by the target API pattern
- unnecessary input requests are not declared by default, especially when they may introduce extra copies, intermediate resources, or avoidable pipeline work

Flag as an issue when:
- the feature’s pass uses or is clearly intended to use a pipeline-provided input but does not declare it with `ConfigureInput(...)`
- `ConfigureInput(...)` requests inputs that the feature/pass does not appear to use
- the declared input flags do not match the intended effect behavior
- the effect description, code, and declared inputs imply conflicting requirements
- unnecessary declared inputs may force extra copies, extra pass work, or other avoidable performance costs

Classification guidance:
- mark as a **confirmed issue** when the code clearly shows a required input is used but not declared
- mark as a **likely issue** when the intended effect implies a required input but the visible code does not fully prove shader/resource usage
- treat unnecessary input declarations as higher severity when they are likely to introduce additional copies or other measurable runtime cost

## Guardrails
The skill must:
- avoid inventing unsupported APIs
- distinguish **confirmed** issues from **likely** issues
- prefer minimal targeted fixes over broad rewrites
- explain why each issue matters
- flag hidden coupling and unnecessary global state
- state when the provided code is insufficient for full certainty

## Non-Goals
- guarantee runtime correctness
- rewrite the entire renderer feature unless necessary
- validate unrelated gameplay logic
- validate shader internals unless directly relevant to pass wiring or binding

## Evaluation Criteria
A successful validation should:
- catch real wiring and API issues
- identify suspicious but plausible mistakes
- provide actionable fixes
- avoid false certainty
- improve trust in generated render pass code

## Notes for Future Expansion
As new recurring issues are discovered, extend this checklist with additional rules such as:
- pass ordering / injection point validation
- resource lifetime and cleanup checks
- read/write hazard detection
- unnecessary copies or allocations
- camera depth/color dependency validation
- multi-pass dependency validation
- override material correctness
- pass configuration