manage-sprite-atlas

Unity SpriteAtlas V2

Unity プロジェクトでアトラスをスクリプトから扱うための、エディターで安全に使える手続き型の知識を提供します。V2 では、エディターでの作成とランタイムでのアクセスを厳密に分離します。

⚠ V2 の重要な原則：SpriteAtlas はランタイム専用です。SpriteAtlasAsset はエディター専用です。コンテキストを混在させないでください。常に V2 を使用してください。

🚨 重要：実装前に必要な確認とユーザーへの質問

コードを生成する前に、必ず次の確認を行い、質問してください。

コードを書く前に、同梱されているリソースを読む（必須）

このスキルには、resources/ に動作する C# コードが含まれています。アトラスのコードで問題が起きる原因のほとんどは、最初にこれらを読まずに書いたことです。選択する方法に対応するファイルを開いてから、コードを書いてください。

この方法を選択する場合	先に読むファイル
アトラス関連の作業全般	resources/authoringvsruntime.cs、references/common-errors.md
事前ビルド生成（デフォルト）	resources/spriteatlasprebuildgenerator.cs、resources/enablespritepacking.cs、resources/savespriteatlasasset.cs
オプション B、Addressables の遅延バインディング	resources/buildaddressablespostprocess.cs、resources/spriteatlaslatebinding.cs、resources/handlelatebinding.cs
古い API を使用する可能性がある場合	resources/deprecatedmethods.cs、resources/dontscriptspriteatlasineditor.cs、resources/dontpackinruntimebuilds.cs

resources/ には全 38 ファイルがあり、カスタムパッカー、バリアント、プラットフォーム設定、ランタイムアクセスを網羅しています。表にない作業の場合は、独自の方法を考案するのではなく、ディレクトリを確認してください。これらを読まず、記憶だけを頼りに API を使うことが、アトラスが問題なくインポートされるのにランタイムでは何も起きない、最もよくある原因です。

0. 既存のスクリプトを確認する（最初に必ず実施）

コードを生成する前に、プロジェクト内にこのスキルで生成された既存の SpriteAtlas スクリプトがないか、必ず検索してください。

次の識別子を含むファイルを検索してください：// [UNITY-SKILL:SPRITEATLAS]

既存のスクリプトが見つかった場合は、必ず次の形式でユーザーに質問してください。

"プロジェクト内に既存の SpriteAtlas スクリプトが見つかりました：

事前ビルドジェネレーター：

• Assets/Editor/SpriteAtlas/SpriteAtlasPrebuildGenerator.cs

Addressables ビルダー：

• Assets/Editor/SpriteAtlas/BuildAddressablesPostprocess.cs

ランタイムローダー：

• Assets/Scripts/SpriteAtlas/SpriteAtlasLateBinding.cs

どのようにしますか？"

次に、以下のオプションを提示してください。

• オプション A：既存のスクリプトを更新する（要件が変わった場合に推奨）

  • 既存のパスにスクリプトを再生成します
  • ファイルの配置場所を維持します
  • 最新バージョンに更新します
  • ⚠ カスタム変更が上書きされる場合があります

• オプション B：別の名前で新しいスクリプトを作成する

  • 既存のスクリプトと並べて生成します
  • 複数のアトラス設定に対応できます
  • 元のスクリプトは変更されません
  • 新しい名前とパスを指定する必要があります

• オプション C：中止する（既存のスクリプトは変更しない）

  • コードは生成されません
  • プロジェクトに変更は加えられません
  • 現在の設定を維持する場合に選択してください

ユーザーの選択に応じた処理：

• A を選択した場合：既存のパスに再生成し、バージョンを 2.0.1 以降に更新します
• B を選択した場合：新しいスクリプト名（例：SpriteAtlasPrebuild_Custom.cs）を尋ねてから生成します
• C を選択した場合：直ちに停止し、変更を加えていないことをユーザーに伝えます

1. 配信方法（必須）

「スプライトアトラスをどのように配信しますか？」

オプション A：ビルドに内包（即時読み込み）

• アトラスをビルドに含め、すぐに読み込みます
• includeInBuild = true に設定します
• 適している用途：コア UI、メインゲームプレイのスプライト、常に必要なアセット
• メリット：シンプルで、追加のパッケージが不要、すぐに利用できます
• デメリット：初期ビルドのサイズが増加し、新しいビルドなしでは更新できません

オプション B：Addressables による遅延バインディング（オンデマンド読み込み）

