All content in this course uses:

Label addressable assets

In this tutorial, you'll learn how to assign labels to addressable assets and use labels to more efficiently manage assets in your scripts.

By the end of this tutorial, you will be able to:

Assign labels to sets of addressable assets

Merge labels to create new sets of assets

Configure AssetBundles using labels and bundle modes

GetStarted-LoadyDungeons.zip

 is a way of categorizing one or more addressable assets so that you can easily load them as a set at runtime. 

While groups and labels are both used to categorize addressable assets, they achieve different goals. Groups are used when you develop in Unity Editor to inform the build scripts how to build AssetBundles, the Addressables content. Once the content is built, groups have no presence in the runtime API. On the other hand, labels are authored in the Editor to help with loading strategies at runtime.

Addresses and labels are treated the same at runtime as 

, the concept that is used to locate and retrieve assets. When you write scripts that load assets, rather than request an individual addressable asset by address, you can instead request by a combination of addresses and labels. The Addressables system will retrieve all assets that match the locator keys queried, regardless of which group they were built from, whether in local or remote AssetBundles.

For example, you can create a label for assets you want loaded together, such as gameplay elements or assets by level.

Overview

To assign labels in Loady Dungeons, follow these instructions:

In the Addressables Groups window, select 

To add a new label named "Fancy" in the Addressables Labels dialog, select the 

) button in the reorderable list, and enter "Fancy". Select 

In the Addressables Groups window, locate the 

 dropdown in the rightmost column. (You might have to expand the Addressables Groups window on the right side to see this column.)

(gear) menu to open the Addressables Labels dialog, and add a "Seasonal" label and a "Hats" label. Be sure to select 

You now have three labels defined: Fancy, Seasonal, and Hats.

.  Finally, assign the "Hats" label to all of the hats. In the Addressable Groups window, select the 

 and press Shift+Down arrow key (macOS: Cmd+Down arrow key) or Ctrl+select (macOS: Cmd+select) on the assets to select 

 label to apply it to all selected assets.

Now you have seen a few different ways to create and assign labels. The hats have various labels that you can use in your scripts to identify these assets.

Assign labels

Let’s rewrite the game to place a randomized hat on the dinosaur by loading assets with labels. Now that all the hats are identifiable with the common Hats label, the code will be simple. 

To load multiple assets by a label, follow these instructions:

Near the top of the script, add the following namespace:

Add the following field to the existing script:

Locate the following line in the existing script:

Replace the line above with the following line:

 method, locate the following line in the existing script:

Replace the line above with the following lines:

This will make an attempt to load all the assets across all the groups that have the "Hats" key, so it will load Hat00 through Hat05. It also registers an event handler 

, which is called when all the assets with the Hats label are collected and loaded.

 and replace it with the following method: 

This method will test to see if loading all the hats was a successful operation with a valid result. If it was a success, we iterate and log the names of all the assets with the “Hats” key and pass them along to 

which chooses one of the prefabs at random.

Here, the main changes are that the method takes in a list of loaded prefabs, the random range is no longer hard-coded, and it will randomly pick one of the prefabs from the list to instantiate.

 Replace the line above with the following lines:

Here, we are still destroying the instance of the hat prefab, but instead of releasing the prefab, we keep all the hat assets in memory. We avoid releasing because the result of the load operation wasn’t one asset but multiple, so releasing 

will decrement the reference count on all prefabs, releasing all of them. Instead, we keep the reference to all and pass it along to pick from randomly again. 

Note that "AsyncOperationHandle Status: Succeeded” is printed in the Console window and you can now see the name of each hat that has the Hats label. This means that the hats loaded successfully.

Since this method collects multiple assets with its AsyncOperationHandle, the result is a list of GameObjects. The method was one asynchronous operation that was used to get all of them, so you do not have individual handles that you can release for each asset. As a result, you have to create and destroy the prefab instance using the 

Load assets by a label

When you specify multiple locator keys (addresses and labels), you can specify a merge mode to determine how the sets of assets matching each key are combined:

: Include assets only from the first key that resolves to a valid location.

In Loady Dungeons, you can use this feature to load only assets labeled "Hat" and "Seasonal" for a seasonal update to your game. To make only seasonal hats appear, follow these instructions:

merge mode so that LoadAssetsAsync gets assets with both the Hats and Seasonal labels:

