Unity Addressables Assets

Unity Addressables & Asset Management

Retrieval Sources

Local doc coverage for this topic is uneven and re-verified on disk as of this pass. The Addressables package ships its own separate documentation set (hosted at docs.unity3d.com/Packages/com.unity.addressables@.../) that is not mirrored in this local copy — only two thin package-overview pages exist in Manual/ (830 and 702 words respectively, both landing-page-style descriptions with no API tables, no code samples, and no cross-links to AsyncOperationHandle, AssetReference, ResourceLocator, or any other Addressables type). There is no local ScriptReference/ coverage at all for the UnityEngine.AddressableAssets or UnityEngine.ResourceManagement namespaces — confirmed by directory listing, zero Addressables.*.html or AsyncOperationHandle.*.html files exist anywhere under ScriptReference/.

By contrast, the legacy AssetBundle system (the substrate Addressables is built on) has deep, current, real coverage: 19 Manual pages plus well over 100 ScriptReference pages, all present under /media/artiq/FRESH_DRIVE/Books/Unity6/Documentation/en/ and confirmed via wc -w to contain substantive prose (700–2,200 words each), not stubs. The Resources system (the third leg of Unity asset loading) also has real Manual + ScriptReference coverage. Treat local retrieval as authoritative for AssetBundles, Resources, and Caching; treat it as absent for Addressables API specifics — those answers below are drawn from accurate pretrained knowledge and are labeled as such wherever used.

Key Guidelines

Addressables Concepts (pretrained knowledge — local docs are a thin stub, flagged explicitly)

Everything in this subsection comes from accurate pretrained knowledge of the com.unity.addressables package, not from local retrieval — the local docs do not cover it beyond a one-paragraph overview, so verify against docs.unity3d.com/Packages/com.unity.addressables@latest or in-Editor API docs before shipping. Addressables is a content-management layer built on top of AssetBundles (and, for local-only content, direct asset references) that lets you reference an asset by a string key or label instead of a hard scene/inspector reference, resolve it asynchronously at runtime, and have Unity manage ref-counting, dependency loading, and (optionally) remote hosting for you. Content is organized into Addressable Groups, each of which maps to build settings — local vs. remote, which bundle(s) it packs into, compression — so you can, for example, ship core content in the player build while hosting a DLC group on a CDN that updates independently of app store releases. Every asynchronous Addressables call (LoadAssetAsync, InstantiateAsync, LoadSceneAsync, DownloadDependenciesAsync) returns an AsyncOperationHandle (or the generic AsyncOperationHandle<T>), which is a ref-counted handle: each successful load increments an internal reference count for that asset and its dependencies, and the count must be decremented with a matching Addressables.Release(handle) (or Addressables.ReleaseInstance for InstantiateAsync results) or the asset — and everything it depends on — stays resident. Because the count is reference-based rather than GC-based, a leaked handle is invisible to the Unity Profiler's normal GC pressure view; it shows up only as elevated resident memory in the Addressables/Memory profiler modules.

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

public class AddressableLoader : MonoBehaviour
{
    AsyncOperationHandle<GameObject> _handle;

    async void Start()
    {
        _handle = Addressables.LoadAssetAsync<GameObject>("Enemies/Goblin");
        await _handle.Task;

        if (_handle.Status == AsyncOperationStatus.Succeeded)
        {
            Instantiate(_handle.Result, transform.position, Quaternion.identity);
        }
        else
        {
            Debug.LogError($"Failed to load addressable: {_handle.OperationException}");
        }
    }

    void OnDestroy()
    {
        // Symmetric release — required even on a Succeeded handle, or the
        // asset (and its dependency bundles) never unload.
        if (_handle.IsValid())
            Addressables.Release(_handle);
    }
}

Legacy AssetBundles — Building & Organizing (from real local docs)

