1043|blog.unity.com
Addressables: Planning and best practices
Games today are bigger than ever. As they continue to explore the limits of modern device hardware, it becomes increasingly critical for developers to manage content efficiently at runtime. And, as publishers look to optimize their games’ retention and monetization metrics, a small game client and dynamic over-the-air content updates have become baseline requirements for many successful games.Unity provides an end-to-end pipeline to help developers and publishers succeed in today’s gaming marketplace. That pipeline starts and ends with Addressables, a Unity package that launched in 2019 and now powers thousands of successful live games and tens of thousands more in development.The Addressables package provides a user interface (UI) and API for organizing Unity assets to be built into AssetBundles and loaded and unloaded dynamically at runtime. Whether AssetBundles are shipped with your base game or hosted and delivered from a remote content delivery network (CDN) like Cloud Content Delivery, Addressables helps you load the assets you need, only when you need them.While the Addressables system can simplify many aspects of content management, it’s not a “set it and forget it” feature. The choices you make about how to organize, build, load, and unload addressable assets have significant implications for your game’s size and performance.This guide explores some of the most important factors to consider so that you can get the most out of the Addressables system. At the end of this blog, you’ll find helpful “cheat sheets” that provide general settings and strategy recommendations based on common Addressables use cases.Of course, the best strategy will depend on the game you’re building and your goals. Treat this guide as a reference to be used together with Unity Learn materials, Unity Manual documentation, and the community-driven forum for Addressables.At its core, Addressables is a tool for building and working with AssetBundles. Before diving into the Addressables UI and API, it’s important to get familiar with the AssetBundles archive file format and some of the runtime implications.You can think of AssetBundles as containers – they are archive files built for your target platforms that can contain assets like models, textures, prefabs, ScriptableObjects, audio clips, and even entire scenes that Unity can load at runtime.A key feature of AssetBundles is that they can express dependencies between one another. For example, AssetBundle 1 might contain a prefab that depends on a texture in AssetBundle 2. When you use Addressables to load the prefab at runtime, the Addressables system will automatically load AssetBundle 2 and the dependent texture into memory. And, if AssetBundle 1 has another asset that depends on an asset in AssetBundle 3, AssetBundle 3 will also be loaded into memory, and so on.When your game is running, the Addressables system tracks active references for all assets – including dependent assets like the texture discussed above – to determine which ones need to be in memory. An asset loaded from an AssetBundle cannot be released from memory until both its reference count and all other asset reference counts in the same AssetBundle are at 0. The AssetBundle itself can be released from memory only when all asset reference counts in the AssetBundle are at 0.Keeping in mind this tight relationship between Addressables and AssetBundles, the most important rule when organizing your Addressables content is to create AssetBundles that contain discrete sets of assets that you expect to be loaded and unloaded together.The most important decision you’ll likely make while using Addressables is how to organize your assets into Addressables groups. Here are a few questions to consider:Should you create many small groups or a smaller number of large groups?For each group, how many AssetBundles should you aim to generate (i.e., should you pack the assets in that group together, separately, or by label)?Should you use labels?Should you give your groups local or remote load paths?While we would love to give a single answer, the best Addressables grouping strategy will depend on several factors that are specific to your game.Remember: Addressables groups provide the organizational structure for your addressable assets that determines how those assets will be built into AssetBundles. So the best organizational strategy will be the one that packs, loads, and unloads your AssetBundles most effectively based on your game’s unique structure, goals, and limitations.Before you start organizing your Addressables content, make sure you have a solid grasp on the following:1. Your game’s structure and roadmap2. Your game’s platform strengths and limitations3. Your primary goal(s) in using Addressables to optimize your game’s performanceWe’ll tackle each of these factors below.The first factor to consider is your game’s structure and roadmap.By “structure,” we mean the actual architecture of your game. Is your game a linear, single-player journey where the player will progress through a predictable set of levels or environments? Is it a multiplatform PvP game with thousands of vanity items that could be instantiated at unpredictable times? Your game’s structure will determine when you will need to have assets loaded and ready to use, and when you’ll be able to unload assets and AssetBundles from memory.Remember, try to create AssetBundles that contain only the assets that need to be loaded together and can be unloaded together. If your game is a linear journey with distinct break points, consider organizing Addressables groups into larger subsets of content associated with each section of your game. That way, those assets can be loaded and unloaded together.If your game is non-linear and more unpredictable, opt for smaller groups that will generate smaller AssetBundles, allowing you to load and unload more dynamically. Always aim to use logical and meaningful names for your groups to help you quickly locate assets and optimize your layout.“Roadmap” refers to how your game will evolve over time. Once your game ships to players, will it remain mostly unchanged aside from occasional bug fixes or game balance patches? Or do you expect to add new content on a regular basis without requiring your players to install a large client update?Your content roadmap helps inform your grouping strategy. If your game’s content will be self-contained and not updated after launch, focus your grouping strategy around the structural considerations discussed above. If your game will require frequent content updates, group your content in a way that will allow players to download exactly what they need, when they need it.Consider using labels to help identify content from distinct bundles that will be needed together at runtime, such as a set of cosmetic items that will grow over time as your game matures. You can also use the “Pack Together By Label” Bundle Mode in your Groups Settings to subdivide content you’ve logically grouped together.For example, perhaps you plan to launch a new “Halloween 2023” event with some cosmetic items for players to collect. Your “Halloween 2023 Outfits” group might contain assets with the labels “Hats,” “Shoes,” and “Masks.” You could then add a “Halloween 2023” label to all the assets in this group. Using the “Pack Together By Label” Bundle Mode for this group will create three AssetBundles at build time.At runtime, you could then load all addressable assets with the Label “Hats” in your character customization screen to ensure all assets with that label are downloaded, loaded into memory, and ready for players to view. Or you could load all addressable assets with the label “Halloween 2023” on your promotional page for your event, ensuring they are ready to be displayed to your players.Having a deep understanding of your game’s structure and roadmap will help you make informed decisions about your content organization that will be beneficial throughout your game’s lifecycle.Next, we’ll tackle your platforms’ specific strengths and limitations and what they mean for your content strategy.The next factor to consider is the strengths and limitations of the platforms you’re targeting for distribution. In this section, we’ve outlined common platform targets for Addressables users, as well as some key considerations for each.Mobile and VRFor mobile and VR platforms, the most important considerations to keep in mind are app size, bundled content size, and download speeds.For your groups, consider the sets of content that your players will need immediately after install (e.g., to be able to complete your tutorial). Ensure this content is organized into groups with local load paths so that it will be included with your base game. Organize all other content into groups with remote load paths so that you can deliver this content over the air to your players.Opt for a group strategy that will build relatively small AssetBundles. The exact balance will depend on your game. Avoid extremely large bundles that will consume a substantial amount of memory and will be difficult to release once loaded. Similarly, avoid a huge number of tiny bundles that may create a very large Addressables catalog file that will be downloaded for every content update. Many tiny bundles can also have an impact on the speed at which your players can download the content they need, so be mindful of these pros and cons when determining the right balance for your game.Desktop and ConsolesFor desktop and consoles, the most important consideration is performance. Compared to mobile devices and wireless VR hardware, desktop and console hardware typically has fewer constraints around memory and disk storage. With this in mind, consider a group setting that will build uncompressed AssetBundles. This will provide the fastest possible loading time and can even provide for efficient patching on certain platforms.When developing for consoles specifically, pay close attention to any platform-specific caching restrictions that may apply. While mobile platforms allow you to take advantage of Unity’s AssetBundle Cache for downloaded content, this functionality is disabled by default at the Unity engine level for certain consoles and WebGL. Consider updating your base game with the new content on those platforms rather than attempting to deliver remote content over the air. Otherwise, you will need to create your own custom AssetBundle caching system and determine whether your solution complies with those platforms’ terms of service.After evaluating the strengths and limitations of your target platforms, identify one or two primary goals you’re trying to achieve by using the Addressables system. For example: Are you mainly aiming to reduce your base game’s size, or are you planning to deliver over-the-air content updates to players? To demonstrate, let’s discuss these options, and more, in detail below.Minimizing base game sizeIf your primary goal is to minimize your base game’s size, and you aren’t as concerned about memory limitations or large downloads after install, then your primary focus should be migrating as many assets as possible from scenes and Resources into one or more Addressables groups with remote load paths.Consider making the scenes in your project addressable and determine which, if any, must be included with the main player build. For those that can be delivered to players after install, include those scenes in groups with remote load paths. You can even build a player with one almost-empty scene, and load the rest of your game dynamically from there, as explained in this Open Projects Devlog video.If you make any scenes addressable, it’s best to make all of them addressable to reduce the chance and volume of unnecessary asset duplication.For groups that will generate AssetBundles to be hosted remotely, be sure to enable the AssetBundle Cache. This setting will ensure that downloaded AssetBundles will be cached on your players’ devices, preventing them from having to redownload each session.While it’s always good to keep in mind the runtime implications of many small bundles versus few large bundles, these considerations become more relevant when considering other goals you may have.Efficiently delivering remote content to playersIf your primary goal is the efficient delivery of remote content, your group structure should reflect how you aim to split content between “local” (i.e., assets included with your player build) and “remote” content (i.e., assets hosted on an external content delivery network). Again, be sure to enable the AssetBundle Cache to cache downloaded content on players’ devices.The size, number, and Bundle Mode of these groups will depend on when you expect to deliver remote content to your players and how long you’re willing to let them wait for downloads to complete. For example, if your game’s structure will allow for delivery of all remote content shortly after they install the base game, you can opt for larger groups with Pack Together or Pack Together By Label, which will result in a small number of large downloads.If you expect to deliver smaller sets of remote content to players throughout their sessions that will be less disruptive to the experience, you can opt for smaller groups and/or a Bundle Mode setting that will generate smaller AssetBundles that will download much more quickly.In most cases, for groups containing remote content, consider Enabled, Excluding Cached for your AssetBundle Cyclic Redundancy Check (CRC) option. This will provide additional assurances of your remote content’s integrity as it’s being cached to players’ devices, while avoiding the additional overhead of performing a CRC for loading content that’s already on player devices.Optimizing runtime memory usage and performanceIf your primary goal is optimizing the game’s runtime performance and memory usage, remember the most important rule of Addressables groups organization: Assets that you plan to load and unload at the same time should be grouped together.Generally speaking, this will mean creating smaller AssetBundles. You can achieve this in several ways, including creating smaller groups and/or avoiding the “Pack Together” Bundle Mode in your Group Settings for large groups that contain assets that won’t always be needed at the same time in your game.You should also keep an eye on runtime performance to help you spot potential issues or areas of optimization. Take advantage of official Unity tools like the Unity Profiler, the Memory Profiler package, or the Addressables Event Viewer, which can all help optimize your game’s performance.Be on the lookout for the upcoming Addressables Profiler Module, which will replace the Addressables Event Viewer. This new tool will provide even more in-depth information about how your code is loading and unloading addressable assets and AssetBundles, including detailed information about dependencies among your assets and AssetBundles.Multiple goalsOf course, most projects will have a number of goals associated with Addressables. In this case, there is truly no one-size-fits-all approach. You will need to evaluate the tradeoffs outlined above and find the group structure and settings that will best achieve the success you’ve defined.We recommend that you take advantage of the Addressables Build Report and the Addressables Profiler Module, available soon in Addressables 1.21.3. The Addressables Build Report will provide you with detailed information about the AssetBundles that were generated from your Addressables builds, including file size, potential duplicates, and in-depth dependency information. The Addressables Profiler Module is a new runtime analysis tool that takes advantage of this new dependency data, providing precise information about what was loaded by your Addressables code and why it was loaded.Below we’ve provided some handy “cheat sheets” for our recommended Addressables settings and strategies based on some of the most common use cases. Of course, these are just suggestions – it’s up to you to determine whether a suggestion aligns with your project’s unique structure and your specific goals.A mobile game with frequent content updatesA standalone, self-contained desktop or console gameA VR game built for Meta Quest 2If you have questions or want to learn more about the Addressables package, visit us in the Addressables forum. You can also connect with me directly on Twitter at @Unity_Jeff. Be sure to watch for new technical blogs from other Unity developers as part of the ongoing Tech from the Trenches series.
