unity-addressables-design

このモジュールのスキルを呼び出す前に： 名前や説明から推測したパラメーターを使ってスキルを呼び出そうとしている場合は、いったん停止し、まずこのファイルを読むか、GET /skills/recommend?includeSchema=true でスキーマを取得してください。recommend／schema からパラメーター定義をすでに取得している場合は、そのまま dryRun に進めます。

トリガー

• Addressables コードの作成またはレビュー
• アセット／シーンの非同期読み込み
• ホットアップデートまたはカタログの更新
• バージョン移行

Addressables - 設計ルール

参考用モジュールです。すべてのルールは、2つのバージョンの Unity Addressables ソースから抽出されています。

• 1.22.3 — [email protected]（Unity 2022、最小 2019.4）
• 2.9.1 — com.unity.addressables@8460f1c9c927（Unity 6、最小 2023.1）

各ルールには具体的なファイルと行が記載されているため、根拠を検証でき、AI が古い記憶に基づいて即興で対応することを防げます。

モード：ドキュメントのみ — 制限対象となる REST スキルはありません。どの動作モード（Approval / Auto / Bypass）でも自由に読み込めます。

このモジュールを読み込むタイミング

以下を作成またはレビューする前に読み込んでください。

• Addressables.InitializeAsync() ／ LoadContentCatalogAsync() の初期化コード
• LoadAssetAsync<T> ／ LoadAssetsAsync<T> ／ InstantiateAsync と、それらのハンドルの解放
• LoadSceneAsync ／ UnloadSceneAsync — 特に SceneReleaseMode（2.9.1）を使用する場合
• CheckForCatalogUpdates → UpdateCatalogs → CleanBundleCache のパッチフロー
• GetDownloadSizeAsync ／ DownloadDependenciesAsync ／ ClearDependencyCacheAsync
• AssetReference ／ AssetReferenceT<T> のフィールド宣言と読み込み／解放
• WaitForCompletion() を呼び出すコード、または AsyncOperationHandle を直接使用するコード
• 1.22.3 から 2.9.1 への移行 — 削除された API、変更されたオーバーロードのシグネチャ

バージョン差分マトリックス

領域	1.22.3（Unity 2022）	2.9.1（Unity 6）
非 Async バリアント（LoadAsset、Instantiate、LoadScene など）	[Obsolete] — コンパイル警告	削除 — コンパイルエラー
IList<object> の複数キー用オーバーロード	あり	IEnumerable に置き換え
SceneReleaseMode enum	なし	新規 — シーンのアンロード時におけるバンドルの有効期間を制御
LoadSceneAsync の releaseMode パラメーター	なし	デフォルトは SceneReleaseMode.ReleaseSceneWhenSceneUnloaded
LoadAssetsAsync<T>(string key, ...)	なし	新規の文字列キー用オーバーロード
UpdateCatalogs(bool autoCleanBundleCache, ...)	なし	新規のオーバーロード
LegacyResourcesLocator ／ LegacyResourcesProvider	あり	削除
DiagnosticEvent ／ DiagnosticEventCollector	あり	削除
ResourceManagerEventCollector	あり	削除
ResourceManager.RegisterDiagnosticCallback()	[Obsolete]	削除
InitializationOperation プロパティ	[Obsolete]、default を返す	削除
BinaryCatalogInitializationData	なし	新規
CachedFileProvider	なし	新規

重要なルールのまとめ