BuildPipeline.BuildAssetBundles is the entry point for building the legacy system; it consumes the AssetBundle names/variants assigned to assets (via the Inspector's AssetBundle dropdown or AssetImporter.SetAssetBundleNameAndVariant) and a BuildAssetBundleOptions flag set, and writes .bundle files plus a top-level manifest bundle to the output folder. Per Manual/AssetBundles-Preparing.html, there are hard organizational constraints: you cannot combine scenes and non-scene assets in one bundle, you cannot include script assets or files already under StreamingAssets in a bundle, and an asset can only belong to one AssetBundle — if two bundles both need it and it isn't given its own bundle, Unity duplicates it into both, inflating total download size. Builds are incremental by default: Unity computes an IncrementalBuildHash per bundle from build inputs (assets, dependencies, target platform, platform-specific settings) and only rebuilds a bundle when that hash — or a secondary TypeTreeHash covering serialization-format changes — differs from the previous build's .manifest file. BuildAssetBundleOptions.ForceRebuildAssetBundle bypasses this cache entirely; IgnoreTypeTreeChanges skips only the secondary check. Because the incremental hash doesn't cover every possible build influence, treat "clean forced rebuild" as the reliable fallback whenever a bundle seems stale despite no apparent input changes.

using UnityEditor;
using UnityEngine;
using System.IO;

public static class BundleBuilder
{
    [MenuItem("Tools/Build AssetBundles")]
    static void BuildAllBundles()
    {
        string outputPath = "Assets/StreamingAssets/AssetBundles";
        if (!Directory.Exists(outputPath))
            Directory.CreateDirectory(outputPath);

        BuildPipeline.BuildAssetBundles(
            outputPath,
            BuildAssetBundleOptions.ChunkBasedCompression, // LZ4, good default for StreamingAssets
            EditorUserBuildSettings.activeBuildTarget);
    }
}

Legacy AssetBundles — Loading & Dependency Management (from real local docs)

Manual/AssetBundles-Native.html documents the full load surface: AssetBundle.LoadFromFile/LoadFromFileAsync for local disk paths (fastest — memory-maps rather than copies), LoadFromMemory/LoadFromMemoryAsync for an in-memory byte array (e.g., after custom decryption), LoadFromStream/LoadFromStreamAsync for a Stream, and UnityWebRequestAssetBundle.GetAssetBundle for remote or cache-backed loading over HTTP. Once a bundle handle is open, individual assets are pulled with AssetBundle.LoadAsset/LoadAssetAsync (single) or LoadAllAssets/LoadAllAssetsAsync (everything in the bundle). Per Manual/AssetBundles-Dependencies.html, bundles become dependent on one another whenever an object in bundle A references an object living in bundle B; if that referenced object isn't itself assigned to a bundle, Unity silently embeds a copy into every dependent bundle instead of erroring, which is a common unexpected size blow-up. AssetBundleManifest (obtained by loading the top-level manifest bundle that BuildAssetBundles always emits alongside the content bundles) exposes GetAllDependencies(bundleName) and GetDirectDependencies(bundleName) so you can load a bundle's full dependency chain before loading the bundle itself — loading out of order produces missing-reference assets rather than an explicit error.

using UnityEngine;
using System.Collections;
using System.IO;

public class DependencyAwareLoader : MonoBehaviour
{
    IEnumerator LoadWithDependencies(string bundleName, string bundleDir)
    {
        // Manifest bundle is named after the output folder itself.
        var manifestBundle = AssetBundle.LoadFromFile(
            Path.Combine(bundleDir, Path.GetFileName(bundleDir)));
        var manifest = manifestBundle.LoadAsset<AssetBundleManifest>("AssetBundleManifest");

        foreach (string dep in manifest.GetAllDependencies(bundleName))
        {
            if (AssetBundle.GetAllLoadedAssetBundles() == null) { }
            AssetBundle.LoadFromFile(Path.Combine(bundleDir, dep));
        }

        var request = AssetBundle.LoadFromFileAsync(Path.Combine(bundleDir, bundleName));
        yield return request;

        AssetBundle bundle = request.assetBundle;
        if (bundle == null)
        {
            Debug.LogError($"Failed to load bundle {bundleName}");
            yield break;
        }

        var assetRequest = bundle.LoadAssetAsync<GameObject>("Player");
        yield return assetRequest;
        Instantiate(assetRequest.asset as GameObject);
    }
}

Legacy AssetBundles — Caching, Compression & Integrity (from real local docs)

Unity's built-in disk cache (Manual/assetbundles-caching.html) intercepts bundles downloaded via UnityWebRequestAssetBundle and stores them re-encoded as LZ4 for fast subsequent loads, regardless of the original build compression — unless Caching.compressionEnabled is false, in which case bundles are cached uncompressed. The Caching class lets you inspect (IsVersionCached), pin (MarkAsUsed), and evict (ClearCache, ClearCachedVersion, ClearAllCachedVersions) cached versions, and supports multiple cache locations via Caching.AddCache/GetAllCachePaths. Per Manual/assetbundles-compression-format.html, there are three build-time compression choices: LZMA (default, smallest download but must decompress the whole archive before any object can be read — slow first access, and per Manual/assetbundles-platforms.html explicitly discouraged for StreamingAssets bundles because decompressing to a temp file is wasteful there), LZ4 (ChunkBasedCompression, chunk-based so individual objects can be decompressed on demand — the cache's own re-encoding target, and the generally recommended default), and uncompressed (UncompressedAssetBundle, largest on disk, fastest to open, 16-byte aligned). Manual/AssetBundles-Integrity.html covers verification: UnityWebRequestAssetBundle.GetAssetBundle overloads accept a hash or CRC to validate downloaded content and trigger a re-download when a newer version is requested, but Unity has no built-in differential patching — every update re-downloads the full bundle; a patching system must track local vs. server version lists itself and diff them to decide what to re-fetch.

