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.csAddressablesビルダー:
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コンテンツをビルド
- 🚨 必須: レイトバインディングランタイムローダースクリプトを作成
- 適している: 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のゼロ値であり、誰も設定していないプロジェクトではパッキングが無効になります。無効の状態で作成されたアトラスはインポートされ、アセットとして表示され、完成したように見えますが、パックされることはありません。Unityはインスペクターで「Sprite Atlas packing is disabled」と表示します。ワークフローの他の部分は失敗しないため、この方法で出荷されたアトラスは成功として読み取られます。プロジェクトがすでに設定されていると想定しないでください。値を読み取ってください。
そのため、「設定した」だけでは完了と見なさないでください。設定後、EditorSettings.spritePackerModeを読み戻し、Disabledでないことを確認し、実際に読み取った値を報告してください。読み戻せない場合は、書き込みが成功したと仮定せず、その旨を伝えてください。
メタファイルを直接編集しないでください。
🚨 重要: デフォルトアプローチはプリビルド生成
ビルドパイプライン中に自動的にSpriteAtlasを生成または更新するために、常にIPreprocessBuildWithReportを使用してください。 これはデフォルトであり、必須のアプローチです。ユーザーが明示的に手動作成を要求した場合のみ、手動作成を使用してください。
❌ 手動メニューアイテムスクリプトを作成しない
明示的に要求されない限り、アトラス生成のために[MenuItem]属性を持つスクリプトを作成しないでください。 プリビルドアプローチにより、手動クリックの必要性がなくなります。手動作成は以下の場合のみ使用: 手動最適化レイアウト、特定のスプライト配置、エディタープレビュー要件。詳細は「発展編: 手動作成」を参照してください。
🚨 重要: スプライトソース場所の制限
プロジェクトのAssetsフォルダーからのみスプライトを追加してください。Unityビルトインアセット、パッケージ、外部の場所からは絶対に追加しないでください。 UnityビルトインアセットはSpriteAtlasにパックできず、パッケージアセットはインポート/依存関係の問題を引き起こす可能性があります。
重要なV2アーキテクチャ
| コンテキスト | コンポーネント | 目的 | 許可される使用法 |
|---|---|---|---|
| エディター | SpriteAtlasAsset | オーサリング | エディタースクリプト、プリビルド、アセット作成 |
| ランタイム | SpriteAtlas | 読み込みとアクセス | ランタイムスクリプト、Addressables、レイトバインディング |
| 決して混在させない | 両方 | - | SpriteAtlasAssetをビルドに含めない、ランタイムでSpriteAtlasAssetを参照しない、エディターでSpriteAtlasをロードしない |