Agent Skills
› Besty0728/Unity-Skills
› unity-yooasset-design
unity-yooasset-design
GitHub为YooAsset v2.3.18提供源码级设计规则，涵盖初始化、资源加载、热更流程及句柄释放等关键陷阱。用于编写或审查相关代码时确保正确性。
Trigger Scenarios
编写或审查 YooAsset 代码
初始化 ResourcePackage
使用 AssetHandle 加载资源
配置热更新/下载流程
选择运行模式 (Play Mode)
用户提及'热更'或'资源包'
Install
npx skills add Besty0728/Unity-Skills --skill unity-yooasset-design -g -y
SKILL.md
Frontmatter
{
"name": "unity-yooasset-design",
"description": "Source-anchored design rules for YooAsset v2.3.18 — initialization, default-package shortcuts, play modes, asset handles, loading, updates, filesystem, build, and pitfalls. Use when writing or reviewing YooAsset code, initializing packages, loading assets via handles, setting up hot-update\/download, or choosing a play mode, even if the user just says \"热更\" or \"资源包\". 为 YooAsset v2.3.18 提供源码锚定的设计规则(初始化、默认包快捷方式、运行模式、资源句柄、加载、更新、文件系统、构建、陷阱);当用户要编写或审查 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 5EPlayModevariantsLoadAssetSync/Async,LoadSubAssetsAsync,LoadAllAssetsAsync,LoadRawFileAsync,LoadSceneAsyncand their matchingHandleusage / release- Patch flow:
RequestPackageVersionAsync → UpdatePackageManifestAsync → CreateResourceDownloader → BeginDownload FileSystemParametersconstruction (Buildin / Cache / Editor / WebServer / WebRemote / custom)IDecryptionServices/IRemoteServices/IWebDecryptionServicesimplementations- Editor-side
AssetBundleBuilder.Run(...)andAssetBundleCollectorconfiguration - 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 | Initialize / Destroy / CreatePackage / TryGetPackage / RemovePackage; single driver GameObject; OperationSystem loop |
| PLAYMODE.md | All 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.md | Patch 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.md | 30 concrete hallucination pitfalls + legacy API migration section |
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
Version Scope
This document targets YooAsset 2.3.18 (2025-12-04). Key recent history:
- 2.3.18 — added
UNPACK_FILE_SYSTEM_ROOTfile-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
AssetBundleload could block unload. - 2.3.16 — removed the downloader
timeoutparameter (useDOWNLOAD_WATCH_DOG_TIMEon the cache file system instead).IFilterRulegained a requiredFindAssetTypeproperty. - 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, previewUseWeakReferenceHandle(underYOOASSET_EXPERIMENTAL).
Source: Assets/YooAsset/CHANGELOG.md:5-275.
Migration Notes (hallucination shield)
| Legacy API (pre-2.3.18) | Status in 2.3.18 | Replacement | Source |
|---|---|---|---|
CreateResourceDownloader(count, retry, timeout) overload / ResourceDownloaderOperation.timeout property |
Removed in 2.3.16 | Assign 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 breaks | Implement 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-incompatible | Rebuild + 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 shortcut | Prefer 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 YooAsset | Subscribe 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 event | Assign 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.
Version History
- ec9f870 Current 2026-07-05 14:42
