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 AssetBundle.
  • 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 unloads until the AssetBundle itself is completely unloaded. The exception to this rule is the engine interface Resources.UnloadUnusedAssets. Executing this method in the above scenario causes 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. An example of this is a material referencing a texture. 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 RootAsset1 and RootAsset2. RootAsset2 references DependencyAsset3, which is contained in BundleB. Even though RootAsset1 has no reference to BundleB, BundleB is still a dependency of RootAsset1 because RootAsset1 is in BundleA, which has a reference on BundleB.

Prior to 1.13.0, the dependency graph was not as thorough as it is now. In the example above, RootAsset1 would not have had a dependency on BundleB. This previous behavior resulted in references breaking when an AssetBundle being referenced by another AssetBundle was unloaded and reloaded. This fix may result in additional data remaining in memory if the dependency graph is complex enough.

Duplicate dependencies

When exploring memory management and dependency graphs, it's important to discuss duplicated content. There are two mechanisms by which an asset can be built into an AssetBundle: explicit and implicit. If you mark an asset as Addressable, it is explicitly put into an AssetBundle. That is the only AssetBundle it is in.

Example: A material has a direct dependency on a texture, and both assets are marked as Addressable in separate AssetBundles BundleM and BundleT respectively. BundleT contains the texture, BundleM contains the material, and lists BundleT as a dependency.

If any dependencies are not explicitly included, then they are implicitly pulled in. Example: A material has a direct dependency on a texture, and only the material is marked as Addressable in BundleM. During build, the texture, because it is not explicitly included elsewhere, is pulled into BundleM when the material is.

This implicit dependency inclusion can lead to duplication. Example Two materials, matA and matB, are Addressable and both have direct dependencies on the same texture. If matA and matB are built into the same AssetBundle, then the texture is pulled implicitly in once. If matA and matB are built into separate AssetBundles, then the texture is pulled implicitly into each of those AssetBundles. At runtime, the engine has no record that these textures came from the same source asset, and are each loaded as they are needed by their respective materials.

SpriteAtlas dependencies

SpriteAtlases complicate the dependency calculation a bit, and merit a more thorough set of examples.

Addressable Sprite Example 1: Three textures exist and are marked as Addressable in three separate groups. Each texture builds to about 500KB. During the build, they are built into three spearate AssetBundles, each AssetBundle only containing the given sprite meta data and texture. Each AssetBundle is be about 500KB and none of these AssetBundles have dependencies.

Addressable Sprite Example 2: The three textures in Example 1 are put into a SpriteAtlas. That atlas is not Addressable. One of the AssetBundles generated contains that atlas texture and is about 1500KB. The other two AssetBundles only contain Sprite metadata (a few KB), and list the atlas AssetBundle as a dependency. Which AssetBundle contains the texture is deterministic in that it is the same through rebuilds, but is not something that can be set by the user. This is the key portion that goes against the standard duplication of dependencies. The sprites are dependent on the SpriteAtlas texture to load, and yet that texture is not built into all three AssetBundles, but is instead built only into one.

Addressable Sprite Example 3: The SpriteAtlas from Example 2 is marked as Addressable in its own AssetBundle. At this point there are four AssetBundles created. If you are using a 2020.x or newer version of Unity, this builds as you would expect. The three AssetBundles with the sprites are each be only a few KB and have a dependency on this fourth SpriteAtlas AssetBundle, which is be about 1500KB. If you are using 2019.x or older, the texture itself may end up elsewhere. The three sprite AssetBundles still depend on the SpriteAtlas AssetBundle. However, the SpriteAtlas AssetBundle may only contain meta data, and the texture may be with one of the other sprites.

Addressable Material With Sprite Dependency Example 1: Instead of three Addressable textures, there are three Addressable materials. Each material depends on its own texture (about 500KB). Building the three materials seperately results, as expected, in three AssetBundles of about 500KB each.

Addressable Material With Sprite Dependency Example 2 Taking the materials and texture from the previous example, all three textures are added to a SpriteAtlas, and that atlas is not marked as Addressable. In this scenario, the SpriteAtlas texture is duplicated. All three AssetBundles are approximately 1500KB. This is expected based on the general rules about duplication of dependencies, but goes against the behavior seen in "Addressable Sprite Example 2".

Addressable Material With Sprite Dependency Example 2 Taking the materials, texture, and SpriteAtlas form the above example, the SpriteAtlas is also marked as Addressable. Conforming to the rules of explicit inclusion, the SpriteAtlas texture is included only in the AssetBundle containing the SpriteAtlas. The AssetBundles with materials references this fourth AssetBundle as a dependency.