• アトラスをビルドに含めず、Addressables 経由でオンデマンドに読み込みます
• includeInBuild = false に設定します
• 各アトラスの Addressables エントリーを作成します
• ビルド前の手順として Addressables を設定します
• 🚨 必須：ビルド手順で Addressables コンテンツをビルドします
• 🚨 必須：遅延バインディング用のランタイムローダースクリプトを作成します
• 適している用途：DLC コンテンツ、オプション機能、大容量アセット、ダウンロードコンテンツ
• メリット：初期ビルドが小さく、個別に更新でき、オンデマンドで読み込めます
• デメリット：Addressables パッケージが必要で、非同期読み込みとネットワーク接続が必要です

ユースケース	推奨
常に表示されるコア UI スプライト	オプション A：ビルドに内包
チュートリアルまたはオンボーディングのスプライト	オプション A：ビルドに内包
レベル固有のスプライト（100 以上のレベル）	オプション B：Addressables
DLC または季節限定コンテンツ	オプション B：Addressables
ローカライズされた UI スプライト（複数言語）	オプション B：Addressables
キャラクタースキンまたはコスメティックアイテム	オプション B：Addressables

2. SpritePacker モード（必須）

アトラスを作成する前に Sprite Packer モードを有効にし、設定を読み戻して反映されたことを確認してください。 resources/enablespritepacking.cs のコードを使用してください。このコードは EditorSettings.spritePackerMode を設定し、インポーターのパッキング設定を構成します。

この手順によって、生成するアトラスが実際に機能するかどうかが決まります。Disabled は SpritePackerMode のゼロ値です。そのため、誰も設定していないプロジェクトではパッキングが Disabled になっており、この状態で作成したアトラスはインポートされ、アセットとして表示され、完成しているように見えても、決してパッキングされません。Unity のインスペクターには、"Sprite Atlas packing is disabled" と表示されます。このほかのワークフローはすべて問題なく進むため、この状態のアトラスを出荷すると、成功したように見えてしまいます。プロジェクトの設定が済んでいると決めつけず、値を読み取ってください。

そのため、「設定した」だけで完了とみなさないでください。設定後に EditorSettings.spritePackerMode を読み戻し、Disabled ではないことを確認して、実際に読み取った値を報告してください。値を読み戻せない場合は、書き込みが反映されたと決めつけず、その旨を伝えてください。

メタファイルを直接編集しないでください。

🚨 重要：デフォルトの方法はビルド前の生成です

ビルドパイプライン中に SpriteAtlas を自動生成または更新するには、必ず IPreprocessBuildWithReport を使用してください。 ユーザーが手動作成を明示的に求めている場合を除き、これがデフォルトかつ必須の方法です。

❌ 手動メニュー項目スクリプトを作成しないでください

明示的に求められていない限り、アトラス生成用に [MenuItem] 属性を持つスクリプトを作成しないでください。 ビルド前の方法を使えば、手動でクリックする必要はありません。手動作成を使用するのは、以下の場合に限ります：手作業で最適化したレイアウト、特定のスプライト配置、またはエディターでのプレビューが必要な場合。高度な設定：手動作成を参照してください。

🚨 重要：スプライトの配置場所に関する制限

プロジェクトの Assets フォルダーにあるスプライトのみを追加してください。Unity 組み込みアセット、パッケージ、外部の場所にあるスプライトは決して追加しないでください。 Unity 組み込みアセットは SpriteAtlas にパッキングできず、パッケージ内のアセットはインポートや依存関係の問題を引き起こす可能性があります。

重要な V2 アーキテクチャ

コンテキスト	コンポーネント	目的	使用可能な範囲
エディターでの作成	SpriteAtlasAsset	スプライト／フォルダーを追加・削除し、メタデータを保存します	✅ エディタースクリプトのみ
エディター設定	SpriteAtlasImporter	テクスチャ、パッキング、プラットフォーム設定を構成します	✅ エディタースクリプトのみ
エディターでのパッキング	SpriteAtlasUtility.PackAtlases()	任意のエディターでのプレビュー用パッキング（ビルド用ではありません）	⚠ プレビュー専用。アトラスはビルド時に自動でパッキングされます
ランタイム	SpriteAtlas	パッキング済みスプライトを照会します（読み取り専用）	✅ ランタイムスクリプトのみ
ランタイム読み込み	SpriteAtlasManager	動的読み込みのコールバックを処理します	✅ ランタイムスクリプトのみ

コンテキストをまたぐ使用の禁止（よくあるエラーの原因）

❌ 無効なパターン	✅ 正しいパターン
エディターコードで new SpriteAtlas() を使う	SpriteAtlasAsset + SpriteAtlasImporter を使用します
エディターで AssetDatabase.LoadAssetAtPath<SpriteAtlas>(...) を使う	SpriteAtlasAsset.Load(...) を使用します
エディターで SpriteAtlasAsset.GetPackables() を使う	SpriteAtlas.GetPackables() を使用します
エディタースクリプトで SpriteAtlas を変更する	SpriteAtlasAsset を変更 → 再インポート → SpriteAtlasImporter を使用します
元のパッキング対象オブジェクト（スプライト／フォルダー）からバリアントを作成する	Master ランタイム SpriteAtlas からバリアントを作成します