using UnityEngine;
using UnityEngine.Networking;
using System.Collections;

public class RemoteBundleLoader : MonoBehaviour
{
    IEnumerator LoadRemote(string url, Hash128 hash)
    {
        // Cache-aware: skips the download entirely if this hash is already cached.
        using UnityWebRequest req = UnityWebRequestAssetBundle.GetAssetBundle(url, hash, 0);
        yield return req.SendWebRequest();

        if (req.result != UnityWebRequest.Result.Success)
        {
            Debug.LogError($"Bundle download failed: {req.error}");
            yield break;
        }

        AssetBundle bundle = DownloadHandlerAssetBundle.GetContent(req);
        Debug.Log($"Loaded {bundle.name}, cached: {Caching.IsVersionCached(url, hash)}");
    }
}

Legacy AssetBundles — Memory & Unloading (from real local docs)

Manual/assetbundles-optimizing.html describes what a loaded AssetBundle actually occupies: a loading cache of recently accessed file pages (sized by AssetBundle.memoryBudgetKB), and TypeTrees (serialization metadata, kept resident for the life of the bundle unless stripped at build time with BuildAssetBundleOptions.DisableWriteTypeTree). Unloading has two very different modes: AssetBundle.Unload(false) frees only the compressed archive and loading-cache memory — any objects already instantiated or loaded from the bundle remain fully resident and usable, which is correct when you plan to keep using loaded assets but don't need the bundle handle anymore. AssetBundle.Unload(true) additionally destroys every asset object that came from the bundle, including ones still referenced by live GameObjects, which is the source of the single most common AssetBundle bug (see Common Mistakes). AssetBundle.UnloadAsync performs the same work spread across frames to avoid a hitch on bundles with many objects.

using UnityEngine;

public class BundleUnloadExample : MonoBehaviour
{
    AssetBundle _bundle;
    GameObject _spawnedPrefabInstance;

    void OnDisable()
    {
        if (_bundle == null) return;

        // Safe pattern: destroy consumers of the bundle's assets FIRST,
        // then Unload(true) once nothing references bundle-owned objects.
        if (_spawnedPrefabInstance != null)
            Destroy(_spawnedPrefabInstance);

        _bundle.Unload(true);
        _bundle = null;
    }
}

Resources Folder Tradeoffs (from real local docs)

Manual/assets-resources-system-load.html documents the mechanism plainly: any asset placed under a folder literally named Resources (you can have several, in different subfolders, and packages can ship their own) is loaded by calling Resources.Load<T>("path/relative/to/Resources/without/extension"). The tradeoff is structural, not just stylistic: everything under any Resources/ folder is force-included in the build and indexed at build time regardless of whether it's ever referenced by a scene, so it inflates both build size and the startup asset-index cost, and unlike AssetBundles/Addressables it offers no fine-grained partial unload — Resources.UnloadAsset frees one asset object, but the folder's build-time inclusion cost is already paid. Resources.UnloadUnusedAssets is a broader, expensive, asynchronous sweep that should not be called every frame.

using UnityEngine;

public class LoadFromResources : MonoBehaviour
{
    public Renderer targetRenderer;
    Texture2D _loadedTexture;

    void Start()
    {
        _loadedTexture = Resources.Load<Texture2D>("Textures/MyTexture");
        if (_loadedTexture != null)
            targetRenderer.material.mainTexture = _loadedTexture;
    }

    void OnDestroy()
    {
        if (_loadedTexture != null)
        {
            Resources.UnloadAsset(_loadedTexture);
            _loadedTexture = null;
        }
    }
}

Remote Content Delivery