#	ルール	バージョン	出典アンカー
1	非 Async 版（LoadAsset、Instantiate、LoadScene、UnloadScene、GetDownloadSize、DownloadDependencies、Initialize、LoadContentCatalog）は、1.22.3 ではすべて [Obsolete] で、2.9.1 では削除されています。常に *Async 版を使用してください。	両方	Addressables.cs:1.22.3:862-2226、Addressables.cs:2.9.1（存在しません）
2	Load／Instantiate 呼び出しから返されるすべての AsyncOperationHandle は、Addressables.Release(handle) で解放する必要があります。解放しないと、シーンのアンロード後も AssetBundle がメモリ上に無期限に残り、メモリリークが発生します。	両方	AsyncOperationHandle.cs:2.9.1:178-203
3	WaitForCompletion() は呼び出し元のスレッドを同期的にブロックします。WebGL ではサポートされておらず、例外がスローされます。本番環境ではメインスレッドから絶対に呼び出さず、代わりに await handle.Task または Completed イベントを使用してください。	両方	AsyncOperationHandle.cs:2.9.1:178-203
4	2.9.1 の LoadSceneAsync では、SceneReleaseMode releaseMode（デフォルトは ReleaseSceneWhenSceneUnloaded）が追加されています。Single モードでのロードによって加算読み込みしたシーンがアンロードされ、バンドルを引き続き保持する必要がある場合は、OnlyReleaseSceneOnHandleRelease を渡し、ハンドルを手動で解放してください。	2.9.1	ISceneProvider.cs:2.9.1:14-26、Addressables.cs:2.9.1:1914
5	複数キーを受け取るオーバーロードは、2.9.1 で IList<object> から IEnumerable に変更されました。従来の IList<object> オーバーロードは存在しなくなったため、IEnumerable または string[] を渡してください。	2.9.1	Addressables.cs:2.9.1:1148,1566,1636
6	LegacyResourcesLocator と LegacyResourcesProvider は、2.9.1 で削除されました。Unity 6 を対象とするコードでは参照しないでください。	2.9.1	Runtime/ResourceLocators/（2.9.1 には存在しません）
7	ResourceManager.RegisterDiagnosticCallback() は、1.22.3 では [Obsolete] で、2.9.1 では削除されました。代わりに Addressables Profiler ウィンドウを使用してください。	2.9.1	ResourceManager.cs:1.22.3:353（2.9.1 には存在しません）
8	カタログの更新フローでは、CheckForCatalogUpdates → UpdateCatalogs の順序を厳守してください。2.9.1 では、UpdateCatalogs(bool autoCleanBundleCache, ...) を使うと、古くなったバンドルを 1 回の呼び出しで自動クリーンアップできます。	両方	Addressables.cs:2.9.1:2092-2147
9	AssetReference.LoadAssetAsync<T>() が返すハンドルは、Addressables.Release(handle) ではなく、assetRef.ReleaseAsset() で解放する必要があります。両者を混在させると、二重解放の例外が発生します。	両方	AssetReference.cs:1.22.3:44-46
10	InitializationOperation プロパティ（1.22.3）は [Obsolete] で、default を返します。これを await しないでください。代わりに await Addressables.InitializeAsync() を使用してください。	1.22.3	Addressables.cs:1.22.3:981-982

サブドキュメントの案内

サブドキュメント	参照するタイミング
INIT.md	InitializeAsync／LoadContentCatalogAsync／カタログの読み込み順序／autoReleaseHandle のセマンティクス
HANDLES.md	AsyncOperationHandle<T> のライフサイクル — Completed、WaitForCompletion、Release、IsDone、Status、OperationException、参照カウント
LOADING.md	LoadAssetAsync、LoadAssetsAsync（すべてのオーバーロードとバージョン差分）、MergeMode、InstantiateAsync、ReleaseInstance
SCENE.md	LoadSceneAsync／UnloadSceneAsync／SceneInstance.ActivateAsync／SceneReleaseMode（2.9.1）／activateOnLoad=false のパターン
UPDATE.md	CheckForCatalogUpdates → UpdateCatalogs のフロー／autoCleanBundleCache（2.9.1）／CleanBundleCache／ResourceLocatorInfo
DOWNLOAD.md	GetDownloadSizeAsync／DownloadDependenciesAsync／ClearDependencyCacheAsync／DownloadStatus 構造体
ASSETREF.md	AssetReference／AssetReferenceT<T>／LoadAssetAsync／ReleaseAsset／OperationHandle プロパティ／IsDone ガード
PITFALLS.md	バージョンタグ付きの具体的なハルシネーションの落とし穴 30 件と、レガシー API の移行に関するセクション

他のモジュールへのルーティング

• Addressables のコンシューマー向け asmdef レイアウト → asmdef を読み込みます
• 複数の Addressables 操作にまたがる非同期オーケストレーション → async を読み込みます
• アーキテクチャレベルの判断（Addressables と YooAsset の比較、グループ戦略）→ architecture を読み込みます
• 読み込み／解放のホットパスのパフォーマンスレビュー → performance を読み込みます

