/addressables

name: addressables
description: "Addressables asset loading — LoadAssetAsync, handle lifecycle, labels, remote catalogs, memory management. Use for asset loading and memory optimization."
globs: ["**/Addressable*.cs", "**/*Address*"]

Unity Addressables

Setup

1. Install via Package Manager: `com.unity.addressables` 2. Mark assets as Addressable in the Inspector checkbox 3. Organize into Groups (local, remote, by scene, by feature) 4. Assign Labels for batch loading (e.g., "level1", "enemies", "ui")

Group Organization Strategy

Groups:
  Local_Static       -- Core assets, always available (shaders, essential UI)
  Local_Dynamic      -- Assets that change between builds
  Remote_Levels      -- Level-specific assets, downloaded on demand
  Remote_Characters  -- Character models/animations

Loading Assets

Basic Asset Loading

using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;

public class AddressableLoader : MonoBehaviour
{
    [SerializeField] private AssetReference prefabReference;

    private AsyncOperationHandle<GameObject> _loadHandle;
    private GameObject _instance;

    public async void LoadAndInstantiate()
    {
        _loadHandle = Addressables.LoadAssetAsync<GameObject>(prefabReference);
        await _loadHandle.Task;

        if (_loadHandle.Status == AsyncOperationStatus.Succeeded)
        {
            _instance = Instantiate(_loadHandle.Result);
        }
        else
        {
            Debug.LogError($"Failed to load addressable: {_loadHandle.OperationException}");
        }
    }

    // CRITICAL: Always release handles to prevent memory leaks
    private void OnDestroy()
    {
        if (_loadHandle.IsValid())
        {
            Addressables.Release(_loadHandle);
        }

        if (_instance != null)
        {
            Destroy(_instance);
        }
    }
}

InstantiateAsync (Load + Instantiate in One Call)

public class AddressableInstantiator : MonoBehaviour
{
    [SerializeField] private AssetReference prefabReference;
    private AsyncOperationHandle<GameObject> _instanceHandle;

    public async void SpawnObject(Vector3 position, Quaternion rotation)
    {
        _instanceHandle = Addressables.InstantiateAsync(prefabReference, position, rotation);
        await _instanceHandle.Task;

        if (_instanceHandle.Status != AsyncOperationStatus.Succeeded)
        {
            Debug.LogError("Failed to instantiate addressable");
        }
    }

    private void OnDestroy()
    {
        // ReleaseInstance destroys the object AND releases the handle
        if (_instanceHandle.IsValid())
        {
            Addressables.ReleaseInstance(_instanceHandle);
        }
    }
}

Handle Lifecycle (CRITICAL)

Every `LoadAssetAsync` or `InstantiateAsync` call returns a handle that MUST be released.

Rules

1. **Every load must have a matching release.** No exceptions. 2. **Track all handles.** Store them in fields or a list. 3. **Release on destroy.** Use OnDestroy or a dedicated cleanup method. 4. **Check IsValid() before releasing.** Prevents double-release errors.

Handle Tracking Pattern

using System.Collections.Generic;
using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;

public class AddressableManager : MonoBehaviour
{
    private readonly List<AsyncOperationHandle> _handles = new();

    public AsyncOperationHandle<T> LoadAsset<T>(object key)
    {
        var handle = Addressables.LoadAssetAsync<T>(key);
        _handles.Add(handle);
        return handle;
    }

    public AsyncOperationHandle<GameObject> InstantiateAsset(AssetReference reference,
        Vector3 position = default, Quaternion rotation = default)
    {
        var handle = Addressables.InstantiateAsync(reference, position, rotation);
        _handles.Add(handle);
        return handle;
    }

    public void ReleaseAll()
    {
        foreach (var handle in _handles)
        {
            if (handle.IsValid())
            {
                Addressables.Release(handle);
            }
        }
        _handles.Clear();
    }

    private void OnDestroy()
    {
        ReleaseAll();
    }
}

Label-Based Loading

Load multiple assets sharing a label in a single call.

using System.Collections.Generic;
using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;

public class LevelAssetLoader : MonoBehaviour
{
    private AsyncOperationHandle<IList<GameObject>> _levelAssetsHandle;

    public async void LoadLevelAssets(string levelLabel)
    {
        _levelAssetsHandle = Addressables.LoadAssetsAsync<GameObject>(
            levelLabel,
            prefab =>
            {
                // Called for EACH asset as it loads
                Debug.Log($"Loaded: {prefab.name}");
            });

        await _levelAssetsHandle.Task;

        if (_levelAssetsHandle.Status == AsyncOperationStatus.Succeeded)
        {
            Debug.Log($"All {_levelAssetsHandle.Result.Count} assets loaded for {levelLabel}");
        }
    }

    public void UnloadLevelAssets()
    {
        if (_levelAssetsHandle.IsValid())
        {
            Addressables.Release(_levelAssetsHandle);
        }
    }
}

Asset Reference Types

using UnityEngine;
using UnityEngine.AddressableAssets;

public class TypedReferences : MonoBehaviour
{
    // Generic reference — loads as UnityEngine.Object
    [SerializeField] private AssetReference genericRef;

    // Typed references — type-safe in Inspector
    [SerializeField] private AssetReferenceGameObject prefabRef;
    [SerializeField] private AssetReferenceTexture2D textureRef;
    [SerializeField] private AssetReferenceSprite spriteRef;
    [SerializeField] private AssetReferenceT<AudioClip> audioRef;
    [SerializeField] private AssetReferenceT<ScriptableObject> dataRef;

    // As