⚠️ Critical V2 Principle:

SpriteAtlas

is runtime-only.

SpriteAtlasAsset

is editor-only. Never mix contexts. Always use V2.

// [UNITY-SKILL:SPRITEATLAS]

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

• 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

• 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

• 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

• 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

🚨 IMPORTANT: This workflow is shown for reference only. ALWAYS implement this inside

IPreprocessBuildWithReport.OnPreprocessBuild()

rather than in manual scripts. See Quick Start.

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

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

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

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

OnPreprocessBuild

GenerateAtlasByFolder("Assets/Art/UI", "Assets/Atlases/UI.spriteatlasv2")

GenerateAtlasByNaming("Assets/Art", "icon_", "Assets/Atlases/Icons.spriteatlasv2")

• Atlases are included in build
• Ready for immediate use at runtime

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

• 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

⚠️ 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.

• Hand-optimized sprite layouts where exact positioning matters
• Custom sprite ordering requirements
• Editor preview during authoring workflow
• Explicitly requested by user

• 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

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

• Addressables Delivery: references/addressables-delivery.md - Complete late-binding setup with Addressables
• Manual Authoring: references/manual-authoring.md - Manual patterns (NOT default - use only when explicitly requested)
• Common Errors: references/common-errors.md - Invalid patterns and API corrections
• API Reference: references/api.md - Complete V2 class documentation
• Custom Packing: references/custom-packing.md -

  ScriptablePacker

  implementation
• Best Practices: references/best-practices.md - Optimization and common pitfalls