バージョンの範囲

このドキュメントは、次の2つのバージョンを対象としています。

• 1.22.3 — Unity 2022 LTS に同梱されています。移行用に、非 Async 版の [Obsolete] バリアントがまだ含まれています。
• 2.9.1 — Unity 6（2023.1 以降）に同梱されています。すべての [Obsolete] API が削除されています。新しい SceneReleaseMode、バイナリカタログ形式、AutoGroupGenerator が含まれます。

一方のバージョンにのみ適用されるルールには、[1.22.3] または [2.9.1] のタグが付いています。タグのないルールは両方に適用されます。

移行に関する注意事項（ハルシネーション防止）

レガシー API	状態	置き換え先	ソース
Addressables.Initialize()	1.22.3 では [Obsolete]、2.9.1 では削除	Addressables.InitializeAsync()	Addressables.cs:1.22.3:862-864
Addressables.LoadAsset<T>(key)	1.22.3 では [Obsolete]、2.9.1 では削除	Addressables.LoadAssetAsync<T>(key)	Addressables.cs:1.22.3:992-1007
Addressables.LoadAssets<T>(keys, cb, mode)	1.22.3 では [Obsolete]、2.9.1 では削除	Addressables.LoadAssetsAsync<T>(keys, cb, mode)	Addressables.cs:1.22.3:1242-1276
Addressables.Instantiate(key, ...)	1.22.3 では [Obsolete]、2.9.1 では削除	Addressables.InstantiateAsync(key, ...)	Addressables.cs:1.22.3:1892-1972
Addressables.LoadScene(key, ...)	1.22.3 では [Obsolete]、2.9.1 では削除	Addressables.LoadSceneAsync(key, ...)	Addressables.cs:1.22.3:2090-2106
Addressables.UnloadScene(handle, ...)	1.22.3 では [Obsolete]、2.9.1 では削除	Addressables.UnloadSceneAsync(handle, ...)	Addressables.cs:1.22.3:2180-2226
Addressables.GetDownloadSize(key)	1.22.3 では [Obsolete]、2.9.1 では削除	Addressables.GetDownloadSizeAsync(key)	Addressables.cs:1.22.3:1547
Addressables.DownloadDependencies(key)	1.22.3 では [Obsolete]、2.9.1 では削除	Addressables.DownloadDependenciesAsync(key)	Addressables.cs:1.22.3:1608
Addressables.InitializationOperation	1.22.3 では [Obsolete]、2.9.1 では削除	await Addressables.InitializeAsync()	Addressables.cs:1.22.3:981-982
LoadResourceLocationsAsync(IList<object> keys, ...)	1.22.3 では存在、2.9.1 では削除	LoadResourceLocationsAsync(IEnumerable keys, ...)	Addressables.cs:2.9.1:1148
GetDownloadSizeAsync(IList<object> keys)	1.22.3 では存在、2.9.1 では削除	GetDownloadSizeAsync(IEnumerable keys)	Addressables.cs:2.9.1:1566
DownloadDependenciesAsync(IList<object> keys, mode, ...)	1.22.3 では存在、2.9.1 では削除	DownloadDependenciesAsync(IEnumerable keys, mode, ...)	Addressables.cs:2.9.1:1636
LegacyResourcesLocator / LegacyResourcesProvider	1.22.3 では存在、2.9.1 では削除	すべてのアセットに Addressables グループを使用します	Runtime/ResourceLocators/LegacyResourcesLocator.cs:1.22.3
ResourceManager.RegisterDiagnosticCallback(...)	1.22.3 では [Obsolete]、2.9.1 では削除	Addressables Profiler ウィンドウ	ResourceManager.cs:1.22.3:353
DiagnosticEvent / DiagnosticEventCollector	1.22.3 では存在、2.9.1 では削除	Addressables Profiler／カスタム IProfilerEmitter	Runtime/ResourceManager/Diagnostics/:1.22.3

迷った場合は、記憶ではなく、引用されているソースを読んでください。