Memory management

Mirroring load and unload

When working with Addressable Assets, the primary way to ensure proper memory management is to mirror your load and unload calls correctly. How you do so depends on your Asset types and load methods. In all cases, however, the release method can either take the loaded Asset, or an operation handle returned by the load. For example, during Scene creation (described below) the load returns a AsyncOperationHandle<SceneInstance>, which you can release via this returned handle, or by keeping up with the handle.Result (in this case, a SceneInstance).

Asset loading

To load an Asset, use Addressables.LoadAssetAsync (single asset) or Addressables.LoadAssetsAsync (multiple assets).

Note: LoadAssetAsync is intended for use with keys that map to single entries. If you provide a key that matches multiple entries (such as a widely used label) the method will load the first match it finds to the given key. This is not deterministic as it can be affected by build order.

This loads the Asset into memory without instantiating it. Every time the load call executes, it adds one to the ref-count for each Asset loaded. If you call LoadAssetAsync three times with the same address, you will get three different instances of an AsyncOperationHandle struct back, all referencing the same underlying operation. That operation has a ref-count of three for the corresponding Asset. If the load succeeds, the resulting AsyncOperationHandle struct contains the Asset in the .Result property. You can use the loaded Asset to instantiate using Unity's built-in instantiation methods, which does not increment the Addressables ref-count.

To unload the Asset, use the Addressables.Release method, which decrements the ref-count. When a given Asset's ref-count is zero, that Asset is ready to be unloaded, and decrements the ref-count of any dependencies.

Note: The Asset may or may not be unloaded immediately, contingent on existing dependencies. For more information, read the section on when memory is cleared.

Scene loading

