unity-yooasset-design
Source-anchored design rules for YooAsset v2.3.18, with a 3.x delta sheet
How do I install this agent skill?
npx skills add https://github.com/besty0728/unity-skills --skill unity-yooasset-designIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides technical design rules and best practices for using the YooAsset Unity plugin (versions 2.x and 3.x). It contains architectural guidelines, API references, and migration notes to help an AI agent accurately assist with Unity development tasks. No security risks or malicious patterns were detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
YooAsset - Design Rules
Version scope: YooAsset 2.3.18 (plugin range [2.3.15,2.4.0-0)) and 3.x ([3.0.4,3.1.0-0)). The rules below are 2.x; read V3.md for the 3.x delta.
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.
Version gate: these files describe the 2.x line (2.3.15+). On YooAsset 3.0.4+ most runtime and Editor names changed (Options-style
InitializePackageAsync/LoadPackageManifestAsync,EOperationStatus.Succeeded,Bundle*Editor types, no default-package shortcuts, no AssetArt). Callyooasset_check_installedand readapiLine; when it is"3.x", read V3.md first and translate every 2.x name in the other sub-docs through it.
When to use
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 |
| V3.md | YooAsset 3.0.4+ delta sheet: every 2.x name in this module mapped to its 3.x form, removed features, new behavior traps |
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); the 3.x line (3.0.4+, verified against 3.0.7) is covered only by V3.md. Key recent 2.x 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.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/besty0728/unity-skills/unity-yooasset-design">View unity-yooasset-design on skillZs</a>