unity-addressables

Unity Addressables

Deep decision framework for asset loading and memory management in Unity. Covers when to adopt Addressables over Resources or direct references, group design, async loading with AsyncOperationHandle, memory lifecycle (load → use → release), ref-counting patterns, and content update workflows via CCD. Untracked handles are the most common source of memory leaks in Addressables projects.

When to Apply

Activate when the conversation involves:

• Deciding whether to use Addressables, Resources, or direct serialized references for an asset
• Loading or instantiating an asset at runtime from a path or label
• Tracking and releasing AsyncOperationHandle instances to avoid memory leaks
• Designing Addressable groups (by scene, feature, update frequency)
• Preloading assets before a scene or gameplay segment begins
• Streaming downloadable content or supporting remote catalogs
• Diagnosing unexpectedly high memory from loaded-but-unreleased assets

Do NOT activate for in-scene prefab wire-up where the asset is always needed and always loaded — that belongs to hades:prefab-architecture. For questions about how scenes themselves are structured and loaded, see hades:scene-architecture.

Project Context Check

Before making recommendations, gather project-specific context so advice is calibrated to the actual codebase.

1. Check if Addressables is already in use:

   • Call search_by_name("*AddressableAsset*") — finds AddressableAssetSettings, AddressableAssetGroup, and AddressableAssetData files. If none exist, the project has not adopted Addressables yet; adjust the scope of advice accordingly.
   • Call graph_query(edgeKind: "references", edgeTargetNamePattern: "AssetReference", edgeTargetKind: "Class") — locates MonoBehaviours with AssetReference fields, indicating Addressables is already wired into gameplay code.

2. Assess project scale:

   • Call get_project_summary() — reveals total asset count, scene count, and build targets. Addressables provide the most value in large projects (many assets) or projects with remote content. Small prototypes rarely justify the setup cost.