📦 Lesson 7.3: Addressables — Async Content Management

Why Addressables

To see the problem Addressables solves, look at the two ways you already load content and where each fails at scale.

Three concrete wins fall out of that. First, memory control: nothing loads until you ask, and it unloads the moment you release, so you hold only what's on screen. Second, remote content: assets can live on a CDN and download at runtime, so you can add or fix content without resubmitting the app. Third, decoupling: code refers to content by key, not by a hard link, so scenes stay lean and assets can move between bundles without touching a line of code.

🔎 It builds on Lesson 1.3. Every Addressables load is asynchronous — it returns immediately and completes later, because the asset may be on disk or across a network. You'll await these operations using exactly the async/await patterns from Lesson 1.3. If awaiting still feels shaky, revisit it before the code below.

Addresses, Labels & Groups

You mark an asset "Addressable" with a checkbox in its Inspector (or by dragging it into the Addressables Groups window). Doing so gives it three things:

The Addressables Groups window is where you organize all this — assets grouped into rows, each with its address and labels, and each group configured local or remote. It's a UI Toolkit window, so like the tools in the last two lessons it's reconstructed here as a diagram rather than a screenshot:

Loading Asynchronously

Loading returns an AsyncOperationHandle<T> — a handle to an in-progress operation that you await and later release. There are two things you'll load: an asset (data you keep, like a prefab or sprite) and an instance (a live GameObject in the scene). Start with loading an asset:

using System.Threading.Tasks;
using UnityEngine;
using UnityEngine.AddressableAssets;         // Addressables
using UnityEngine.ResourceManagement.AsyncOperations; // AsyncOperationHandle

public class GoblinFactory : MonoBehaviour
{
    AsyncOperationHandle<GameObject> handle;   // keep it so we can release later

    async Task LoadPrefabAsync()
    {
        // Kick off the load. Returns immediately; the work happens over time.
        handle = Addressables.LoadAssetAsync<GameObject>("Enemies/Goblin");

        // Await completion — non-blocking, like any Task (Lesson 1.3).
        GameObject prefab = await handle.Task;

        if (handle.Status == AsyncOperationStatus.Succeeded)
            Instantiate(prefab, transform.position, Quaternion.identity);
        else
            Debug.LogError("Failed to load Enemies/Goblin");
    }
}

The key you pass — "Enemies/Goblin" — is the address. You could equally pass a label to load a whole set, or an AssetReference (next section). If the asset is remote and not yet cached, this same call downloads it first; your code doesn't change. You can also subscribe instead of awaiting: handle.Completed += op => { ... }; — useful in non-async contexts.

To put a live object in the scene, use InstantiateAsync, which loads (if needed) and instantiates in one step:

// Load-and-spawn in one call. The handle here represents the *instance*.
AsyncOperationHandle<GameObject> spawnHandle =
    Addressables.InstantiateAsync("Enemies/Goblin", position, Quaternion.identity);
GameObject goblin = await spawnHandle.Task;

The Golden Rule: Release

Addressables tracks memory with reference counting. Each load increments a count on the underlying asset and its dependencies; each release decrements it. When the count hits zero, Unity unloads the asset and its bundle. Load without releasing and the count never drops — the asset stays in memory forever. This is the single most important discipline of the whole system.

void OnDestroy()
{
    // Release the ASSET load: use Addressables.Release with the handle.
    if (handle.IsValid())
        Addressables.Release(handle);
}

// For something spawned with InstantiateAsync, release the INSTANCE:
void Despawn(GameObject goblin)
{
    // ReleaseInstance destroys the GameObject *and* decrements the ref count.
    Addressables.ReleaseInstance(goblin);
}

The lifecycle below is the mental model to carry: an operation moves from load, to an awaited handle, to use, to release, and only then does memory actually free. Skip the last box and you have a leak that grows the longer the session runs.

Figure 2: The load/release lifecycle. Every load bumps a reference count; every release drops it; the asset frees only when the count reaches zero. Forgetting the release step is the classic Addressables memory leak.

AssetReference Fields

