Loading Assets at Runtime with Unity Addressables: Step‑by‑Step Guide

Desired outcome

Enable runtime loading of assets by address, reduce the initial player build size, and optionally update content without rebuilding the player.

Prerequisites

• Unity 2020.3 LTS or newer (any edition that supports the Package Manager).
• Addressables package version 1.19+ installed via Window → Package Manager.
• Basic familiarity with the Unity Inspector and C# scripting.
• Edit permissions on the project (to mark assets and modify scripts).

Procedure

1. Mark assets as addressable
   • In the Project window, select a prefab, texture, or other asset.
   • In the Inspector, click Addressable and then Mark as Addressable.
   • Assign a clear address string, e.g., CubePrefab.
2. Organize into groups (optional but recommended)
   • Open Window → Asset Management → Addressables → Groups.
   • Create a new group (right‑click → Create Group) and drag the marked assets into it.
   • Set the group’s Build Path to LocalBuildPath and Load Path to LocalLoadPath for local testing.
3. Build player content
   • With the Addressables window open, click Build → New Build → Default Build Script.
   • Unity will generate asset bundles based on the groups and place them in the Library/com.unity.addressables folder.
   • Note: This step is platform‑specific; repeat if you change the target platform.
4. Load the asset at runtime
   • Create a C# script (e.g., AssetLoader.cs) and attach it to a GameObject in a scene.
   • Use the following code to load a prefab by its address and instantiate it:

   using UnityEngine;
   using UnityEngine.AddressableAssets;
   using UnityEngine.ResourceManagement.AsyncOperations;
   
   public class AssetLoader : MonoBehaviour
   {
       private AsyncOperationHandle _handle;
   
       public void LoadCube()
       {
           _handle = Addressables.LoadAssetAsync("CubePrefab");
           _handle.Completed += OnLoadCompleted;
       }
   
       private void OnLoadCompleted(AsyncOperationHandle handle)
       {
           if (handle.Status == AsyncOperationStatus.Succeeded)
           {
               GameObject cube = Instantiate(handle.Result);
               cube.name = "LoadedCube";
               // Optionally store the reference for later release
           }
           else
           {
               Debug.LogError("Failed to load asset: " + handle.OperationException);
           }
       }
   
       private void OnDestroy()
       {
           if (_handle.IsValid())
           {
               Addressables.Release(_handle);
           }
       }
   }
   

5. Release the handle when the asset is no longer needed
   • Call Addressables.Release(handle) for each AsyncOperationHandle you obtained.
   • Do this in error paths as well (e.g., inside a catch block or after a failed load).
   • Failing to release causes memory leaks because the bundle remains loaded.

Expected checks

• After calling LoadAssetAsync, inspect the AsyncOperationHandle.Status; it should be Succeeded before using handle.Result.
• Verify that the loaded object is not null.
• Open the Unity Profiler (Window → Analysis → Profiler), select the Memory module, and look for a temporary spike that disappears after you call Release.
• Check the Console for any address resolution errors (e.g., "Unable to locate address").

Recovery options

• Fallback asset: If loading fails, instantiate a default prefab loaded via Resources.Load or a hard‑coded reference.
• Clear cache: For remote builds, call Caching.ClearCache() to remove corrupted bundles, then retry the load.
• Verify connectivity: Ensure the remote server hosting the bundles is reachable; test with a simple ping or a browser request to the bundle URL.

Limitations

• Addressable builds are platform‑specific; switching target platforms requires rebuilding the content.
• Changing an asset’s group, address, or marking status necessitates a new build; otherwise the player will look for a stale hash and fail to load.
• Remote content depends on correct server configuration (proper MIME types, CORS if needed) and network availability.

Practical verification steps

1. Enter Play mode in the Unity Editor.
2. Press a UI button that calls LoadCube() on the AssetLoader component.
3. Observe the Console: a message like "Load succeeded" (if you added one) or no error indicates success.
4. Open the Profiler, watch the Memory tab: you should see a brief increase when the cube is instantiated, returning to baseline after the object is destroyed and the handle released.
5. Destroy the instantiated cube (e.g., via another button calling Destroy) and confirm that the memory drops and no orphaned GameObjects remain in the Hierarchy.
6. For remote testing, host a dummy bundle on a local web server, set the group’s RemoteLoadPath to that URL, rebuild, and repeat the steps; simulate a network failure by stopping the server and verify your fallback logic runs.