エディターコードで SpriteAtlas を対象にしたスクリプトを作成してはいけません — V2 では、GetPackables を除き、ランタイム専用です。

V2 の基本ワークフロー（参考のみ — 代わりに事前ビルドを使用してください）

🚨 重要：このワークフローは参考用としてのみ掲載しています。手動スクリプトではなく、必ず IPreprocessBuildWithReport.OnPreprocessBuild() 内に実装してください。クイックスタートを参照してください。

前提条件

• Unity 6000.3 以降
• Unity のアセットインポートパイプラインに関する基本的な理解
• アトラス作成のためのエディタースクリプトに関する知識

クイックスタート：事前ビルドの自動生成（デフォルトの方法）

概要

これが SpriteAtlas を作成するための主要かつデフォルトの方法です。 IPreprocessBuildWithReport を実装して、分類ルールに基づき、各ビルドの前に SpriteAtlas を自動で生成または更新します。メニューを手動でクリックする必要はありません。

ワークフローの手順

手順 1：ユーザーに配信方法を確認する

コードを生成する前に、次のように質問してください。「スプライトアトラスをどのように配信しますか：（A）組み込みデータ、または（B）Addressables による遅延バインディング？」

手順 2：事前ビルドスクリプトを作成する

このスクリプトを Editor フォルダーに作成します。ユーザーが選択した配信方法に応じてカスタマイズしてください。

オプション A：組み込みデータ（即時読み込み）

組み込みデータ（即時読み込み）

オプション B：Addressables による遅延バインディング（オンデマンド読み込み）

🚨 必須要件：ユーザーが Addressables を選択した場合、以下の 3 つのスクリプトをすべて生成する必要があります。1 つまたは 2 つだけ生成してはいけません。Addressables による配信を機能させるには、3 つすべてが必要です。

必須スクリプト（3 つすべて必須）：

1. 事前ビルドスクリプト（IPreprocessBuildWithReport）- アトラスを生成し、Addressables のエントリを作成します
2. Addressables ビルドスクリプト（IPostprocessBuildWithReport）- Addressables のコンテンツバンドルをビルドします
3. 遅延バインディングランタイムローダー（MonoBehaviour）- ランタイムでのオンデマンド読み込みを処理します

実装の詳細は references/addressables-delivery.md を参照してください。

ワークフロー全体

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

ステップ 3：分類ルールをカスタマイズする

OnPreprocessBuild メソッドを編集して、プロジェクトのスプライト構成に合わせます。次の方法から選択するか、複数の方法を組み合わせてください。

方法	使用する状況	実装
フォルダー別	スプライトがフォルダー構成に従って整理されている場合	GenerateAtlasByFolder("Assets/Art/UI", "Assets/Atlases/UI.spriteatlasv2")
命名規則	スプライトが命名パターンに従っている場合	GenerateAtlasByNaming("Assets/Art", "icon_", "Assets/Atlases/Icons.spriteatlasv2")
アセットラベル	スプライトにラベルが付けられている場合
シーン別	特定のシーンでスプライトを使用する場合	シーンの参照を検索

ステップ 4：プロジェクトをビルドする

ビルド時にアトラスが自動的に生成／更新されます。メニューを手動でクリックする必要はありません。 そのため、プリビルドがデフォルトの方法です。

組み込みデータの場合（オプション A）：

• アトラスがビルドに含まれます
• 実行時にすぐ使用できます

Addressables の場合（オプション B）—追加で必要な手順：

スクリプトは 1 つだけではなく、3 つ生成する必要があります。

1. プリビルドスクリプト（IPreprocessBuildWithReport）—アトラスを生成し、Addressables エントリーを自動作成します
2. Addressables ビルドスクリプト（IPostprocessBuildWithReport）—Addressables コンテンツバンドルをビルドします
3. 遅延バインディングランタイムローダー（MonoBehaviour）—SpriteAtlasManager を介したオンデマンド読み込みを処理します

ビルドプロセスでは、次の処理が行われます。

• アトラスを生成します（プリビルドの手順）
• アドレス可能なエントリーを自動作成します
• Addressables コンテンツバンドルをビルドします（ポストプロセスの手順）
• 実行時：遅延バインディングローダーが、スプライトへの初回アクセス時にアトラスを自動的に読み込みます

一般的な分類パターン

フォルダー構成別：

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");

命名規則別：

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

プリビルドでのバリアント生成

解像度ごとにバリアントアトラスを生成します。

詳細：手動作成（デフォルトではありません。明示的に要求された場合のみ使用してください）

