unity-addressables-design
Source-anchored design rules for Unity Addressables 1.22.3/2.9.1
How do I install this agent skill?
npx skills add https://github.com/besty0728/unity-skills --skill unity-addressables-designIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides comprehensive design rules and documentation for Unity Addressables (versions 1.22.3 and 2.9.1). It is strictly instructional and contains no malicious code, remote execution, or data exfiltration patterns.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Addressables - Design Rules
Version scope: Addressables 1.22.3 (Unity 2022) and 2.9.1 (Unity 6). The migration table below lists the cross-version differences.
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.
When to use
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.
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-addressables-design">View unity-addressables-design on skillZs</a>