Skip to content

t1k:unity:base:addressables

FieldValue
Modulebase
Version5.116.6
Efforthigh
Tools—

Keywords: addressables, asset management, loading

/t1k:unity:base:addressables

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.

// 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);
MethodUse CaseReturn
LoadAssetAsync<T>(key)Single assetAsyncOperationHandle<T>
InstantiateAsync(key)GameObjectAsyncOperationHandle<GameObject>
LoadAssetsAsync<T>(labels, cb, merge)Batch by labelAsyncOperationHandle<IList<T>>
LoadSceneAsync(address)SceneAsyncOperationHandle<SceneInstance>
  1. Inspector: Check “Addressable” on asset, set address + group + labels
  2. Window > Asset Management > Addressables > Groups — organize assets
  3. Packing: Pack Together (one bundle) / Pack Separately (per-asset)
  4. Profiles: Local (shipped) vs Remote (CDN with [BuildTarget] variable)
// 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);
  • 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
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.

// 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);
  1. Unmatched Load/Release: Lost handle = permanent memory leak
  2. Partial bundle unload: One asset released doesn’t free bundle if others loaded
  3. Asset churn: Repeated load/release in loops — load once, reuse handle
  4. Label explosion: Too many label combos = too many bundles. Plan early (2-3 per asset)
  5. Diagnostics: Enable in Settings > Diagnostics to debug load failures
  6. 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.
  7. 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.
  8. Editor automation exit behavior: Batch extraction helpers may call EditorApplication.Exit(1) only when Application.isBatchMode; menu-driven Editor workflows should log errors and keep Unity open so users do not lose unsaved work.
  9. 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.
  10. 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 calls AddressableAssetSettingsDefaultObject.GetSettings(create: false) and aborts with a “Addressables not initialized” modal if the asset is missing. Via t1k unity menu this 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:
    // 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();
    Then re-run the migration menu item (or invoke it directly via reflection — see gotcha 11).
  11. Modal-blocked menu items: t1k unity menu blocks 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 to t1k unity eval and invoke the menu’s underlying static method via reflection (most editor tools delegate to a private static worker that bypasses any UI gate).
  12. Duplication is a group-placement problem. An asset referenced from N Pack Together groups 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 via IncludeInBuild rather than deleting it, and read the shipped UnityFS compression 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 other AssetReference*) — never [SerializeField] GameObject for runtime-instantiated content.
  • Bake helper (SSOT): AssetReferenceBakerExtensions.BakeAssetReference(ref Baker, AssetReferenceGameObject) lives in com.the1studio.dots-core. Bakers MUST call it instead of hand-rolling weak-reference baking.
  • Enforcement gate: DOTSCore.Tests.Addressables.AddressablesEnforcementTests fails the build on any Resources.Load(, AssetDatabase.LoadAssetAtPath, or non-ECS Object.Instantiate(GameObject) in Runtime asmdefs outside the per-project allowlist.
  • Allowlist: legitimate Mono-UI Instantiate carve-outs go in the consumer project’s Assets/Editor/AddressablesEnforcement.Allowlist.cs with File+Line entries citing the audit finding.
  • Build hook required: consumer projects MUST ship an AddressablesBuildPlayerProcessor or the Android APK ships an empty catalog → runtime InvalidKeyException.
  • See the consumer project’s CLAUDE.md § “Addressables Mandate” and Packages/unity-dots-library/MIGRATION.md for the full consumer upgrade procedure.
  • t1k-unity-mobile-build-size — weighing and censusing the built bundle set (artifact-census.md ship-twice detection)
  • t1k-unity-base-scene-management — Addressable scene loading
  • t1k-unity-mobile-core — Remote content delivery optimization
  • t1k-unity-base-save-system — Saving asset references
  • t1k-unity-dots-rendering-graphics — ECS mesh/material loading via Addressables
FileContents
references/bundle-hygiene.mdProve a load, exclude unused groups, find duplicated implicit deps, read buildlayout and the shipped compression header