unity-yooasset-design

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

トリガー

• YooAsset コードの作成またはレビュー
• パッケージの初期化
• ハンドルを使ったアセットの読み込み
• ホットアップデート／ダウンロードの設定
• 再生モードの選択
• YooAsset コードの作成またはレビュー、パッケージの初期化、ハンドルを使ったアセットの読み込み、ホットアップデート／ダウンロードの設定、再生モードの選択

YooAsset - 設計ルール

参考情報モジュールです。各ルールは、Assets/YooAsset/ にある YooAsset v2.3.18（2025-12-04）のソースから導き出されています。各ルールには具体的なファイルと行が記載されているため、根拠を確認でき、AI が古い記憶をもとに即興で回答することを防げます。

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

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

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

• YooAssets.Initialize() / CreatePackage() / Destroy() の初期化コード
• デフォルトパッケージのショートカット：YooAssets.SetDefaultPackage(...)、YooAssets.LoadAssetAsync(...)、YooAssets.CreateResourceDownloader(...)
• 5 種類の EPlayMode のいずれかを指定した ResourcePackage.InitializeAsync(...)
• LoadAssetSync/Async、LoadSubAssetsAsync、LoadAllAssetsAsync、LoadRawFileAsync、LoadSceneAsync と、それぞれに対応する Handle の使用／解放
• パッチ適用フロー：RequestPackageVersionAsync → UpdatePackageManifestAsync → CreateResourceDownloader → BeginDownload
• FileSystemParameters の構築（Buildin / Cache / Editor / WebServer / WebRemote / カスタム）
• IDecryptionServices / IRemoteServices / IWebDecryptionServices の実装
• エディター側の AssetBundleBuilder.Run(...) と AssetBundleCollector の設定
• EOperationStatus / EFileClearMode / PackageDetails に基づく分岐を行うコード

重要なルールの概要（サブドキュメントを読まない場合でも必ず覚えてください）

#	ルール	ソースのアンカー
1	CreatePackage() を呼び出す前に YooAssets.Initialize() を呼び出し、プロセスレベルのシングルトンとして維持してください。2 回目の呼び出しは警告をログに記録して戻りますが、通常のアーキテクチャでは YooAssets.Initialized で呼び出しを制御してください。この呼び出しにより、DontDestroyOnLoad を使って [{nameof(YooAssets)}] ドライバーの GameObject が作成され、OperationSystem.Update() が実行されます。このドライバーを自分で Destroy しないでください。	Runtime/YooAssets.cs:38-64
2	ResourcePackage.InitializeAsync(...) に個別の EPlayMode 引数はありません。具体的な InitializeParameters サブクラスから再生モードを推測します。組み込みの 5 つのサブクラスは 5 つのモードに 1 対 1 で対応しています。認識されないサブクラスでは NotImplementedException がスローされます。一方、認識されていても意味的に誤ったサブクラスを使うと、誤ったファイルシステムの構成が設定され、後で失敗します。	Runtime/ResourcePackage/ResourcePackage.cs:107-135, 170-181, Runtime/InitializeParameters.cs:8-110
3	EditorSimulateMode が動作するのは UNITY_EDITOR が定義されている場合のみです。WebPlayMode が動作するのは UNITY_WEBGL が定義されている場合のみであり、WebGL ではその他のすべてのモードが拒否されます。	Runtime/ResourcePackage/ResourcePackage.cs:160-197
4	すべての AssetHandle／SubAssetsHandle／AllAssetsHandle／RawFileHandle／SceneHandle は、必ず Release() または Dispose() で解放してください。解放しないと、AutoUnloadBundleWhenUnused = true であってもバンドルはアンロードされません。	Runtime/ResourceManager/Handle/HandleBase.cs:21-40, Runtime/InitializeParameters.cs:48-49
5	LoadAssetSync/Async は DEBUG ビルドのみの型ガードを実行します。このガードは、UnityEngine.Behaviour を継承するすべての Type と、UnityEngine.Object を継承しないすべての型を拒否します。DEBUG 以外のビルドではガードがコンパイルから除外されますが、この制限はアーキテクチャ上の要件として扱ってください。	Runtime/ResourcePackage/ResourcePackage.cs:1172-1187
6	YooAsset 2.3.18 には、YooAssets のデフォルトパッケージ用静的ショートカット（SetDefaultPackage、Load*、CreateResourceDownloader など）が含まれています。これらは有効な API ですが、複数パッケージを扱うコードやライブラリコードでは、明示的な ResourcePackage 参照を優先するのが望ましい設計です。	Runtime/YooAssetsExtension.cs:16, 217-295, 479-506
7	RequestPackageVersionAsync() は RequestPackageVersionOperation を返します（.PackageVersion を公開しています）。2.3.18 には UpdatePackageVersionOperation クラスはありません。そうだったと記憶している場合は、以前の名前と混同しています。	Runtime/ResourcePackage/ResourcePackage.cs:225-231
8	UpdatePackageManifestAsync を呼び出す前に UnloadAllAssetsAsync() を呼び出してください。ローダーがまだ有効な場合、YooAsset は警告をログに記録します。	Runtime/ResourcePackage/ResourcePackage.cs:242-247
9	ダウンローダーのコールバック（DownloadFinishCallback／DownloadUpdateCallback／DownloadErrorCallback／DownloadFileBeginCallback）は、BeginDownload() を呼び出す前に割り当てる必要があります。これらはイベントではなくデリゲートフィールドであり、各スロットに登録できる購読者は 1 つだけです。	Runtime/DownloadSystem + Runtime/ResourcePackage/Operation/DownloaderOperation.cs:86-101, 330-336
10	YooAssets.RemovePackage() を呼び出す前に ResourcePackage.DestroyAsync() を実行する必要があります。InitializeStatus != EOperationStatus.None の場合、RemovePackage は処理を拒否します。	Runtime/YooAssets.cs:177-190, Runtime/ResourcePackage/ResourcePackage.cs:210-218
11	パッチのフローは厳密に次の順序で実行します。InitializeAsync → RequestPackageVersionAsync → UpdatePackageManifestAsync(version) → CreateResourceDownloader → BeginDownload。順序を飛ばす（たとえば、バージョン取得後、マニフェスト更新前にアセットを読み込む）ことはサポートされていません。	Runtime/ResourcePackage/ResourcePackage.cs:225, 238, 972, Samples~/Space Shooter/.../PatchLogic/FsmNode/Fsm*.cs

