/manage-sprite-atlas

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

Unity SpriteAtlas V2

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

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

🚨 CRITICAL: Required Checks and User Inputs Before Implementation

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

Read the shipped resources before writing code (REQUIRED)

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

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

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

0. Check for Existing Scripts (REQUIRED FIRST STEP)

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

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

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

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

**Then present options:**

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

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

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

**User Choice Handling:**

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

1. Delivery Mechanism (REQUIRED)

Ask: "How do you want to deliver the 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