⚠ 警告：手動作成はデフォルトの方法ではありません。ユーザーが手動制御または開発中のエディタープレビューを明示的に要求した場合にのみ、これらのパターンを使用してください。

🚨 デフォルトの方法：代わりに IPreprocessBuildWithReport を使ったプリビルド生成を使用してください。クイックスタートを参照してください。

手動作成が適しているのは、次の場合のみです。

• 正確な配置が重要な、手作業で最適化したスプライトレイアウト
• スプライトの並び順に関するカスタム要件
• 作成ワークフロー中のエディタープレビュー
• ユーザーから明示的に要求された場合

次の場合は手動作成を使用しないでください。

• ユーザーが「スプライトアトラスを作成して」と依頼した場合（プリビルドを使用）
• ユーザーが「スプライトを最適化して」と依頼した場合（プリビルドを使用）
• ユーザーが自動化されたワークフローを求めている場合（プリビルドを使用）
• 手動制御に関する具体的な要件が示されていない場合

マスターアトラスの作成、バリアントの作成、実行時の読み込みを含む手動作成パターンの詳細については、references/manual-authoring.mdを参照してください。

主な要件（V2 固有）

1. 🚨 既存のスクリプトを必ず最初に確認する：コードを生成する前に、[UNITY-SKILL:SPRITEATLAS] 識別子が付いたスクリプトをスキャンし、更新するか新規作成するかユーザーに確認してください
2. 🚨 生成したスクリプトには必ずタグを付ける：今後検出できるよう、生成するすべてのスクリプトの先頭にスキル識別子を含めてください
3. 🚨 配信方法を必ず確認する：コードを生成する前に、ユーザーに「組み込みデータですか、それとも Addressables ですか？」と尋ねてください
4. 🚨 Sprite Packer モードを必ず有効にする：プリビルドスクリプトで EditorSettings.spritePackerMode = SpritePackerMode.SpriteAtlasV2 を設定してください
5. 🚨 必ずプリビルド生成を使用する：アトラスを作成するデフォルトの方法として、IPreprocessBuildWithReport を実装してください
6. 🚨 Assets/ フォルダー内のスプライトのみ追加する：Packages、組み込みアセット、外部の場所にあるスプライトは追加しないでください
7. 🚨 Addressables で配信する場合は、必ず 3 つのスクリプトを生成する：
   • Addressables のセットアップを含むプリビルドアトラス生成スクリプト
   • Addressables コンテンツをビルドする IPostprocessBuildWithReport
   • 遅延バインディングのランタイムローダースクリプト（SpriteAtlasManager を継承）
8. includeInBuild を正しく設定する：組み込みデータの場合は true、Addressables の場合は false
9. 2 段階のエディターパターン：SpriteAtlasAsset で作成 → 保存 → インポート → SpriteAtlasImporter で設定 → SaveAndReimport()
10. エディターコードでは SpriteAtlas を使用しない — 読み込み済みのランタイムアトラスに対する SpriteAtlas.GetPackables() インスタンスメソッドを除く
11. バリアントはマスターを参照する：AssetDatabase.LoadAssetAtPath<SpriteAtlas>() で読み込んだランタイムインスタンスを使用して、SetMasterAtlas(SpriteAtlas) を使用してください
12. プラットフォーム形式の割り当て：キャストせず、format = TextureImporterFormat.ASTC_6x6 を直接使用してください
13. ファイル拡張子：V2 アトラスでは .spriteatlasv2 を使用します（.spriteatlas ではありません）
14. SpriteAtlasUtility.PackAtlases() は任意です：エディターでのプレビューにのみ使用します。ビルド時のパッキングは自動で行われます

よくあるエラーと無効なパターンについては、references/common-errors.md を参照してください。

詳細リファレンス

• Addressables での配信：references/addressables-delivery.md - Addressables を使用した遅延バインディングの完全なセットアップ
• 手動作成：references/manual-authoring.md - 手動作成のパターン（デフォルトではありません。明示的に要求された場合のみ使用）
• よくあるエラー：references/common-errors.md - 無効なパターンと API の修正
• API リファレンス：references/api.md - V2 クラスの完全なドキュメント
• カスタムパッキング：references/custom-packing.md - ScriptablePacker の実装
• ベストプラクティス：references/best-practices.md - 最適化とよくある落とし穴

名前空間

エディタースクリプト：

using UnityEditor;            // AssetImporter, AssetDatabase
using UnityEditor.U2D;        // SpriteAtlasAsset, SpriteAtlasImporter, SpriteAtlasUtility
using UnityEngine;            // Runtime types (e.g., TextureImporterFormat)
using UnityEngine.U2D;        // SpriteAtlas

ランタイムスクリプト：

using UnityEngine;            // Core Unity types
using UnityEngine.U2D;        // SpriteAtlas, SpriteAtlasManager