サブドキュメントへのルーティング

サブドキュメント	読むタイミング
INIT.md	Initialize／Destroy／CreatePackage／TryGetPackage／RemovePackage、単一のドライバー GameObject、OperationSystem ループ
PLAYMODE.md	5 つの EPlayMode 値すべて、それぞれに対応する InitializeParameters サブクラス、プラットフォームの #if ガード、ランタイムのディスパッチテーブル
HANDLES.md	HandleBase API（Release／IsDone／Progress／Status／LastError／Completed／Task／IEnumerator）、AssetHandle.Instantiate*、参照カウント、AutoUnloadBundleWhenUnused
LOADING.md	LoadAsset、LoadSubAssets、LoadAllAssets、LoadRawFile、LoadScene — すべてのオーバーロード＋Behaviour／Type の拒否＋LoadSceneParameters
UPDATE.md	パッチフロー、RequestPackageVersionOperation、UpdatePackageManifestOperation、PreDownloadContentOperation、ResourceDownloaderOperation（4 つのコールバック、一時停止／再開／キャンセル、Combine）
FILESYSTEM.md	FileSystemParameters＋24 個の FileSystemParametersDefine 定数＋5 つのファクトリーヘルパー＋IDecryptionServices／IRemoteServices／IWebDecryptionServices
BUILD.md	AssetBundleBuilder.Run(...)、BuildParameters（Scriptable／Raw／Simulate）、AssetBundleCollector、IFilterRule.FindAssetType、ScriptableBuildParameters.ReplaceAssetPathWithAddress
PITFALLS.md	具体的なハルシネーションの落とし穴 30 件＋レガシー API の移行セクション

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

• YooAsset を利用するプロジェクトの Asmdef とアセンブリ構成 → asmdef を読み込みます
• 複数の YooAsset オペレーションにまたがる非同期オーケストレーション → async を読み込みます
• アーキテクチャレベルの判断（Addressables と YooAsset の比較、単一パッケージと複数パッケージの比較）→ architecture を読み込みます
• 読み込み／解放のホットパスに関するパフォーマンスレビュー → performance を読み込みます

バージョンの対象範囲

このドキュメントは YooAsset 2.3.18（2025-12-04）を対象としています。主な最近の履歴は次のとおりです。

