<< All versions
Skill v1.0.1
currentAutomated scan100/100besty0728/unity-skills/addressables-design
+1 new
──Details
PublishedJune 26, 2026 at 03:07 AM
Content Hashsha256:26f40fb5c62b2296...
Git SHAc04335936688
Bump Typepatch
──Files
Files (1 file, 10.7 KB)
SKILL.md10.7 KBactive
SKILL.md · 112 lines · 10.7 KB
version: "1.0.1" name: unity-addressables-design description: Source-anchored design rules for Unity Addressables across two versions — 1.22.3 on Unity 2022 and 2.9.1 on Unity 6 — covering initialization, async operation handles, asset/scene loading, catalog updates, content download, AssetReference, and version migration. Use when writing or reviewing Addressables code, loading assets/scenes asynchronously, setting up hot-update or catalog refresh, or migrating between versions, even if the user just says "可寻址" or "热更". 为 Unity Addressables 提供源码锚定的设计规则(覆盖两个版本,Unity 2022 用 1.22.3、Unity 6 用 2.9.1;含初始化、异步操作句柄、资源/场景加载、目录更新、资源下载、AssetReference、版本迁移);当用户要编写或审查 Addressables 代码、异步加载资源/场景、配置热更新或目录刷新时使用。
Addressables - Design Rules
Advisory module. Every rule is distilled from Unity Addressables source at two versions:
- 1.22.3 —
com.unity.addressables@1.22.3(Unity 2022, min 2019.4) - 2.9.1 —
com.unity.addressables@8460f1c9c927(Unity 6, min 2023.1)
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:
Addressables.InitializeAsync()/LoadContentCatalogAsync()bootstrap codeLoadAssetAsync<T>/LoadAssetsAsync<T>/InstantiateAsyncand their handle releaseLoadSceneAsync/UnloadSceneAsync— especially withSceneReleaseMode(2.9.1)CheckForCatalogUpdates→UpdateCatalogs→CleanBundleCachepatch flowGetDownloadSizeAsync/DownloadDependenciesAsync/ClearDependencyCacheAsyncAssetReference/AssetReferenceT<T>field declarations and load/release- Any code that calls
WaitForCompletion()or usesAsyncOperationHandledirectly - Migration from 1.22.3 to 2.9.1 — removed APIs, changed overload signatures
Version Difference Matrix
| Area | 1.22.3 (Unity 2022) | 2.9.1 (Unity 6) | |
|---|---|---|---|
Non-Async variants (LoadAsset, Instantiate, LoadScene, etc.) | [Obsolete] — compile warning | Removed — compile error | |
IList<object> multi-key overloads | Present | Replaced by IEnumerable | |
SceneReleaseMode enum | Does not exist | New — controls bundle lifetime on scene unload | |
LoadSceneAsync releaseMode param | Absent | SceneReleaseMode.ReleaseSceneWhenSceneUnloaded default | |
LoadAssetsAsync<T>(string key, ...) | Does not exist | New string-key overload | |
UpdateCatalogs(bool autoCleanBundleCache, ...) | Does not exist | New overload | |
LegacyResourcesLocator / LegacyResourcesProvider | Present | Removed | |
DiagnosticEvent / DiagnosticEventCollector | Present | Removed | |
ResourceManagerEventCollector | Present | Removed | |
ResourceManager.RegisterDiagnosticCallback() | [Obsolete] | Removed | |
InitializationOperation property | [Obsolete], returns default | Removed | |
BinaryCatalogInitializationData | Does not exist | New | |
CachedFileProvider | Does not exist | New |
Critical Rule Summary
| # | Rule | Version | Source anchor | |
|---|---|---|---|---|
| 1 | All non-Async variants (LoadAsset, Instantiate, LoadScene, UnloadScene, GetDownloadSize, DownloadDependencies, Initialize, LoadContentCatalog) are [Obsolete] in 1.22.3 and removed in 2.9.1. Always use the *Async form. | Both | Addressables.cs:1.22.3:862-2226, Addressables.cs:2.9.1 (absent) | |
| 2 | Every AsyncOperationHandle returned by a Load/Instantiate call MUST be released via Addressables.Release(handle). Forgetting leaks the AssetBundle in memory indefinitely — even after the scene unloads. | Both | AsyncOperationHandle.cs:2.9.1:178-203 | |
| 3 | WaitForCompletion() blocks the calling thread synchronously. On WebGL it is unsupported and throws. Never call it on the main thread in production; use await handle.Task or the Completed event instead. | Both | AsyncOperationHandle.cs:2.9.1:178-203 | |
| 4 | LoadSceneAsync in 2.9.1 adds SceneReleaseMode releaseMode (default ReleaseSceneWhenSceneUnloaded). If a Single-mode load unloads your additive scene and you need the bundle to stay alive, pass OnlyReleaseSceneOnHandleRelease and release the handle manually. | 2.9.1 | ISceneProvider.cs:2.9.1:14-26, Addressables.cs:2.9.1:1914 | |
| 5 | Multi-key overloads changed from IList<object> to IEnumerable in 2.9.1. The old IList<object> overloads no longer exist — pass IEnumerable or string[]. | 2.9.1 | Addressables.cs:2.9.1:1148,1566,1636 | |
| 6 | LegacyResourcesLocator and LegacyResourcesProvider were removed in 2.9.1. Do not reference them in code targeting Unity 6. | 2.9.1 | Runtime/ResourceLocators/ (absent in 2.9.1) | |
| 7 | ResourceManager.RegisterDiagnosticCallback() was [Obsolete] in 1.22.3 and removed in 2.9.1. Use the Addressables Profiler window instead. | 2.9.1 | ResourceManager.cs:1.22.3:353 (absent in 2.9.1) | |
| 8 | Catalog update flow is strictly ordered: CheckForCatalogUpdates → UpdateCatalogs. In 2.9.1, UpdateCatalogs(bool autoCleanBundleCache, ...) can auto-clean stale bundles in one call. | Both | Addressables.cs:2.9.1:2092-2147 | |
| 9 | AssetReference.LoadAssetAsync<T>() returns a handle that must be released via assetRef.ReleaseAsset(), NOT Addressables.Release(handle). Mixing the two causes double-release exceptions. | Both | AssetReference.cs:1.22.3:44-46 | |
| 10 | InitializationOperation property (1.22.3) is [Obsolete] and returns default. Do not await it. Use await Addressables.InitializeAsync() instead. | 1.22.3 | Addressables.cs:1.22.3:981-982 |
Sub-doc Routing
| Sub-doc | When to read | |
|---|---|---|
| INIT.md | InitializeAsync / LoadContentCatalogAsync / catalog loading order / autoReleaseHandle semantics | |
| HANDLES.md | AsyncOperationHandle<T> lifecycle — Completed, WaitForCompletion, Release, IsDone, Status, OperationException, ref-counting | |
| LOADING.md | LoadAssetAsync, LoadAssetsAsync (all overloads + version diff), MergeMode, InstantiateAsync, ReleaseInstance | |
| SCENE.md | LoadSceneAsync / UnloadSceneAsync / SceneInstance.ActivateAsync / SceneReleaseMode (2.9.1) / activateOnLoad=false pattern | |
| UPDATE.md | CheckForCatalogUpdates → UpdateCatalogs flow / autoCleanBundleCache (2.9.1) / CleanBundleCache / ResourceLocatorInfo | |
| DOWNLOAD.md | GetDownloadSizeAsync / DownloadDependenciesAsync / ClearDependencyCacheAsync / DownloadStatus struct | |
| ASSETREF.md | AssetReference / AssetReferenceT<T> / LoadAssetAsync / ReleaseAsset / OperationHandle property / IsDone guard | |
| PITFALLS.md | 30 concrete hallucination pitfalls with version tags + legacy API migration section |
Routing to Other Modules
- Asmdef layout for Addressables consumers → load asmdef
- Async orchestration across multiple Addressables operations → load async
- Architecture-level decisions (Addressables vs YooAsset, group strategy) → load architecture
- Performance review of load/release hot paths → load performance
Version Scope
This document targets two versions:
- 1.22.3 — shipped with Unity 2022 LTS. Contains
[Obsolete]non-Async variants still present for migration. - 2.9.1 — shipped with Unity 6 (2023.1+). All
[Obsolete]APIs removed. NewSceneReleaseMode, binary catalog format,AutoGroupGenerator.
When a rule applies to only one version it is tagged [1.22.3] or [2.9.1]. Untagged rules apply to both.
Migration Notes (hallucination shield)
| Legacy API | Status | Replacement | Source | |
|---|---|---|---|---|
Addressables.Initialize() | [Obsolete] in 1.22.3, removed in 2.9.1 | Addressables.InitializeAsync() | Addressables.cs:1.22.3:862-864 | |
Addressables.LoadAsset<T>(key) | [Obsolete] in 1.22.3, removed in 2.9.1 | Addressables.LoadAssetAsync<T>(key) | Addressables.cs:1.22.3:992-1007 | |
Addressables.LoadAssets<T>(keys, cb, mode) | [Obsolete] in 1.22.3, removed in 2.9.1 | Addressables.LoadAssetsAsync<T>(keys, cb, mode) | Addressables.cs:1.22.3:1242-1276 | |
Addressables.Instantiate(key, ...) | [Obsolete] in 1.22.3, removed in 2.9.1 | Addressables.InstantiateAsync(key, ...) | Addressables.cs:1.22.3:1892-1972 | |
Addressables.LoadScene(key, ...) | [Obsolete] in 1.22.3, removed in 2.9.1 | Addressables.LoadSceneAsync(key, ...) | Addressables.cs:1.22.3:2090-2106 | |
Addressables.UnloadScene(handle, ...) | [Obsolete] in 1.22.3, removed in 2.9.1 | Addressables.UnloadSceneAsync(handle, ...) | Addressables.cs:1.22.3:2180-2226 | |
Addressables.GetDownloadSize(key) | [Obsolete] in 1.22.3, removed in 2.9.1 | Addressables.GetDownloadSizeAsync(key) | Addressables.cs:1.22.3:1547 | |
Addressables.DownloadDependencies(key) | [Obsolete] in 1.22.3, removed in 2.9.1 | Addressables.DownloadDependenciesAsync(key) | Addressables.cs:1.22.3:1608 | |
Addressables.InitializationOperation | [Obsolete] in 1.22.3, removed in 2.9.1 | await Addressables.InitializeAsync() | Addressables.cs:1.22.3:981-982 | |
LoadResourceLocationsAsync(IList<object> keys, ...) | Present in 1.22.3, removed in 2.9.1 | LoadResourceLocationsAsync(IEnumerable keys, ...) | Addressables.cs:2.9.1:1148 | |
GetDownloadSizeAsync(IList<object> keys) | Present in 1.22.3, removed in 2.9.1 | GetDownloadSizeAsync(IEnumerable keys) | Addressables.cs:2.9.1:1566 | |
DownloadDependenciesAsync(IList<object> keys, mode, ...) | Present in 1.22.3, removed in 2.9.1 | DownloadDependenciesAsync(IEnumerable keys, mode, ...) | Addressables.cs:2.9.1:1636 | |
LegacyResourcesLocator / LegacyResourcesProvider | Present in 1.22.3, removed in 2.9.1 | Use Addressables groups for all assets | Runtime/ResourceLocators/LegacyResourcesLocator.cs:1.22.3 | |
ResourceManager.RegisterDiagnosticCallback(...) | [Obsolete] in 1.22.3, removed in 2.9.1 | Addressables Profiler window | ResourceManager.cs:1.22.3:353 | |
DiagnosticEvent / DiagnosticEventCollector | Present in 1.22.3, removed in 2.9.1 | Addressables Profiler / custom IProfilerEmitter | Runtime/ResourceManager/Diagnostics/:1.22.3 |
When in doubt, read the cited source — not your memory.