Hats with the Seasonal label are randomly loaded. Note that "AsyncOperationHandle Status: Succeeded” is printed in the Console window and 

 are listed, which are the only hats labeled with both the Hats and Seasonal labels. This means that the correct hats loaded successfully.

The previous code accomplishes the job of showing the correct visuals - we have a random hat that appears on Loady’s head at the start of the level. However, the hat does not switch until the next level, so having all prefabs loaded may not be the best use of memory. Loading somewhere between 6 Hat assets may work fine now, but what happens if we grow our hat inventory to 200, or 1000 hats? It wouldn’t be practical to load all of those assets into memory just to have 1 on Loady’s head at any time.

The Addressables runtime represents all the content using 

, which define where all the assets can be found. Resource locations are the intermediary between locator keys and assets. So far, we have shown you ways to ask for assets so that they are loaded and ready. But in those load requests this chain of events generally occurs:

You pass in a locator key or a set of keys.

All the resource locations associated with the locator keys are found.

All the assets are loaded from the resource locations.

The API provides a way to break this up into two requests - load resource locations from locator keys, and load assets from the resource locations. This allows you to separate finding the items from loading them, which can split the overhead of doing it all at once.

Let’s modify our script so that you can get the locations to the assets without loading them, picking one random fancy hat at the start of the level, and then instantiating it.

To limit the amount of loaded assets, follow these instructions:

 We are going to perform two operations, one for loading the locations, and the other for loading the single asset. The 

field captures the handle for the resource location request, and 

is used to capture the instantiate operation.

 This is the request that simply gets the resource locations without loading the assets. 

 Replace the line above with the following line:

  Locate the following lines in the existing script:

method and replace it with the following lines:

Instead of accepting a list of loaded prefab assets, it instead receives a list of resource locations, so that one can be randomly picked. Once it is randomly picked, that lone asset can be loaded into memory and registers an event handler OnHatLoadComplete that will notify you when all the asset is loaded.

Here, the changes are that the asset can be released from memory and, and then it will randomly pick one of the resource locations which should be loaded and instantiated next. 

The fancy hats that are randomly loaded when the user clicks the primary mouse button. Note that "AsyncOperationHandle Status: Succeeded” is printed in the Console window and  

 are listed, which are the only hats labeled with both the Hats and Fancy labels. The details about the hats are requested, but only one is loaded successfully at a time.

Load one random fancy hat and instantiate it

, we briefly mentioned that the Content Packing & Loading group schema had an advanced option called Bundle Mode, and that Bundle Mode had a

 option. Now that you know how labels work, it’s time to revisit this option. 

The Pack Together By Label option uses labels to inform how assets are split into AssetBundles during builds. Using the Pack Together By Labels option, when assets have unique combinations of labels, they can be loaded together. For example, 

, which are labeled as Fancy, can be loaded with 

 which is labeled as Fancy and Seasonal. 

 can be loaded with them as well because all three share the Seasonal label.

There are memory allocation benefits to building individual AssetBundles with the 

 bundle mode. This mode avoids loading in a large bundle when all you want are Fancy hats, for example. In this scenario, there is no need to bring non-Fancy hats in memory, so it’s best to avoid the Pack Together mode.

There are performance benefits with loading items from one bundle with Pack Together mode. For example, you can group 

 together if you know that you want to load some combination of objects with the Hats and Fancy labels. That way, you can bring them in together. What about 

 is labeled Fancy, so it would make sense to bundle it with 

, but it also has the Seasonal label. Bundling it with 

 may be optimal for loading Fancy hats, but doing so would note be optimal for loading in Seasonal hats, since that would create a bundle large enough to include 

 to be loaded in when you aren’t using them. What to do?

This is where the Pack Together By Label option comes in. During build, it brings together assets that have a unique combination of labels and bundles them. You can make it so that 

 are in their own bundle. That way, you have the tradeoff: items that are loaded and unloaded together are mostly clumped together, while memory is in smaller reusable chunks.

To see how the asset bundles are built from Pack Together By Label groups, follow these instructions:

In the Inspector window, under the Content Packing & Loading schema, select 

 from the toolbar to start the build process again.

After the build is finished, find the remote build directory in your file system. Note the bundle files that were created. In addition to previously seen bundles, there are now four AssetBundles for each unique combination of labels in the Hats group that have replaced the original hats bundle.

Labels and Bundle Mode

In the next tutorial, you will learn how to serve addressable assets on a local hosting service in the Editor.

Unity Version 2022.3