Back to Details

unity-yooasset-design

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
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.
调用本模块中的任何技能之前： 如果你打算根据技能名称或描述猜测参数来调用技能，请停止操作——先阅读本文档（或通过
GET /skills/recommend?includeSchema=true
获取其 schema）。如果你已经从推荐/schema中获得了参数定义，可以直接进入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代码
  • 初始化包
  • 通过句柄加载资源
  • 配置热更新/下载
  • 选择运行模式
  • 编写或审查 YooAsset 代码、初始化 package、用句柄加载资源、配置热更/下载、选择运行模式

YooAsset - Design Rules

YooAsset - 设计规范

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).
本模块为指导性模块。每条规范均提炼自
Assets/YooAsset/
路径下的YooAsset v2.3.18（2025-12-04）源码。每条规范都引用了具体的文件/行号，因此其依据可被审计，AI不会基于过时记忆随意发挥。
模式：仅文档模式——无REST技能限制；可在任何操作模式（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
在编写或审查以下代码之前加载本模块：
  • 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
    分支的代码

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

核心规范总结（即使跳过子文档也需牢记）

#RuleSource anchor
1Call 
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
4Every 
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
6YooAsset 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
8Before 
UpdatePackageManifestAsync
, call 
UnloadAllAssetsAsync()
; YooAsset logs a warning when loaders are still alive.
Runtime/ResourcePackage/ResourcePackage.cs:242-247
9Downloader 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
11The 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
序号规范源码锚点
1在调用任何
CreatePackage()
之前必须调用
YooAssets.Initialize()
，并将其作为进程级单例。第二次调用仅会记录警告并返回，但合理的架构应通过
YooAssets.Initialized
来限制调用。该调用会通过
DontDestroyOnLoad
创建一个名为
[{nameof(YooAssets)}]
的驱动GameObject，以驱动
OperationSystem.Update()
。请勿自行销毁该驱动对象。
Runtime/YooAssets.cs:38-64
2
ResourcePackage.InitializeAsync(...)
没有单独的
EPlayMode
参数：它会从具体的
InitializeParameters
子类推断运行模式。五个内置子类与五种模式一一对应；未知子类会抛出
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
6YooAsset 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()
之前赋值。它们是委托字段而非事件——每个槽位只能有一个订阅者。
Runtime/DownloadSystem
+ 
Runtime/ResourcePackage/Operation/DownloaderOperation.cs:86-101, 330-336
10
ResourcePackage.DestroyAsync()
必须在
YooAssets.RemovePackage()
之前执行。当
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

Sub-doc Routing

子文档导航

Sub-docWhen to read
INIT.md
Initialize
/ 
Destroy
/ 
CreatePackage
/ 
TryGetPackage
/ 
RemovePackage
; single driver GameObject; 
OperationSystem
loop
PLAYMODE.mdAll 5 
EPlayMode
values, their matching 
InitializeParameters
subclass, platform 
#if
guards, and the runtime dispatch table
HANDLES.md
HandleBase
API (Release / IsDone / Progress / Status / LastError / Completed / Task / IEnumerator), 
AssetHandle.Instantiate*
, reference counting, 
AutoUnloadBundleWhenUnused
LOADING.md
LoadAsset
, 
LoadSubAssets
, 
LoadAllAssets
, 
LoadRawFile
, 
LoadScene
— all overloads + Behaviour/Type rejection + 
LoadSceneParameters
UPDATE.mdPatch flow, 
RequestPackageVersionOperation
, 
UpdatePackageManifestOperation
, 
PreDownloadContentOperation
, 
ResourceDownloaderOperation
(4 callbacks, pause/resume/cancel, 
Combine
)
FILESYSTEM.md
FileSystemParameters
+ 24 
FileSystemParametersDefine
constants + 5 factory helpers + 
IDecryptionServices
/ 
IRemoteServices
/ 
IWebDecryptionServices
BUILD.md
AssetBundleBuilder.Run(...)
, 
BuildParameters
(Scriptable / Raw / Simulate), 
AssetBundleCollector
, 
IFilterRule.FindAssetType
, 
ScriptableBuildParameters.ReplaceAssetPathWithAddress
PITFALLS.md30 concrete hallucination pitfalls + legacy API migration section
子文档阅读时机
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.md30个具体的易混淆陷阱 + 旧版API迁移章节

Routing to Other Modules

其他模块导航

  • Asmdef & assembly layout for YooAsset consumers → load asmdef
  • Async orchestration across multiple YooAsset operations → load async
  • Architecture-level decisions (Addressables vs YooAsset, single-package vs multi-package) → load architecture
  • Performance review of load/release hot paths → load performance
  • YooAsset使用者的Asmdef与程序集布局 → 加载asmdef
  • 跨多个YooAsset操作的异步编排 → 加载async
  • 架构层面决策（Addressables vs YooAsset、单包 vs 多包） → 加载architecture
  • 加载/释放热路径的性能审查 → 加载performance

Version Scope

版本范围

