Yooasset DesignSAFE

AI automation skills specifically designed for Unity

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: unity-yooasset-design
description: Source-anchored design rules for YooAsset v2.3.18
---

> **Before calling any skill in this module:** if you are about to call a skill with parameters guessed from its name or description, STOP — read this file (or fetch its schema via `GET /skills/recommend?includeSchema=true`) first. If you already have the parameter definitions from recommend/schema, you may proceed straight to dryRun.

## 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

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.