To load a Scene, use Addressables.LoadSceneAsync. You can use this method to load a Scene in Single mode, which closes all open Scenes, or in Additive mode (for more information, see documentation on Scene mode loading.

To unload a Scene, use Addressables.UnloadSceneAsync, or open a new Scene in Single mode. You can open a new Scene by either using the Addressables interface, or using the SceneManager.LoadScene or SceneManager.LoadSceneAsync methods. Opening a new Scene closes the current one, properly decrementing the ref-count.

GameObject instantiation

To load and instantiate a GameObject Asset, use Addressables.InstantiateAsync. This instantiates the Prefab located by the specified location parameter. The Addressables system will load the Prefab and its dependencies, incrementing the ref-count of all associated Assets.

Calling InstantiateAsync three times on the same address results in all dependent assets having a ref-count of three. Unlike calling LoadAssetAsync three times, however, each InstantiateAsync call returns an AsyncOperationHandle pointing to a unique operation. This is because the result of each InstantiateAsync is a unique instance. You would need to individually release each returned AsyncOperationHandle or GameObject instance. Another distinction between InstantiateAsync and other load calls is the optional trackHandle parameter. When set to false, you must keep the AsyncOperationHandle to use while releasing your instance. This is more efficient, but requires more development effort.

To destroy an instantiated GameObject, use Addressables.ReleaseInstance, or close the Scene that contains the instantiated object. This Scene can have been loaded (and thus closed) in Additive or Single mode. This Scene can also have been loaded using either the Addressables or SceneManagement API. As noted above, if you set trackHandle to false, you can only call Addressables.ReleaseInstance with the handle, not with the actual GameObject.

Note: If you call Addressables.ReleaseInstance on an instance that was not created using the Addressables API, or was created with trackHandle==false, the system detects that and returns false to indicate that the method was unable to release the specified instance. The instance will not be destroyed in this case.

Addressables.InstantiateAsync has some associated overhead, so if you need to instantiate the same objects hundreds of times per frame, consider loading via the Addressables API, then instantiating through other methods. In this case, you would call Addressables.LoadAssetAsync, then save the result and call GameObject.Instantiate() for that result. This allows flexibility to call Instantiate in a synchronous way. The downside is that the Addressables system has no knowledge of how many instances you created, which can lead to memory issues if not properly managed. For example, a Prefab referencing a texture would no longer have a valid loaded texture to reference, causing rendering issues (or worse). These sorts of problems can be hard to track down as you may not immediately trigger the memory unload (see section on clearing memory, below).

Data loading

Interfaces that do not need their AsyncOperationHandle.Result released, will still need the operation itself to be released. Examples of these would be Addressables.LoadResourceLocationsAsync and Addressables.GetDownloadSizeAsync. They load data that you can access until the operation is released. This release should be done via Addressables.Release.

Background interactions

Operations that do not return anything in the AsyncOperationHandle.Result field have have an optional parameter to automatically release the operation handle on completion. If you have no further need for one of these operation handles after it has completed, set the autoReleaseHandle parameter to true to make sure the operation handle is cleaned up. The scenario where you would want autoReleaseHandle to be false would be if you needed to check the Status of the operation handle after it has completed. Examples of these interfaces are Addressables.DownloadDependenciesAsync and Addressables.UnloadScene.

The Addressables Event Viewer

Use the Addressables Event Viewer window to monitor the ref-counts of all Addressables system operations. To access the window in the Editor, select Window > Asset Management > Addressables > Event Viewer.

Important: In order to view data in the Event Viewer, you must enable the Send Profiler Events setting in your AddressableAssetSettings object's Inspector. Changes to Send Profiler Events will be reflected in the following build. This means that entering play mode when using the Use Existing Build play mode script will use the value set during the most recent build. Alternatively, entering play mode when using the Use Asset Database or Simulate Groups play mode scripts will pick up the current state, as those play mode scripts rebuild the settings data upon entering play mode.

The following information is available in the Event Viewer:

  • A white vertical line indicates the frame in which a load request occurred.
  • A blue background indicates that an Asset is currently loaded.
  • The green part of the graph indicates an Asset's current ref-count.

Note that the Event Viewer is only concerned with ref-counts, not memory consumption (see section on clearing memory, below, for more information).

Listed under the Assets column, you will see a row for each of the following, per frame:

  • FPS: The frames per second count.
  • MonoHeap: The amount of RAM in use.
  • Event Counts: The total number of events in a frame.
  • Instantiation Counts: The total number of calls to Addressables.InstantiateAsync on a frame.
  • Asset requests: Displays the reference count on an operation over time. If the Asset request has any dependencies, a triangle appears that you can click on to view the children's request operations.

You can click the left and right arrows in order to step through the frames one by one, or click Current to jump to the latest frame. Press the + button to expand a row for more details.

The information displayed in the Event Viewer is related to the build script you use to create Play mode data.

When using the Event Viewer, avoid the Use Asset Database built script because it does not account for any shared dependencies among the Assets. Use the Simulate Groups script or the Use Existing Build script instead, but the latter is better suited for the Event Viewer because it gives a more accurate monitoring of the ref-counts.

Connecting the Event Viewer to a standalone player

To connect the Event Viewer to a standalone player, go into the build menu, select the platform you wish to use, and ensure that Development Build and Autoconnect Profiler are both enabled. Next, open the Unity Profiler by selecting Window > Analysis > Profiler and select the platform you wish to build for on the top toolbar. Finally, select Build and Run in the Build Settings window and the Event Viewer will automatically connect to and display events for the standalone player selected.

When is memory cleared?

An Asset no longer being referenced (indicated by the end of a blue section in the profiler) does not necessarily mean that Asset was unloaded. A common applicable scenario involves multiple Assets in an AssetBundle. For example:

  • You have three Assets (tree, tank, and cow) in an AssetBundle (stuff).
  • When tree loads, the profiler displays a single ref-count for tree, and one for stuff.
  • Later, when tank loads, the profiler displays a single ref-count for both tree and tank, and two ref-counts for the stuff bundle.
  • If you release tree, it's ref-count becomes zero, and the blue bar goes away.

In this example, the tree Asset is not actually unloaded at this point. You can load an AssetBundle, or its partial contents, but you cannot partially unload an AssetBundle. No Asset in stuff will unload until the bundle itself is completely unloaded. The exception to this rule is the engine interface Resources.UnloadUnusedAssets. Executing this method in the above scenario will cause tree to unload. Because the Addressables system cannot be aware of these events, the profiler graph only reflects the Addressables ref-counts (not exactly what memory holds). Note that if you choose to use Resources.UnloadUnusedAssets, it is a very slow operation, and should only be called on a screen that won't show any hitches (such as a loading screen).

AssetBundle dependencies

Loading an Addressable Asset loads all the AssetBundle dependencies and keeps them loaded until you call Addressables.Release on the handle returned from the loading method.

AssetBundle dependencies are created when an asset in one AssetBundle references an asset in another AssetBundle. The dependencies of all these AssetBundles can be thought of as a dependency graph. During the catalog generation stage of the build process, Addressables walks this graph to calculate all the AssetBundles that must be loaded for each Addressable Asset. Because dependencies are calculated at the AssetBundle level, all Addressable Assets within a single AssetBundle have the same dependencies. Adding an Addressable Asset that has an external reference (references an object in another AssetBundle) to an AssetBundle adds that AssetBundle as a dependency for all the other Addressable Assets in the AssetBundle.

For Example:

BundleA contains Addressable Assets Asset1 and Asset2. Asset2 references Asset3, which is contained in BundleB. Even though Asset1 has no reference to BundleB, BundleB is still a dependency of Asset1 because Asset1 is in BundleA, which has a reference on BundleB.

NOTE

The dependency calculation for the required set of AssetBundles has changed as of 1.13.0. Prior to 1.13.0, only the AssetBundles that contained assets for the requested Addressable Asset were loaded. In the example above, Asset1 would not have had a dependency on BundleB. This previous behavior was resulting in references breaking when an AssetBundle being referenced by another AssetBundle was unloaded and reloaded.