This document targets YooAsset 2.3.18 (2025-12-04). Key recent history:
  • 2.3.18 — added 
    UNPACK_FILE_SYSTEM_ROOT
    file-system parameter, 
    EFileClearMode.ClearBundleFilesByLocations
    , 
    RawFileBuildParameters.IncludePathInHash
    .
  • 2.3.17 — [CRITICAL] fixed a CRC-validation bug that let corrupted downloads pass verification on 2.3.15/2.3.16. Also fixed a Package-destroy race where an in-flight 
    AssetBundle
    load could block unload.
  • 2.3.16 — removed the downloader 
    timeout
    parameter (use 
    DOWNLOAD_WATCH_DOG_TIME
    on the cache file system instead). 
    IFilterRule
    gained a required 
    FindAssetType
    property.
  • 2.3.15 — bumped the manifest binary format; installers built with 2.3.15+ are not readable by 2.3.14 or earlier clients and vice versa. Added 
    FILE_VERIFY_MAX_CONCURRENCY
    , 
    StripUnityVersion
    , preview 
    UseWeakReferenceHandle
    (under 
    YOOASSET_EXPERIMENTAL
    ).
Source: 
Assets/YooAsset/CHANGELOG.md:5-275
.
本文档针对YooAsset 2.3.18（2025-12-04）。近期关键版本历史：
  • 2.3.18 — 新增
    UNPACK_FILE_SYSTEM_ROOT
    文件系统参数、
    EFileClearMode.ClearBundleFilesByLocations
    、
    RawFileBuildParameters.IncludePathInHash
    。
  • 2.3.17 — [重要修复] 修复了一个CRC验证漏洞，该漏洞曾导致2.3.15/2.3.16版本中损坏的下载包通过验证。同时修复了包销毁时的竞态问题，即正在进行的
    AssetBundle
    加载可能会阻塞卸载。
  • 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
。

Migration Notes (hallucination shield)

迁移说明（防混淆）

Legacy API (pre-2.3.18)Status in 2.3.18ReplacementSource
CreateResourceDownloader(count, retry, timeout)
overload / 
ResourceDownloaderOperation.timeout
property		Removed in 2.3.16Assign 
DOWNLOAD_WATCH_DOG_TIME
on the 
CacheFileSystemParameters
/ 
BuildinFileSystemParameters
CHANGELOG.md:173-177
, 
FileSystemParametersDefine.cs:18
IFilterRule
without a 
FindAssetType
property		Breaking change in 2.3.16 — compilation breaksImplement 
public string FindAssetType { get; }
that returns a Unity asset-type filter string
CHANGELOG.md:179-192
Old manifest binary (pre-2.3.15 client reading a 2.3.15+ manifest, or vice versa)Wire-incompatibleRebuild + re-ship installer; no runtime bridge exists
CHANGELOG.md:196-198
YooAssets.LoadAsset(...)
Does not exist — method names include 
LoadAssetSync
/ 
LoadAssetAsync
, not bare 
LoadAsset
package.LoadAssetAsync<T>(location)
or 
YooAssets.LoadAssetAsync<T>(location)
after 
SetDefaultPackage
Runtime/YooAssetsExtension.cs:217-295
, 
Runtime/ResourcePackage/ResourcePackage.cs:641-732
YooAssets.LoadAssetAsync(...)
marked as hallucination		Outdated rule — 2.3.18 has this default-package shortcutPrefer 
package.LoadAssetAsync<T>(location)
for explicit ownership; static shortcut is acceptable only after 
YooAssets.SetDefaultPackage(package)
Runtime/YooAssetsExtension.cs:16, 260-295
package.UnloadUnusedAssets()
(synchronous)		Does not exist
package.UnloadUnusedAssetsAsync(int loopCount = 10)
returns an 
UnloadUnusedAssetsOperation
Runtime/ResourcePackage/ResourcePackage.cs:355-361
UpdatePackageVersionOperation
class (often confused with the real type)		Does not exist
RequestPackageVersionOperation
, with a 
.PackageVersion
string property
Runtime/ResourcePackage/ResourcePackage.cs:225-231
NetworkVariable<T>
/ 
OnValueChanged
style sync for assets (leaked in from Netcode)		Does not exist in YooAssetSubscribe 
AssetHandle.Completed
event or 
await handle.Task
/ 
yield return handle
Runtime/ResourceManager/Handle/AssetHandle.cs:20-37
, 
Runtime/ResourceManager/Handle/HandleBase.cs:152-173
ResourceDownloaderOperation.OnDownloadFinishCallback
(event-style)		Field is a plain delegate, not an eventAssign once: 
downloader.DownloadFinishCallback = OnFinish;
— do not 
+=
(single-slot field)
Runtime/ResourcePackage/Operation/DownloaderOperation.cs:86-101
When in doubt, read the cited source — not your memory.
旧版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中为破坏性变更——编译会失败实现
public string FindAssetType { get; }
，返回Unity资源类型过滤字符串
CHANGELOG.md:179-192
旧版清单二进制（2.3.15之前的客户端读取2.3.15+版本的清单，或反之）完全不兼容重新构建并发布安装包；不存在运行时桥接方案
CHANGELOG.md:196-198
YooAssets.LoadAsset(...)
不存在——方法名称包含
LoadAssetSync
/ 
LoadAssetAsync
，而非裸
LoadAsset
在调用
SetDefaultPackage
后使用
package.LoadAssetAsync<T>(location)
或
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
类（常与真实类型混淆）		不存在
RequestPackageVersionOperation
，带有
.PackageVersion
字符串属性
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
如有疑问，请阅读引用的源码——而非依赖你的记忆。