Addressables - Design Rules

unity-addressables-design

Source-anchored design rules for Unity Addressables 1.22.3 (Unity 2022) and 2.9.1 (Unity 6). Load before writing any InitializeAsync / LoadAssetAsync / LoadSceneAsync / UpdateCatalogs / AssetReference code to avoid removed APIs, handle leaks, SceneReleaseMode bugs, and catalog update ordering err...

gabrielmoreira/agent-skills-mirror·0installs19stars

SKILL.md

Full skill instructions

Addressables - Design Rules

Advisory module. Every rule is distilled from Unity Addressables source at two versions:

1.22.3 — [email protected] (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 code
LoadAssetAsync<T> / LoadAssetsAsync<T> / InstantiateAsync and their handle release
LoadSceneAsync / UnloadSceneAsync — especially with SceneReleaseMode (2.9.1)
CheckForCatalogUpdates → UpdateCatalogs → CleanBundleCache patch flow
GetDownloadSizeAsync / DownloadDependenciesAsync / ClearDependencyCacheAsync
AssetReference / AssetReferenceT<T> field declarations and load/release
Any code that calls WaitForCompletion() or uses AsyncOperationHandle directly
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. New SceneReleaseMode, 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.

Install skill

Copy and run in your terminal

npx -y skills add https://github.com/gabrielmoreira/agent-skills-mirror --skill addressables-design

View on GitHub

mirrors/repos/Besty0728@Unity-Skills/SkillsForUnity/unity-skills~/skills/addressables-design/SKILL.md

swift-concurrency
Diagnose Swift Concurrency issues, refactor callback-based code to async/await, and guide Swift 6 migration when working with tasks, actors, @MainActor, Sendable, data races, thread safety, or concurrency-related compiler and linter warnings.
0 installs
K-12 Exam Systems Coach
Periodically refreshed mirror of agents, skills, prompts and instruction files from public repositories.
0 installs
reddit-post-writer
Write Reddit posts and comments that recommend affiliate products without getting banned or flagged as spam. Subreddit-native content that adds value first. Use this skill when the user asks about Reddit posts for affiliate marketing, writing Reddit comments that mention products, how to promote ...
0 installs
seo-image-gen
AI image generation for SEO assets: OG/social preview images, blog hero images, schema images, product photography, infographics. Powered by Gemini via nanobanana-mcp. Requires banana extension installed. Use when user says \"generate image\", \"OG image\", \"social preview\", \"hero image\", \"b...
0 installs