t1k:unity:base:addressables
| Field | Value |
|---|---|
| Module | base |
| Version | 5.116.6 |
| Effort | high |
| Tools | — |
Keywords: addressables, asset management, loading
How to invoke
Section titled “How to invoke”/t1k:unity:base:addressablesUnity Addressables — Asset Management
Section titled “Unity Addressables — Asset Management”Addressables replaces Resources.Load() with address-based async loading, reference-counted memory, and remote content delivery.
Key rule: Every Load must pair with Release to avoid memory leaks.
Load Patterns
Section titled “Load Patterns”// Single asset:var handle = Addressables.LoadAssetAsync<Texture2D>("bg_texture");yield return handle;Texture2D bg = handle.Result;Addressables.Release(handle); // CRITICAL: always release
// Instantiate GameObject:var handle = Addressables.InstantiateAsync("enemy_prefab", pos, rot, parent);yield return handle;Addressables.ReleaseInstance(handle.Result); // Release when done
// Batch by label:var handle = Addressables.LoadAssetsAsync<Sprite>("ui", null);yield return handle;Addressables.Release(handle);
// Inspector reference:[SerializeField] AssetReference characterModel;var handle = characterModel.LoadAssetAsync<GameObject>();yield return handle;Instantiate(handle.Result);characterModel.ReleaseAsset();
// Scene loading:var handle = Addressables.LoadSceneAsync("level_01", LoadSceneMode.Single);yield return handle;Addressables.UnloadSceneAsync(handle);Loading Methods
Section titled “Loading Methods”| Method | Use Case | Return |
|---|---|---|
LoadAssetAsync<T>(key) | Single asset | AsyncOperationHandle<T> |
InstantiateAsync(key) | GameObject | AsyncOperationHandle<GameObject> |
LoadAssetsAsync<T>(labels, cb, merge) | Batch by label | AsyncOperationHandle<IList<T>> |
LoadSceneAsync(address) | Scene | AsyncOperationHandle<SceneInstance> |
Setup & Groups
Section titled “Setup & Groups”- Inspector: Check “Addressable” on asset, set address + group + labels
- Window > Asset Management > Addressables > Groups — organize assets
- Packing: Pack Together (one bundle) / Pack Separately (per-asset)
- Profiles: Local (shipped) vs Remote (CDN with
[BuildTarget]variable)
Labels & Batch Loading
Section titled “Labels & Batch Loading”// Union — assets with ANY label:Addressables.LoadAssetsAsync<GameObject>(new[] { "ui", "fx" }, null, MergeMode.Union);
// Intersection — assets with ALL labels:Addressables.LoadAssetsAsync<GameObject>(new[] { "ui", "common" }, null, MergeMode.Intersection);Memory Management
Section titled “Memory Management”- Bundle unloads only when ref count = 0
- Multiple assets from same bundle: all must release before memory freed
- Avoid load/release churn in hot paths — load once, reuse
Resources.UnloadUnusedAssets()— slow (50-100ms), loading screens only
Content Updates
Section titled “Content Updates”var check = Addressables.CheckForCatalogUpdates(autoRelease: false);yield return check;if (check.Result.Count > 0) { yield return Addressables.UpdateCatalogs(check.Result);}Addressables.Release(check);Editor: Build > Update a Previous Build — only changed bundles regenerated.
Migration from Resources.Load
Section titled “Migration from Resources.Load”// OLD: var tex = Resources.Load<Texture2D>("textures/bg");// NEW:var handle = Addressables.LoadAssetAsync<Texture2D>("bg_texture");yield return handle;Texture2D tex = handle.Result;Addressables.Release(handle);Hard rules
Section titled “Hard rules”- Unmatched Load/Release: Lost handle = permanent memory leak
- Partial bundle unload: One asset released doesn’t free bundle if others loaded
- Asset churn: Repeated load/release in loops — load once, reuse handle
- Label explosion: Too many label combos = too many bundles. Plan early (2-3 per asset)
- Diagnostics: Enable in Settings > Diagnostics to debug load failures
- Runtime core + addressable UI double init: If an addressable UI depends on a separate runtime core prefab, initialize shared pools/controllers once in the core and make the UI
Init()skip them when the core is already initialized. Re-running pool init can duplicate generated item instances/children and make inventory icons or equipped slots render incorrectly. - Scene UI used as data catalog: Before lazy-loading/removing a scene UI prefab, grep for static resolvers and serialized references to its child components. If other systems use UI cells as sprite/data sources, warm the Addressable after the permitted lifecycle event or route those flows through async load before dereferencing.
- Editor automation exit behavior: Batch extraction helpers may call
EditorApplication.Exit(1)only whenApplication.isBatchMode; menu-driven Editor workflows should log errors and keep Unity open so users do not lose unsaved work. - Batchmode project lock: Unity batchmode cannot open a project already open in another Unity instance. Detect and ask before killing editor processes; never remove lock files as a shortcut.
- Bootstrap chicken-and-egg — settings must exist before group-creation tools run: Any project-side migration menu item (e.g.,
Tools/Addressables/Create All Demo Groups) typically callsAddressableAssetSettingsDefaultObject.GetSettings(create: false)and aborts with a “Addressables not initialized” modal if the asset is missing. Viat1k unity menuthis looks like a timeout (the modal blocks the Editor), not a clear error. Always bootstrap the settings asset FIRST before invoking any group-creation tool:Then re-run the migration menu item (or invoke it directly via reflection — see gotcha 11).// via `t1k unity eval --file bootstrap.cs`var t = System.AppDomain.CurrentDomain.GetAssemblies().SelectMany(a => a.GetTypes()).First(x => x.FullName == "UnityEditor.AddressableAssets.AddressableAssetSettingsDefaultObject");var settings = t.GetMethod("GetSettings", new[] { typeof(bool) }).Invoke(null, new object[] { true });UnityEditor.AssetDatabase.SaveAssets(); - Modal-blocked menu items:
t1k unity menublocks on any modal the menu raises (confirmation dialogs, “missing settings” warnings, file pickers). The call will time out (exit 7,editor-busy-or-modal), not return a clear error. When you’ve ruled out long-running work as the cause, suspect a modal — fall back tot1k unity evaland invoke the menu’s underlying static method via reflection (most editor tools delegate to aprivate staticworker that bypasses any UI gate). - Duplication is a group-placement problem. An asset referenced from N
Pack Togethergroups ships N times; only one shared group both reference fixes it (a second explicit entry still duplicates). Prove a bundle is loaded (server log / call site) before optimizing it, exclude an unused group viaIncludeInBuildrather than deleting it, and read the shippedUnityFScompression header, not the schema. Audit recipes:references/bundle-hygiene.md.
Library Convention — Addressables-First (unity-dots-library v2.0.0+)
Section titled “Library Convention — Addressables-First (unity-dots-library v2.0.0+)”Since unity-dots-library v2.0.0 (2026-05-23) the library is Addressables-only for all prefab/asset wiring. Consumer projects that depend on the library MUST follow this contract:
- Authoring fields: use
AssetReferenceGameObject(or otherAssetReference*) — never[SerializeField] GameObjectfor runtime-instantiated content. - Bake helper (SSOT):
AssetReferenceBakerExtensions.BakeAssetReference(ref Baker, AssetReferenceGameObject)lives incom.the1studio.dots-core. Bakers MUST call it instead of hand-rolling weak-reference baking. - Enforcement gate:
DOTSCore.Tests.Addressables.AddressablesEnforcementTestsfails the build on anyResources.Load(,AssetDatabase.LoadAssetAtPath, or non-ECSObject.Instantiate(GameObject)in Runtime asmdefs outside the per-project allowlist. - Allowlist: legitimate Mono-UI
Instantiatecarve-outs go in the consumer project’sAssets/Editor/AddressablesEnforcement.Allowlist.cswithFile+Lineentries citing the audit finding. - Build hook required: consumer projects MUST ship an
AddressablesBuildPlayerProcessoror the Android APK ships an empty catalog → runtimeInvalidKeyException. - See the consumer project’s
CLAUDE.md§ “Addressables Mandate” andPackages/unity-dots-library/MIGRATION.mdfor the full consumer upgrade procedure.
Related Skills & Agents
Section titled “Related Skills & Agents”t1k-unity-mobile-build-size— weighing and censusing the built bundle set (artifact-census.mdship-twice detection)t1k-unity-base-scene-management— Addressable scene loadingt1k-unity-mobile-core— Remote content delivery optimizationt1k-unity-base-save-system— Saving asset referencest1k-unity-dots-rendering-graphics— ECS mesh/material loading via Addressables
Reference Files
Section titled “Reference Files”| File | Contents |
|---|---|
references/bundle-hygiene.md | Prove a load, exclude unused groups, find duplicated implicit deps, read buildlayout and the shipped compression header |