• 2.3.18 — UNPACK_FILE_SYSTEM_ROOT ファイルシステムパラメーター、EFileClearMode.ClearBundleFilesByLocations、RawFileBuildParameters.IncludePathInHash を追加しました。
• 2.3.17 — [CRITICAL] CRC 検証のバグを修正しました。このバグにより、2.3.15／2.3.16 では破損したダウンロードが検証を通過していました。また、実行中の AssetBundle 読み込みによってアンロードがブロックされる、Package の破棄時の競合も修正しました。
• 2.3.16 — ダウンローダーの timeout パラメーターを削除しました（代わりにキャッシュファイルシステムで DOWNLOAD_WATCH_DOG_TIME を使用してください）。IFilterRule に必須プロパティ FindAssetType を追加しました。
• 2.3.15 — マニフェストのバイナリ形式を更新しました。2.3.15 以降でビルドされたインストーラーは、2.3.14 以前のクライアントでは読み取れず、その逆も同様です。FILE_VERIFY_MAX_CONCURRENCY、StripUnityVersion、プレビュー機能の UseWeakReferenceHandle（YOOASSET_EXPERIMENTAL の下）を追加しました。

ソース：Assets/YooAsset/CHANGELOG.md:5-275。

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

レガシー API（2.3.18 より前）	2.3.18 での状態	置き換え先	参照元
CreateResourceDownloader(count, retry, timeout) オーバーロード／ResourceDownloaderOperation.timeout プロパティ	2.3.16 で削除	CacheFileSystemParameters／BuildinFileSystemParameters に DOWNLOAD_WATCH_DOG_TIME を設定します	CHANGELOG.md:173-177, FileSystemParametersDefine.cs:18
FindAssetType プロパティのない IFilterRule	2.3.16 での破壊的変更 — コンパイルエラーになります	Unity のアセットタイプフィルター文字列を返す public string FindAssetType { get; } を実装します	CHANGELOG.md:179-192
古いマニフェストバイナリ（2.3.15 より前のクライアントで 2.3.15 以降のマニフェストを読み込む場合、またはその逆）	ワイヤー互換性なし	再ビルドしてインストーラーを再配布してください。実行時のブリッジはありません	CHANGELOG.md:196-198
YooAssets.LoadAsset(...)	存在しません — メソッド名には LoadAsset だけのものではなく、LoadAssetSync／LoadAssetAsync が含まれます	package.LoadAssetAsync<T>(location)、または SetDefaultPackage の後に YooAssets.LoadAssetAsync<T>(location) を使用します	Runtime/YooAssetsExtension.cs:217-295, Runtime/ResourcePackage/ResourcePackage.cs:641-732
YooAssets.LoadAssetAsync(...) をハルシネーションとして扱うルール	古いルールです — 2.3.18 にはこのデフォルトパッケージ用ショートカットがあります	所有元を明示するには package.LoadAssetAsync<T>(location) を推奨します。静的ショートカットは YooAssets.SetDefaultPackage(package) の後に限り使用できます	Runtime/YooAssetsExtension.cs:16, 260-295
package.UnloadUnusedAssets()（同期）	存在しません	package.UnloadUnusedAssetsAsync(int loopCount = 10) は UnloadUnusedAssetsOperation を返します	Runtime/ResourcePackage/ResourcePackage.cs:355-361
UpdatePackageVersionOperation クラス（実際にある型とよく混同されます）	存在しません	.PackageVersion 文字列プロパティを持つ RequestPackageVersionOperation を使用します	Runtime/ResourcePackage/ResourcePackage.cs:225-231
アセットの同期に使う NetworkVariable<T>／OnValueChanged 形式（Netcode 由来の情報が混入しています）	YooAsset には存在しません	AssetHandle.Completed イベントを購読するか、await handle.Task／yield return handle を使用します	Runtime/ResourceManager/Handle/AssetHandle.cs:20-37, Runtime/ResourceManager/Handle/HandleBase.cs:152-173
ResourceDownloaderOperation.OnDownloadFinishCallback（イベント形式）	フィールドはイベントではなく、通常のデリゲートです	一度だけ代入します：downloader.DownloadFinishCallback = OnFinish; — 単一スロットのフィールドなので += は使用しないでください	Runtime/ResourcePackage/Operation/DownloaderOperation.cs:86-101

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