/yooasset-design

name: unity-yooasset-design
description: Source-anchored design rules for YooAsset v2.3.18. 为 YooAsset v2.3.18 提供源码锚定的设计规则。

Triggers

• Writing or reviewing YooAsset code
• Initializing packages
• Loading assets via handles
• Setting up hot-update/download
• Choosing a play mode
• 编写或审查 YooAsset 代码、初始化 package、用句柄加载资源、配置热更/下载、选择运行模式

YooAsset - Design Rules

Advisory module. Every rule is distilled from YooAsset **v2.3.18** (2025-12-04) source at `Assets/YooAsset/`. Each rule cites a concrete file/line so the reasoning is auditable and the AI does not improvise against stale memory.

> **Mode**: Documentation only — no REST skills to gate; load freely under any operating mode (Approval / Auto / Bypass).

When to Load This Module

Load before writing or reviewing any of:

• `YooAssets.Initialize()` / `CreatePackage()` / `Destroy()` bootstrap code
• default package shortcuts: `YooAssets.SetDefaultPackage(...)`, `YooAssets.LoadAssetAsync(...)`, `YooAssets.CreateResourceDownloader(...)`
• `ResourcePackage.InitializeAsync(...)` with any of the 5 `EPlayMode` variants
• `LoadAssetSync/Async`, `LoadSubAssetsAsync`, `LoadAllAssetsAsync`, `LoadRawFileAsync`, `LoadSceneAsync` and their matching `Handle` usage / release
• Patch flow: `RequestPackageVersionAsync → UpdatePackageManifestAsync → CreateResourceDownloader → BeginDownload`
• `FileSystemParameters` construction (Buildin / Cache / Editor / WebServer / WebRemote / custom)
• `IDecryptionServices` / `IRemoteServices` / `IWebDecryptionServices` implementations
• Editor-side `AssetBundleBuilder.Run(...)` and `AssetBundleCollector` configuration
• Any code branching on `EOperationStatus` / `EFileClearMode` / `PackageDetails`

Critical Rule Summary (memorize even if you skip the sub-docs)

| # | Rule | Source anchor | |---|------|---------------| | 1 | Call `YooAssets.Initialize()` before any `CreatePackage()` and keep it as a process-level singleton. A second call only logs a warning and returns, but normal architecture should gate it with `YooAssets.Initialized`. The call creates a `[{nameof(YooAssets)}]` driver GameObject via `DontDestroyOnLoad` to pump `OperationSystem.Update()`. Do not `Destroy` this driver yourself. | `Runtime/YooAssets.cs:38-64` | | 2 | `ResourcePackage.InitializeAsync(...)` has no separate `EPlayMode` argument: it infers play mode from the concrete `InitializeParameters` subclass. The five built-in subclasses map 1:1 to the five modes; an unknown subclass throws `NotImplementedException`, while a recognized but semantically wrong subclass wires the wrong file-system topology and fails later. | `Runtime/ResourcePackage/ResourcePackage.cs:107-135, 170-181`, `Runtime/InitializeParameters.cs:8-110` | | 3 | `EditorSimulateMode` works only when `UNITY_EDITOR` is defined; `WebPlayMode` works only when `UNITY_WEBGL` is defined (and every other mode is rejected on WebGL). | `Runtime/ResourcePackage/ResourcePackage.cs:160-197` | | 4 | Every `AssetHandle` / `SubAssetsHandle` / `AllAssetsHandle` / `RawFileHandle` / `SceneHandle` **must** be released via `Release()` or `Dispose()`. Without release, bundles never unload even with `AutoUnloadBundleWhenUnused = true`. | `Runtime/ResourceManager/Handle/HandleBase.cs:21-40`, `Runtime/InitializeParameters.cs:48-49` | | 5 | `LoadAssetSync/Async` performs a DEBUG-only type guard that rejects any `Type` derived from `UnityEngine.Behaviour` and any type not derived from `UnityEngine.Object`. Treat the restriction as architectural even though the guard is compiled out of non-DEBUG builds. | `Runtime/ResourcePackage/ResourcePackage.cs:1172-1187` | | 6 | YooAsset 2.3.18 includes default-package static shortcuts on `YooAssets` (`SetDefaultPackage`, `Load*`, `CreateResourceDownloader`, etc.). They are valid API, but architecture should prefer explicit `ResourcePackage` references in multi-package or library code. | `Runtime/YooAssetsExtension.cs:16, 217-295, 479-506` | | 7 | `RequestPackageVersionAsync()` returns `RequestPackageVersionOperation` (exposes `.PackageVersion`). There is **no** `UpdatePackageVersionOperation` class in 2.3.18 — if you think you remember one, you are confusing it with the older name. | `Runtime/ResourcePackage/ResourcePackage.cs:225-231` | | 8 | Before `UpdatePackageManifestAsync`, call `UnloadAllAssetsAsync()`; YooAsset logs a warning when loaders are still alive. | `Runtime/ResourcePackage/ResourcePackage.cs:242-247` | | 9 | Downloader callbacks (`DownloadFinishCallback` / `DownloadUpdateCallback` / `DownloadErrorCallback` / `DownloadFileBeginCallback`) must be assigned **before** `BeginDownload()`. They are delegate fields, not events — only one subscriber per slot. | `Runtime/DownloadSystem` + `Runtime/ResourcePackage/Operation/DownloaderOperation.cs:86-101, 330-336` | | 10 | `ResourcePackage.DestroyAsync()` must run before `YooAssets.RemovePackage()`. `RemovePackage` refuses when `InitializeStatus != EOperationStatus.None`. | `Runtime/YooAssets.cs:177-190`, `Runtime/ResourcePackage/ResourcePackage.cs:210-218` | | 11 | The patch flow is strictly ordered: `InitializeAsync → RequestPackageVersionAsync → UpdatePackageManifestAsync(version) → CreateResourceDownloader → BeginDownload`. Jumping ahead (e.g. loading assets between version and manifest) is unsupported. | `Runtime/ResourcePackage/ResourcePackage.cs:225, 238, 972`, `Samples~/Space Shooter/.../PatchLogic/FsmNode/Fsm*.cs` |

Sub-doc Routing

| Sub-doc | When to read | |---------|--------------| | [INIT.md](./INIT.md) | `Initialize` / `Destroy` / `CreatePackage` / `TryGetPackage` / `RemovePackage`; single driver GameObject; `OperationSystem` loop | | [PLAYMODE.md](./PLAYMODE.md) | All 5 `EPlayMode` values, their matching `InitializeParameters` subclass, platform `#if` guards, and the runtime dispatch table | | [HANDLES.md](./HANDLES.md) | `HandleBase` API (Release / IsDone / Progress / Status / LastError / Completed / Task / IEnumerator), `AssetHandle.Instantiate*`, reference counting, `AutoUnloa