Loading by a hand-typed string works, but a typo is a runtime failure and there's no drag-and-drop. AssetReference fixes both: it's a serializable field that shows a familiar object-picker in the Inspector, yet stores an Addressables key rather than a hard reference — so assigning it does not pull the asset into memory. It's the designer-friendly way to point at Addressable content.

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

public class Spawner : MonoBehaviour
{
    // Drag an Addressable prefab here in the Inspector — stored as a key, not a hard link.
    public AssetReferenceGameObject enemyRef;

    AsyncOperationHandle<GameObject> handle;

    async void Start()
    {
        // AssetReference has its own load/instantiate helpers.
        handle = enemyRef.InstantiateAsync(transform.position, Quaternion.identity);
        await handle.Task;
    }

    void OnDestroy()
    {
        if (handle.IsValid())
            enemyRef.ReleaseInstance(handle);   // release via the reference
    }
}

AssetReference comes in typed flavours — AssetReferenceGameObject, AssetReferenceTexture, AssetReferenceSprite — that restrict the picker to the right asset type, catching mistakes at edit time. The same release rule applies: whatever you loaded or instantiated through the reference, you release. This is the field type the mini-project's level-layout asset uses to remember which Addressable each placement marker points to.

Catalogs & Remote Content

How does the runtime know that "Enemies/Goblin" maps to a particular file in a particular bundle, possibly on a server? Through a content catalog — a small JSON manifest, built alongside your bundles, that maps every address and label to its bundle and dependencies. At startup Addressables loads the catalog; from then on, any key you request is resolved through it.

When content is remote, you often want to preload it — download a level's bundles up front (behind a progress bar) so gameplay never stalls mid-scene waiting on a network fetch. That's DownloadDependenciesAsync, which downloads (and caches) everything a key or label needs without instantiating anything:

async Task PreloadLevelAsync()
{
    // Download every bundle tagged "level" into the cache, with progress.
    var handle = Addressables.DownloadDependenciesAsync("level");

    while (!handle.IsDone)
    {
        float pct = handle.PercentComplete;   // drive a loading bar
        // ... update UI ...
        await Task.Yield();
    }

    // Optional: check the total size beforehand with GetDownloadSizeAsync(key).
    Addressables.Release(handle);             // release the download op when done
}

Once dependencies are downloaded and cached, subsequent LoadAssetAsync/InstantiateAsync calls for those keys resolve from the local cache and complete quickly. Downloaded bundles persist between sessions, so you pay the network cost once. Together, remote catalogs plus DownloadDependenciesAsync are how live-service games patch content, run seasonal events, and ship optional DLC — all without a store resubmission.

💡 You don't need a server to learn this. During development, groups set to "remote" can be served from a local folder or Unity's built-in hosting service, and the catalog/download code is identical to production. Build the habits — addresses, handles, releases, preloading — locally, and they carry straight over to a real CDN.

Hands-on Challenge

public class PickupSpawner : MonoBehaviour
{
    public AssetReferenceGameObject pickupRef;
    AsyncOperationHandle<GameObject> handle;

    async void Start()
    {
        handle = pickupRef.InstantiateAsync(transform.position, Quaternion.identity);
        while (!handle.IsDone)
        {
            Debug.Log($"Loading pickup: {handle.PercentComplete:P0}");
            await Task.Yield();
        }
        if (handle.Status != AsyncOperationStatus.Succeeded)
            Debug.LogError("Pickup failed to load");
    }

    void OnDestroy()
    {
        if (handle.IsValid())
            pickupRef.ReleaseInstance(handle);   // destroys instance + drops ref count
    }
}

Summary

🚀 What's Next?

You now have both halves of this module: the ability to build Editor tools (Lessons 7.1–7.2) and to manage content asynchronously (this lesson). In Lesson 7.4: A Level-Layout Tool with Addressable Loading, you'll combine them — an EditorWindow that lists Addressable prefabs and stamps placement markers into a saved layout asset, plus a runtime loader that reads that layout and instantiates each marker's Addressable, releasing every one on unload.