The Addressable Asset System allows you to safely and efficiently manage the content of complex Unity projects. Discover how the Synchronous Addressables API can make switching your project to this flexible system easier than before.
The Addressable Asset System (i.e., Addressables) is our recommended tool for projects that require efficient asset and memory management. Addressables separates the concerns of referencing and packaging assets, enables faster iteration both in playmode and on deployed player builds, and provides automatic memory management and profiling tools. It builds your assets into Asset Bundles, our proprietary file structure used to package assets for content distribution and loading at runtime. The Addressable Asset System then builds a content catalog to facilitate the management of loading and dependency tracking at runtime with more flexibility.
Loading from Asset Bundles in Unity provides an efficient way to unload content that is no longer needed from memory. Loading through Addressables automatically enables high-level reference counting of loaded assets and their dependencies, and can automatically unload bundles and their associated assets when no longer in use. Additionally, Addressables provides a visual profiler for real-time debugging of loaded asset and Asset Bundle reference counts. In short, the Addressable Asset System helps you store and catalog game assets so that they can be quickly found and loaded. When you’re ready to host your assets and deliver them to live games, take a look at Cloud Content Delivery. This solution pushes those game assets right to your players through our content delivery network (CDN) partner, Akamai – completely separate from your code. Using Addressables and a CDN vastly reduces your build size and eliminates the need to have your players download and install new game versions whenever you want to make an update.
You can install the Addressable Asset System directly from the Package Manager. It’s supported by Unity 2019 LTS and newer. Check out the Addressable Asset System documentation for a guide to help you get started. Also, take a look at this blog post on saving memory with addressables, based on Patrick DeVarney’s experience optimizing customer projects with the Professional Services team.
Nearly all Addressables APIs are asynchronous in nature. As such, they return a handle for the user to progress, and retrieve the result once the operation is complete. This handle is an AsyncOperationHandle.
We initially designed Addressables around this asynchronous-only workflow as, at the time, we were heavily focused on the mobile customer requiring CDN support. This gave us the ability to provide safe APIs that would always work, no matter where the content was stored. Consider the workflow example where you would load something that you believed to be local (or that perhaps was local initially), but that actually contained a remote-hosted dependency. Loading that item asynchronously would allow you to handle any other surprise downloads.
This asynchronous restriction has not been well-suited to projects that don’t fit this profile. Many of you develop games that will never have remote content, or that will have very finely controlled download management. As our customer base has continued to grow and diversify, we have come to recognize the need for a synchronous API.
This brings us to the addition of Synchronous Addressables APIs. These APIs are available as of version 1.17.4 of the Addressables package, which is compatible with Unity 2021.1, Unity 2020 LTS and Unity 2019 LTS.
With this addition, you no longer need to make asset loading asynchronous in order to start using Addressables in your project. This new synchronous functionality comes in the form of a method called WaitForCompletion on the AsyncOperationHandle, which returns the result of that operation.
As previously mentioned, nearly all existing Addressables APIs are asynchronous, and all that are asynchronous will return this handle. By including a WaitForCompletion method in the handle class, we have given all existing APIs the ability to become synchronous on the fly.
For example, you could previously call Addressables.LoadAssetAsync<GameObject>(“MyPrefab”). This would return an AsyncOperationHandle<GameObject>, which is a handle to a GameObject operation. With that handle, calling WaitForCompletion would cause the currently executing code to block until the load is complete. Once complete, WaitForCompletion returns the requested GameObject.
All operations, asynchronous or synchronous, must be released. You can release the operation itself, or pass in the result and look up the operation from there.
In most instances, loading synchronously will have comparable performance to loading asynchronously. However, in some situations, it may be slightly faster or slower – and in a few specific cases, significantly slower.
The first case that is significantly slower occurs when the Addressables interaction involves many engine calls. This is likely to take place when loading many assets at once or a few assets that have large and complex dependency trees. This happens because, as of Unity 2021.1, running an asynchronous engine interface synchronously introduces a per-call delay. We’ve removed this delay for the next tech release, Unity 2021.2, which is currently in its alpha stage.
The second case that can significantly affect performance involves calling WaitForCompletion on a small operation, while many other larger operations are running in the background. WaitForCompletion on a single op will block the engine’s queue of asynchronous load operations. If there are some larger operations ahead of the one you’re waiting on, they could end up finishing before yours returns as complete.
We have long known that synchronous interfaces would be required. While it has taken us longer than we had hoped to build them into the existing systems in a robust and reliable manner, we’re excited to share this improvement with you today.
We hope that we've taken the right steps toward making the Addressable Asset System the best possible fit for your project’s content management strategy. We want you to know that we're listening to your feedback and doing what we can to incorporate it. That said, we look forward to hearing what you think of WaitForCompletion in the comments or the Addressables forum.
To stay up to date with what we’re working on, you can also check out the runtime asset management tab of Unity’s pipelines and integrations roadmap. Please feel free to use this page to submit your ideas regarding Addressables.