For AssetBundles, Manual/assetbundles-platforms.html describes hosting bundles on a plain web server and pulling them with UnityWebRequestAssetBundle, or using Unity's Cloud Content Delivery (CCD) service, which the docs note integrates well with Addressables specifically for large, dynamic content sets. Console platforms typically don't fetch bundles directly over the web from in-game code at all — they're delivered through the platform's own DLC/store mechanism instead. On Android, bundles can be packaged into Google Play's native asset-pack format for store-managed delivery. For Addressables (pretrained knowledge, not locally documented), the equivalent mechanism is a remote catalog: you build a "Remote" content profile, host the generated catalog JSON plus its content bundles on a CDN or CCD bucket, and point the player's RuntimeSettings/catalog URL at that host — Addressables checks the remote catalog hash against the cached one (Addressables.CheckForCatalogUpdates / UpdateCatalogs) and only re-downloads bundles whose content hash changed, giving you post-release content or DLC updates without an app-store resubmission, layered on top of the exact same UnityWebRequestAssetBundle + Caching machinery described above.

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

public class RemoteCatalogUpdater : MonoBehaviour
{
    async void Start()
    {
        var checkHandle = Addressables.CheckForCatalogUpdates(false);
        List<string> catalogsToUpdate = await checkHandle.Task;
        Addressables.Release(checkHandle);

        if (catalogsToUpdate.Count > 0)
        {
            var updateHandle = Addressables.UpdateCatalogs(catalogsToUpdate);
            await updateHandle.Task;
            Addressables.Release(updateHandle);
            Debug.Log("Remote catalogs updated — new/changed remote content is now resolvable.");
        }
    }
}

Common Mistakes

Quick Reference

Advanced Notes

Memory management strategy: Addressables vs. Resources vs. AssetBundles. All three systems ultimately manage the same tradeoff — build size vs. load latency vs. runtime memory vs. update flexibility — but they sit at different layers and are not interchangeable defaults.

• Resources/ is the least flexible: everything under it is force-included in every build and indexed at build time whether or not it's ever loaded, and there is no partial/fine-grained unload — only whole-asset (UnloadAsset) or whole-project sweep (UnloadUnusedAssets). Its only real advantage is zero setup and guaranteed availability (no async download step, no missing-bundle failure mode). Reserve it for a small, fixed set of assets that must always be present regardless of build configuration — e.g. a fallback error material, a bootstrap config asset, or content referenced from code paths that run before any content-management system has initialized. Anything whose presence is conditional (per-platform, per-DLC, per-locale, "optional cosmetic content") does not belong here, because Resources content ships in every build variant unconditionally.

• Legacy AssetBundles are the correct choice when you need low-level control that Addressables' abstraction would get in the way of: custom patching/delta-update logic, non-standard hosting infrastructure, tight console platform DLC integration, or a codebase old enough (pre-Addressables, or migrating off it) that the investment in the newer package isn't justified. They demand you hand-manage the entire lifecycle yourself — bundle naming, dependency load order via AssetBundleManifest, cache versioning, and unload discipline (Unload(true) vs Unload(false)) — which is real ongoing engineering cost but buys full transparency: you can see and control exactly what's resident in memory at any moment, which matters on memory-constrained platforms (mobile, some consoles) where the automatic ref-counting of Addressables can obscure exactly why something is still resident.

• Addressables is correct for the common case: any project shipping optional, remote-updatable, or large/varied content (levels, character packs, seasonal cosmetics, localized voice-over) benefits from its automatic dependency resolution, ref-counted lifecycle, and unified local/remote key-based API. The cost is an added abstraction layer — when something leaks or won't unload, you're debugging the ref-count semantics of AsyncOperationHandle rather than a bundle you loaded yourself, and the local documentation gap noted above means you'll lean on pretrained knowledge or the public package docs more than for AssetBundles.

Decision framework: ask (1) is this asset always needed regardless of build/platform/DLC configuration, with negligible size? → Resources. (2) Do I need custom patching, non-standard hosting, or console-store-managed DLC that Addressables' remote-catalog model doesn't fit? → legacy AssetBundles, built directly with BuildPipeline.BuildAssetBundles. (3) Everything else — optional content, remote-updatable content, anything organized around "load this by name/label when needed and free it later" → Addressables. In practice, most modern Unity 6 projects should default to Addressables for all optional/streamed content, use Resources/ only for the small always-resident bootstrap set, and reach for hand-rolled AssetBundles only when a specific platform or pipeline constraint rules Addressables out — since Addressables itself is built on AssetBundles under the hood, understanding the AssetBundle-layer guidance above (dependency load order, Unload(true) semantics, compression choice, caching) directly explains what Addressables is doing for you automatically, and is essential for diagnosing Addressables memory issues even though the two are used through very different APIs.