Unity Addressables

Ce que fait cette skill

Guider l'utilisation du systeme Addressables pour le chargement d'assets asynchrone, l'organisation en groupes, la gestion memoire et le contenu distant (CDN/DLC). Couvre la migration depuis Resources.Load, le preloading avec progression, le reference counting et les patterns de release pour eviter les memory leaks.

Prerequis

• Package com.unity.addressables installe via Package Manager

Demarrage rapide

1. Installer le package : Window > Package Manager > Unity Registry > Addressables
2. Ouvrir Window > Asset Management > Addressables > Groups
3. Marquer des assets comme "Addressable" (checkbox dans l'Inspector)
4. Organiser en groupes logiques (par feature, par scene, par download)
5. Charger avec Addressables.LoadAssetAsync<T>

Arbre de decision

Comment charger cet asset ?
|
+-- Toujours en memoire, reference directe dans l'Inspector ?
|   --> Reference directe [SerializeField] (pas besoin d'Addressables)
|
+-- Charge a la demande, connu au compile-time ?
|   --> AssetReference dans l'Inspector + LoadAssetAsync
|
+-- Charge dynamiquement par label/nom ?
|   --> Addressables.LoadAssetsAsync avec label
|
+-- Contenu telechargeable (DLC, patches) ?
|   --> Remote group + catalog update
|
+-- Migration depuis Resources.Load ?
    --> Marquer les assets comme Addressable, remplacer Resources.Load par LoadAssetAsync

Guide etape par etape

Step 1 : Organisation des groupes

• Groupe par feature : Characters, Levels, UI, Audio
• Groupe par download : Core (inclus dans le build), Optional (telechargeable)
• Groupe par scene si loading par scene
• Eviter les groupes trop gros (> 50 MB) : splitter en sous-groupes par usage
• Utiliser les labels pour tagger les assets transversaux (level1, boss, tutorial)

Step 2 : Chargement async avec handle

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

public class AssetLoader : MonoBehaviour
{
    [SerializeField] private AssetReference prefabRef;
    private AsyncOperationHandle<GameObject> handle;

    public async Awaitable<GameObject> LoadAndInstantiateAsync()
    {
        handle = Addressables.LoadAssetAsync<GameObject>(prefabRef);
        await handle.Task;

        if (handle.Status == AsyncOperationStatus.Succeeded)
            return Instantiate(handle.Result);

        Debug.LogError($"Failed to load: {prefabRef}");
        return null;
    }

    private void OnDestroy()
    {
        // CRITIQUE: toujours release le handle
        if (handle.IsValid())
            Addressables.Release(handle);
    }
}

Points cles :

• AssetReference dans l'Inspector evite les magic strings
• await handle.Task pour attendre le chargement
• Toujours verifier handle.Status avant d'utiliser handle.Result
• Release dans OnDestroy pour eviter les leaks

Step 3 : Chargement par label

public class LabelLoader : MonoBehaviour
{
    [SerializeField] private AssetLabelReference labelRef;
    private AsyncOperationHandle<IList<GameObject>> handle;

    public async Awaitable<IList<GameObject>> LoadAllAsync()
    {
        handle = Addressables.LoadAssetsAsync<GameObject>(labelRef, null);
        await handle.Task;

        if (handle.Status == AsyncOperationStatus.Succeeded)
            return handle.Result;

        Debug.LogError($"Failed to load label: {labelRef}");
        return null;
    }

    private void OnDestroy()
    {
        if (handle.IsValid())
            Addressables.Release(handle);
    }
}

Step 4 : Migration Resources.Load vers Addressables

// AVANT (synchrone, tout en memoire au build)
var prefab = Resources.Load<GameObject>("Enemies/Goblin");

// APRES (async, charge a la demande)
var handle = Addressables.LoadAssetAsync<GameObject>("Enemies/Goblin");
await handle.Task;
var prefab = handle.Result;
// ... utiliser prefab ...
Addressables.Release(handle);

Etapes de migration :

1. Deplacer les assets hors du dossier Resources/
2. Marquer chaque asset comme Addressable (Inspector checkbox)
3. Verifier que l'address correspond a l'ancien path Resources/
4. Remplacer Resources.Load<T>(path) par Addressables.LoadAssetAsync<T>(address)
5. Ajouter Release() quand l'asset n'est plus necessaire
6. Supprimer le dossier Resources/ une fois la migration terminee

Step 5 : Scenes Addressables

using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.ResourceProviders;

public class SceneLoader : MonoBehaviour
{
    [SerializeField] private AssetReference sceneRef;
    private AsyncOperationHandle<SceneInstance> sceneHandle;

    public async Awaitable LoadSceneAsync()
    {
        sceneHandle = Addressables.LoadSceneAsync(sceneRef);
        await sceneHandle.Task;
    }

    public async Awaitable UnloadSceneAsync()
    {
        if (sceneHandle.IsValid())
        {
            await Addressables.UnloadSceneAsync(sceneHandle).Task;
        }
    }
}

Regles strictes

• TOUJOURS appeler Addressables.Release(handle) quand l'asset n'est plus necessaire
• TOUJOURS utiliser AssetReference dans l'Inspector (pas de string addresses en dur)
• TOUJOURS gerer le cas d'echec de chargement (handle.Status)
• TOUJOURS utiliser Addressables.ReleaseInstance() au lieu de Destroy() pour les objets crees via InstantiateAsync
• JAMAIS de Resources.Load dans un nouveau projet (utiliser Addressables)
• JAMAIS garder un handle sans le release (memory leak)
• JAMAIS charger le meme asset deux fois sans reference counting
• PREFERER AssetReferenceT<T> pour typer les references (AssetReferenceGameObject, AssetReferenceSprite, etc.)
• PREFERER AssetLabelReference dans l'Inspector plutot que des strings de labels

Skills connexes

• /perf-audit : detecter memory leaks et assets non release
• /unity-build-config : build content et remote catalog
• /unity-code-gen : generer loading system et asset managers

Troubleshooting