# Addressables package The Addressables package provides tools and scripts to organize and package content for your application, and an API to load and release assets at runtime. When you make an asset Addressable, you can use that asset's address to load it from anywhere. Whether that asset resides in the local application or on a content delivery network, the Addressable system locates and returns it. Adopt the Addressables system to help improve your project in the following areas: - **Flexibility**: Addressables give you the flexibility to adjust where you host your assets. You can install assets with your application or download them on demand. You can change where you access a specific asset at any stage in your project without rewriting any game code. - **Dependency management**: The system automatically loads all dependencies of any assets you load, so that all meshes, shaders, animations, and other assets load before the system returns the content to you. - **Memory management**: The system unloads and loads assets, and counts references automatically. The Addressables package also provides a Profiler to help you identify potential memory problems. - **Content packing**: Because the system maps and understands complex dependency chains, it package AssetBundles efficiently, even when you move or rename assets. You can prepare assets for both local and remote deployment, to support downloadable content and reduced application size. ##### Note ``` The Addressables system builds on Unity's AssetBundle. If you want to use AssetBundles in your projects without writing your own detailed management code, you should use Addressables. ``` # Get started Contains getting started information to set up and use Addressables for the first time. | **Topic** | **Description** | | ------------------------------------------ | -------------------------------------------------------------------- | | Install Addressables | Install the Addressables package. | | Make an asset Addressable | Make assets Addressable. | | Configure your project to use Addressables | Upgrade an existing project to use Addressables. | | Use an Addressable asset | Understand the ways you can load and use Addressable assets. | | Manage Addressable assets | Manage Addressables with groups. | | Build Addressable assets | Build and configure Addressables. | | Remote content distribution | Understand how to distribute content remotely. | | Incremental content updates | Understand how to make a content update build. | | Addressables samples | Information about the samples contained in the Addressables package. | ## Addressables overview Addressables provides a system that can scale with your project. You can start with a simple setup and then reorganize as your project grows in complexity with minimal code changes. For example, you can start with a single group of Addressable assets, which Unity loads as a set. Then, as you add more content, you can split your assets into multiple groups so that you can load only the ones you need at a given time. As your team grows in size, you can make separate Unity projects to develop different types of assets. These auxiliary projects can produce their own Addressables content builds that you load from the main project. ### Concepts This overview discusses the following concepts to help you understand how to manage and use your assets with the Addressables system: | **Concept** | **Description** | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Addressables tools | The Addressables package has several windows and tools that you can use to organize, build, and optimize your content. | | Asset address | A string ID that identifies an Addressable asset. You can use an address as a key to load the asset. | | Asset loading and unloading | The `Addressables` API provides its own functions to load and release assets at runtime. | | Asset location | A runtime object that describes how to load an asset and its dependencies. You can use a location object as a key to load the asset. | | AssetReferences | A type you can use to support the assignment of Addressable assets to fields in an Inspector window. You can use an AssetReference instance as a key to load the asset. The [`AssetReference`](https://docs.unity3d.com/Packages/com.unity.addressables@2.7/manual/AssetReferences.html) class also provides its own loading methods. | | Content builds | Use a content build to collate and package your assets as a separate step before you make a player build. | | Content catalogs | Addressables uses catalogs to map your assets to the resources that contain them. | | Dependencies | An asset dependency is one asset used by another, such as a prefab used in a scene asset or a material used in a prefab asset. | | Dependency and resource management | The Addressables system uses reference counting to track which assets and AssetBundles are in use, including whether the system loads or unloads dependencies (other referenced assets). | | Group | You assign assets to groups in the Editor. The group settings configure how Addressables packages the group assets into AssetBundles and how it loads them at runtime. | | Key | An object that identifies one or more Addressables. Keys include addresses, labels, AssetReference instances and location objects. | | Label | A tag that you can assign to multiple assets and use to load related assets together as a group. You can use a label as a key to load the asset. | | Multiple platform support | The build system separates content built by platform and resolves the correct path at runtime. | By default, Addressables uses AssetBundles to package your assets. You can also implement your own IResourceProvider class to support other ways to access assets. ### Asset addresses A key feature of the Addressables system is that you assign addresses to your assets and use those addresses to load them at runtime. The Addressables resource manager looks up the address in the content catalog to find out where the asset is stored. Assets can be built-in to your application, cached locally, or hosted remotely. The resource manager loads the asset and any dependencies, downloading the content first, if necessary. An overview of the Addressables system retrieving assets from different locations. The locally-installed application includes both non-addressable assets and local addressable assets. It communicates with both a device cache and a remote host, which each have their own addressable assets that the application can retrieve. An overview of the Addressables system retrieving assets from different locations. Because an address isn't tied to the physical location of the asset, you have several options to manage and optimize your assets, both in the Unity Editor and at runtime. Catalogs map addresses to physical locations. Although it's best practice to assign unique addresses to your assets, an asset address doesn't have to be unique. You can assign the same address string to more than one asset when useful. For example, if you have variants of an asset, you can assign the same address to all the variants and use labels to distinguish between the variants: - Asset 1: address: `"plate_armor_rusty"`, label: `"hd"` - Asset 2: address: `"plate_armor_rusty"`, label: `"sd"` The `Addressables` API methods that only load a single asset, such as LoadAssetAsync, load the first instance found if you call them with an address assigned to multiple assets. Other methods, like LoadAssetsAsync, load multiple assets in one operation and load all the assets with the specified address. ##### Tip You can use the `MergeMode` parameter of `LoadAssetsAsync` to load the intersection of two keys. In the earlier example, you can specify the address, `"plate_armor_rusty"`, and the label, `"hd"`, as keys and intersection as the merge mode to load Asset 1. You can then change the label value to `"sd"` to load Asset 2. For more information on how to assign addresses to assets, refer to Making an asset Addressable. For information on how to load assets by keys, including addresses, refer to Loading assets. ### AssetReference An AssetReference is a type that you can set to any kind of Addressable asset. Unity doesn't automatically load the asset assigned to the reference, so you have more control over when to load and unload it. Use fields of type AssetReference in a MonoBehaviour or ScriptableObject to specify which Addressable asset to use for that field (instead of using the string that specifies the address). AssetReferences support drag-and-drop and object picker assignment, which makes them more convenient to use in an Editor Inspector. Addressables also provides a few more specialized types, such as AssetReferenceGameObject and AssetReferenceTexture. You can use these specialized subclasses to prevent the possibility of assigning the wrong asset type to an AssetReference field. You can also use the AssetReferenceUILabelRestriction attribute to limit assignment to assets with specific labels. Refer to Using AssetReferences for more information. ### Asset loading and unloading To load an Addressable asset, you can use its address or other key such as a label or AssetReference. Refer to Loading Addressable Assets for more information. You only need to load the main asset and Addressables loads any dependent assets automatically. When your application no longer needs access to an Addressable asset at runtime, you must release it so that Addressables can free the associated memory. The Addressables system keeps a reference count of loaded assets, and doesn't unload an asset until the reference count returns to zero. As such, you don't need to keep track of whether an asset or its dependencies are still in use. You only need to make sure that any time you explicitly load an asset, you release it when your application no longer needs that instance. Refer to Releasing Addressable assets for more information. ### Dependency and resource management One asset in Unity can depend on another. A scene might reference one or more prefabs, or a prefab might use one or more materials. One or more prefabs can use the same material, and those prefabs can exist in different AssetBundles. When you load an Addressable asset, the system automatically finds and loads any dependent assets that it references. When the system unloads an asset, it also unloads its dependencies, unless a different asset is still using them. As you load and release assets, the Addressables system keeps a reference count for each item. When an asset is no longer referenced, Addressables unloads it. If the asset was in a bundle that no longer has any assets that are in use, Addressables also unloads the bundle. Refer to Memory management for more information. ### Addressables groups and labels Use Addressables groups to organize your content. All Addressable assets belong to a group. If you don't explicitly assign an asset to a group, Addressables adds it to the default group. You can set the group settings to specify how the Addressables build system packages the assets in a group into bundles. For example, you can choose whether to pack all the assets in a group together in a single AssetBundle file. Use labels to tag content that you want to treat together in some way. For example, if you had labels defined for red, hat, and feather, you can load all red hats with feathers in a single operation, whether they're part of the same AssetBundle or not. You can also use labels to decide how assets in a group are packed into bundles. Add an asset to a group and move assets between groups using the Addressables Groups window. You can also assign labels to your assets in the Groups window. #### Group schemas The schemas assigned to a group define the settings used to build the assets in a group. Different schemas can define different groups of settings. For example, one standard schema defines the settings for how to pack and compress your assets into AssetBundles (among other options). Another standard schema defines which of the categories, Can Change Post Release and Cannot Change Post Release the assets in the group belong to. You can define your own schemas to use with custom build scripts. Refer to Schemas for more information about group schemas. ### Content catalogs The Addressables system produces a content catalog file that maps the addresses of your assets to their physical locations. It can also create a hash file containing the hash of the catalog. If you're hosting your Addressable assets remotely, the system uses this hash file to decide if the content catalog has changed and needs to download it. Refer to Content catalogs for more information. The Profile selected when you perform a content build determines how the addresses in the content catalog map to resource loading paths. Refer to Profiles for more information. For information about hosting content remotely, refer to Distributing content remotely. ### Content builds The Addressables system separates the building of Addressable content from the build of your player. A content build produces the content catalog, catalog hash, and the AssetBundles containing your assets. Because asset formats are platform-specific, you must make a content build for each platform before building a player. Refer to Building Addressable content for more information. ### Play mode scripts When you run your game or application in Play mode, it can be inconvenient and slow to always perform a content build before pressing the Play button. At the same time, you want to be able to run your game in a state as close to a built player as possible. Addressables provides three options that decide how the Addressables system locates and loads assets in Play mode: - **Use the Asset Database**: Addressables loads assets directly from the Asset Database. This option typically provides the fastest iteration speed if you're making both code and Asset changes, but also least resembles a production build. - **Use existing build**: Addressables loads content from your last content build. This option most resembles a production build and provides fast iteration turnaround if you aren't changing assets. Refer to Play mode scripts for more information. ### Addressables tools The Addressables system provides the following tools and windows to help you manage your Addressable assets: * Addressable Groups window: The main interface for managing assets, group settings, and making builds. * Profiles window: Helps set up paths used by your builds. * Build layout report: Describes the AssetBundles produced by a content build. * Analyze tool: the Analyze tool runs analysis rules that check whether your Addressables content conforms to the set of rules you have defined. The Addressables system provides some basic rules, such as checking for duplicate assets; you can add your own rules using the AnalyzeRule class. ## Install Addressables To install the Addressables package in your project, use the Package Manager: 1. Open the Package Manager (menu: Window > Package Manager). 2. Set the package list to display packages from the Unity Registry. 3. Select the Addressables package in the list. 4. Click Install (at the bottom, right-hand side of the Package Manager window). To set up the Addressables system in your Project after installation, open the Addressables Groups window and click Create Addressables Settings. The Addressables Groups window before initializing the Addressables system in a Project. The window displays the Create Addressables Settings button and an accompanying message. Before initializing the Addressables system in a Project When you run the Create Addressables Settings command, the Addressables system creates a folder called, AddressableAssetsData, in which it stores settings files and other assets it uses to keep track of your Addressables setup. You should add the files in this folder to your source control system. Note that Addressables can create additional files as you change your Addressables configuration. Refer to Addressables Settings for more information about the settings. ##### Note ``` For instructions on installing a specific version of Addressables or for general information about managing the packages in a Project, refer to Packages. ``` ## Configure your project to use Addressables You can add Addressables to an existing Unity project by installing the Addressables package. Once you've installed the package, you need to assign addresses to your assets and refactor any runtime loading code. Although you can integrate Addressables at any stage in a project’s development, it's best practice to start using Addressables immediately in new projects to avoid unnecessary code refactoring and content planning changes later in development. ### Convert to Addressables Content built using Addressables only references other assets built in that Addressables build. Content that's used or referenced to which is included within both Addressables, and the Player build through the **Scene data** and **Resource folders** is duplicated on disk and in memory if they're both loaded. Because of this limitation, you must convert all **Scene data** and **Resource folders** to the Addressables build system. This reduces the memory overhead because of duplication and means you can manage all content with Addressables. This also means that the content can be either local or remote, and you can update it through content update builds. To convert your project to Addressables, you need to perform different steps depending on how your current project references and loads assets: * **Prefabs**: Assets you create using GameObjects and components, and save outside a Scene. For information on how to upgrade prefab data to Addressables, refer to Convert prefabs. * **AssetBundles**: Assets you package in AssetBundles and load with the AssetBundle API. For information on how to upgrade AssetBundles to Addressables, refer to Convert AssetBundles * **StreamingAssets**: Files you place in the StreamingAssets folder. Unity includes any files in the StreamingAssets folder in your built player application as is. For information, refer to Files in StreamingAssets ### Convert scene data To convert scene data to Addressable, move the scenes out of the Build Settings list and make those scenes Addressable. You must have one scene in the list, which is the scene Unity loads at application startup. You can make a new scene for this that does nothing else than load your first Addressable scene. To convert your scenes: Create a new initialization scene. Open the Build Settings window (menu: File > Build Settings). Add the initialization scene to the scene list. Remove the other scenes from the list. Select each scene in the project list and enable the Addressable option in its Inspector window. Or, you can drag scene assets to a group in the Addressables Groups window. Don't make your new initialization scene Addressable. Update the code you use to load Scenes to use the Addressables class scene loading methods rather than the SceneManager methods. You can now split your one, large Addressable Scene group into multiple groups. The best way to do that depends on the project goals. To proceed, you can move your Scenes into their own groups so that you can load and unload each of them independently of each other. You can avoid duplicating an asset referenced from two different bundles by making the asset itself Addressable. It's often better to move shared assets to their own group as well to reduce dependencies among AssetBundles. To avoid duplicating an asset referenced from two different bundles, make the asset Addressable. It's often better to move shared assets to their own group to reduce the amount of dependencies among your AssetBundles. ### Use Addressable assets in non-Addressable scenes For any scenes that you don't want to make Addressable, you can still use Addressable assets as part of the Scene data through AssetReferences. When you add an AssetReference field to a custom MonoBehaviour or ScriptableObject class, you can assign an Addressable asset to the field in the Unity Editor in a similar way that you assign an asset as a direct reference. The main difference is that you need to add code to your class to load and release the asset assigned to the AssetReference field (whereas Unity loads direct references automatically when it instantiates your object in the Scene). ##### Note ``` You can't use Addressable assets for the fields of any UnityEngine components in a non-Addressable scene. For example, if you assign an Addressable mesh asset to a MeshFilter component in a non-Addressable Scene, Unity doesn't use the Addressable version of that mesh data for the Scene. Instead, Unity copies the mesh asset and includes two versions of the mesh in your application: one in the AssetBundle built for the Addressable group that contains the mesh, and one in the built-in Scene data of the non-Addressable scene. When used in an Addressable Scene, Unity doesn't copy the mesh data and always loads it from the AssetBundle. ``` To replace direct references with AssetReferences in your custom classes, follow these steps: 1. Replace your direct references to objects with asset references (for example, public GameObject directRefMember; becomes public AssetReference assetRefMember;). 2. Drag assets onto the appropriate component’s Inspector, as you would for a direct reference. 3. Add runtime code to load the assigned asset using the Addressables API. 4. Add code to release the loaded asset when no longer needed. For more information about using AssetReference fields, refer to Asset references. For more information about loading Addressable assets, refer to Loading Addressable assets. ### Convert prefabs To convert a prefab into an Addressable asset, enable the **Addressables** option in its Inspector window or drag it to a group in the Addressables Groups window. You don't always need to make prefabs Addressable when used in an Addressable scene. Addressables automatically includes prefabs that you add to the scene hierarchy as part of the data contained in the scene's AssetBundle. If you use a prefab in more than one scene, make the prefab into an Addressable asset so that the prefab data isn't duplicated in each scene that uses it. You must also make a prefab Addressable if you want to load and instantiate it dynamically at runtime. ##### Note ``` If you use a Prefab in a non-Addressable Scene, Unity copies the Prefab data into the built-in Scene data whether the Prefab is Addressable or not. ``` ### Convert the Resources folder If your project loads assets in Resources folders, you can migrate those assets to the Addressables system: 1. Make the assets Addressable. To do this, either enable the **Addressable** option in each asset's Inspector window or drag the assets to groups in the Addressables Groups window. 2. Change any runtime code that loads assets using the Resources API to load them with the Addressables API. 3. Add code to release loaded assets when no longer needed. As with scenes, if you keep all the former Resources assets in one group, the loading and memory performance should be equivalent. When you mark an asset in a Resources folder as Addressable, the system automatically moves the asset to a new folder in your project named Resources_moved. The default address for a moved asset is the old path, omitting the folder name. For example, your loading code might change from: ``` Resources.LoadAsync\<GameObject\>("desert/tank.prefab"); ``` to: ``` Addressables.LoadAssetAsync\<GameObject\>("desert/tank.prefab");. ``` You might have to implement some functionality of the Resources class differently after modifying your project to use the Addressables system. For example, consider the Resources.LoadAll method. Previously, if you had assets in a folder named Resources/MyPrefabs/, and ran Resources.LoadAll\<SampleType\>("MyPrefabs");, it would have loaded all the assets in Resources/MyPrefabs/ matching type SampleType. The Addressables system doesn't support this exact functionality, but you can achieve similar results using Addressable labels. ### Convert AssetBundles When you first open the Addressables Groups window, Unity offers to convert all AssetBundles into Addressables groups. This is the easiest way to migrate your AssetBundle setup to the Addressables system. You must still update your runtime code to load and release assets using the Addressables API. If you want to convert your AssetBundle setup manually, click the Ignore button. The process for manually migrating your AssetBundles to Addressables is similar to that described for scenes and the Resources folder: Make the assets Addressable by enabling the Addressable option on each asset’s Inspector window or by dragging the asset to a group in the Addressables Groups window. The Addressables system ignores existing AssetBundle and label settings for an asset. Change any runtime code that loads assets using the AssetBundle or UnityWebRequestAssetBundle APIs to load them with the Addressables API. You don't need to explicitly load AssetBundle objects themselves or the dependencies of an asset; the Addressables system handles those aspects automatically. Add code to release loaded assets when no longer needed. ##### Note ``` The default path for the address of an asset is its file path. If you use the path as the asset's address, you'd load the asset in the same manner as you would load from a bundle. The Addressable asset system handles the loading of the bundle and all its dependencies. ``` If you chose the automatic conversion option or manually added your assets to equivalent Addressables groups, then, depending on your group settings, you end up with the same set of bundles containing the same assets. The bundle files themselves won't be identical. ### Files in StreamingAssets You can continue to load files from the StreamingAssets folder when you use the Addressables system. However, the files in this folder can't be Addressable nor can they reference other assets in your project. The Addressables system places its runtime configuration files and local AssetBundles in the StreamingAssets folder during a build. Addressables removes these files at the conclusion of the build process and you won’t see them in the Editor. ## Make an asset Addressable You can make an asset Addressable in the following ways: * Enable the Addressable checkbox in the Inspector window for either the asset itself or for its parent folder. * Drag or assign the asset to an AssetReference field in the Inspector window. * Drag the asset into a group on the Addressables Groups window. Once you make an asset Addressable, the Addressables system adds it to a default group, unless you place it in a specific group. Addressables packs assets in a group into AssetBundles according to your group settings when you make a content build. You can load these assets using the Addressables API. ##### Note ``` If you make an asset in a Resources folder Addressable, Unity moves the asset out of the Resources folder. You can move the asset to a different folder in your Project, but you cannot store Addressable assets in a Resources folder. ``` ## Use an Addressable asset To load and use an Addressable asset, you can: * Use an AssetReference that references the asset * Use its address string * Use a label assigned to the asset Refer to Loading assets for more detailed information about loading Addressable assets. Loading Addressable assets uses asynchronous operations. Refer to Operations for information about the different ways to approach asynchronous programming in Unity scripts. ##### Tip ``` You can find more involved examples of how to use Addressable assets in the Addressables Sample repository. ``` ### Use AssetReferences To use an `AssetReference`, add an `AssetReference` field to a `MonoBehaviour` or `ScriptableObject`. After you create an object of that type, you can assign an asset to the field in your object's Inspector window. ##### Note ``` If you assign a non-Addressable asset to an AssetReference field, Unity automatically makes that asset Addressable and adds it to your default Addressables group. AssetReferences also let you use Addressable assets in a Scene that isn't itself Addressable. ``` Unity doesn't load or release the referenced asset automatically; you must load and release the asset using the `Addressables` API: ``` csharp using UnityEngine; using UnityEngine.AddressableAssets; using UnityEngine.ResourceManagement.AsyncOperations; internal class LoadWithReference : MonoBehaviour { // Assign in Editor public AssetReference reference; // Start the load operation on start void Start() { AsyncOperationHandle handle = reference.LoadAssetAsync<GameObject>(); handle.Completed += Handle_Completed; } // Instantiate the loaded prefab on complete private void Handle_Completed(AsyncOperationHandle obj) { if (obj.Status == AsyncOperationStatus.Succeeded) { Instantiate(reference.Asset, transform); } else { Debug.LogError(quot;AssetReference {reference.RuntimeKey} failed to load."); } } // Release asset when parent object is destroyed private void OnDestroy() { reference.ReleaseAsset(); } } ``` Refer to Loading an AssetReference for additional information about loading AssetReferences. ### Load by address You can use the address string to load an asset: ``` csharp using UnityEngine; using UnityEngine.AddressableAssets; using UnityEngine.ResourceManagement.AsyncOperations; internal class LoadWithAddress : MonoBehaviour { // Assign in Editor or in code public string address; // Retain handle to release asset and operation private AsyncOperationHandle<GameObject> handle; // Start the load operation on start void Start() { handle = Addressables.LoadAssetAsync<GameObject>(address); handle.Completed += Handle_Completed; } // Instantiate the loaded prefab on complete private void Handle_Completed(AsyncOperationHandle<GameObject> operation) { if (operation.Status == AsyncOperationStatus.Succeeded) { Instantiate(operation.Result, transform); } else { Debug.LogError(quot;Asset for {address} failed to load."); } } // Release asset when parent object is destroyed private void OnDestroy() { handle.Release(); } } ``` Remember that every time you load an asset, you must also release it. Refer to Loading a single asset for more information. ### Load by label You can load sets of assets that have the same label in one operation: ``` csharp using System.Collections.Generic; using UnityEngine; using UnityEngine.AddressableAssets; using UnityEngine.ResourceManagement.AsyncOperations; internal class LoadWithLabels : MonoBehaviour { // Label strings to load public List<string> keys = new List<string>() {"characters", "animals"}; // Operation handle used to load and release assets AsyncOperationHandle<IList<GameObject>> loadHandle; // Load Addressables by Label void Start() { float x = 0, z = 0; loadHandle = Addressables.LoadAssetsAsync<GameObject>( keys, // Either a single key or a List of keys addressable => { //Gets called for every loaded asset if (addressable != null) { Instantiate<GameObject>(addressable, new Vector3(x++ * 2.0f, 0, z * 2.0f), Quaternion.identity, transform); if (x > 9) { x = 0; z++; } } }, Addressables.MergeMode.Union, // How to combine multiple labels false); // Whether to fail if any asset fails to load loadHandle.Completed += LoadHandle_Completed; } private void LoadHandle_Completed(AsyncOperationHandle<IList<GameObject>> operation) { if (operation.Status != AsyncOperationStatus.Succeeded) Debug.LogWarning("Some assets did not load."); } private void OnDestroy() { // Release all the loaded assets associated with loadHandle loadHandle.Release(); } } ``` See Loading multiple assets for more information. ## Manage Addressable assets To manage your Addressable assets, use the Addressables Groups window. Use this window to create Addressables groups, move assets between groups, and assign addresses and labels to assets. When you first install and set up the Addressables package, it creates a default group for Addressable assets. The Addressables system assigns any assets you mark as Addressable to this group by default. At the start of a project, you might find it acceptable to keep your assets in this single group, but as you add more content, you should create additional groups so that you have better control over which resources your application loads and keeps in memory at any given time. Key group settings include: * Build path: Where to save your content after a content build. * Load path: Where your application looks for built content at runtime. ##### Note ``` You can use Profile variables to set these paths. Refer to Profiles for more information. ``` * **Bundle mode**: How to package the content in the group into a bundle. You can choose the following options: * One bundle containing all group assets * A bundle for each entry in the group (useful if you mark entire folders as Addressable and want their contents built together) * A bundle for each unique combination of labels assigned to group assets * **Content update restriction**: Setting this value allows you to publish smaller content updates. Refer to Content update builds for more information. If you always publish full builds to update your app and don't download content from a remote source, you can ignore this setting. For more information on strategies to consider when deciding how to organize your assets, refer to Organizing Addressable assets. For more information on using the Addressables Groups window, refer to Groups. ## Build Addressable assets The Addressables content build step converts the assets in your Addressables groups into AssetBundles based on the group settings and the current platform set in the Unity Editor. You can configure the Addressables system to build your Addressables content as part of every Player build or you can build your content separately before making a Player build. Refer to Building Addressables content with Player builds for more information about configuring these options. If you configure Unity to build your content as part of the Player build, use the normal **Build** or **Build and Run** buttons in the Editor Build Settings window to start a build. Unity builds your Addressables content as a pre-build step before it builds the Player. In earlier versions of Unity, or if you configure Unity to build your content separately, you must make an Addressables build using the **Build** menu on the **Addressables Groups** window. The next time you build the Player for your project, it uses the artifacts produced by the last Addressables content build run for the current platform. To start a content build from the Addressables Groups window: 1. Open the Addressables Groups window (menu: **Windows > Asset Management > Addressables > Groups**). 2. Choose an option from the Build menu: * **New Build**: perform a build with a specific build script. Use the Default Build Script if you don't have your own custom one. * **Update a Previous Build**: builds an update based on an existing build. To update a previous build, the Addressables system needs the addressables_content_state.bin file produced by the earlier build. You can find this file in the Assets/AddressableAssetsData/Platform folder of your Unity Project. Refer to Content Updates for more information about updating content. * **Clean Build**: deletes cached build files. By default, the build creates files in the locations defined in your Profile settings for the **LocalBuildPath** and **RemoteBuildPath** variables. The files that Unity uses for your player builds include AssetBundles (.bundle), catalog JSON and hash files, and settings files. ##### Warning ``` Don't change the local build or load paths from their default values. If you do, you must copy the local build artifacts from your custom build location to the project's StreamingAssets folder before making a Player build. Altering these paths also precludes building your Addressables as part of the Player build. ``` If you have groups that you build to the **RemoteBuildPath**, you must upload those AssetBundles, catalog, and hash files to your hosting server. If your Project doesn't use remote content, set all groups to use the local build and load paths. A content build also creates the following files that Addressables doesn't use directly in a player build: * `addressables_content_state.bin`: used to make a content update build. If you support dynamic content updates, you must save this file after each content release. Otherwise, you can ignore this file. * `AddressablesBuildTEP.json`: logs build performance data. For more information, refer to Build Profiling. Refer to Building Addressable content for more information about how to set up and perform a content build. ### Start a full content build To make a full content build: 1. Set the desired Platform Target on the **Build Settings** window. 2. Open the **Addressables Groups** window (menu: **Asset Management** > **Addressables** > **Groups**). 3. Choose the **New Build** > **Default Build Script** command from the Build menu of the Groups window. The build process starts. After the build is complete, you can perform a player build and upload any remote files from your **RemoteBuildPath** to your hosting server. ##### Important ``` If you plan to publish remote content updates without rebuilding your application, you must preserve the addressables_content_state.bin file for each published build. Without this file, you can only create a full content build and player build, not an update. Refer to Content update builds for more information. ``` ## Remote content distribution You can use Addressables to support remote distribution of content through a Content Delivery Network (CDN) or other hosting service. Unity provides the Unity Cloud Content Delivery (CCD) service for this purpose, but you can use any CDN or host you prefer. Before building content for remote distribution, you must: * Enable the **Build Remote Catalog** option in your AddressableAssetSettings (access using menu: **Windows > Asset Management > Addressables > Settings**). * Configure the **RemoteLoadPath** in the Profile you use to publish content to reflect the remote URL at which you plan to access the content. * For each Addressables group containing assets you want to deliver remotely, set the **Build Path** to **RemoteBuildPath** and the **Load Path** to **RemoteLoadPath**. * Set desired **Platform Target** on the Unity **Build Settings** window. After you make a content build (using the Addressables Groups window) and a player build (using the **Build Settings** window), you must upload the files created in the folder designated by your profile's **RemoteBuildPath** to your hosting service. The files to upload include: * AssetBundles (name.bundle) * Catalog (catalog_timestamp.json) * Hash (catalog_timestamp.hash) Refer to Distributing remote content for more information. ## Incremental content updates When you distribute content remotely, you can reduce the amount of data your users need to download for an update by publishing incremental content update builds. An incremental update build allows you to publish remote bundles which contain only the assets that have changed since you last published an update rather than republishing everything. The assets in these smaller, updated bundles override the existing assets. ##### Important ``` You must enable the Build Remote Catalog option before you publish a player build if you want to have the option to publish incremental updates. Without a remote catalog, an installed application doesn't check for updates. ``` For more detailed information about content updates, including examples, refer to Content update builds. ### Start a content update build To make a content update, rather than a full build: 1. In the **Build Settings** window, set the **Platform Target** to match the target of the previous content build that you are now updating. 2. Open the **Addressables Groups** window (menu: **Asset Management > Addressables > Groups**). 3. From the **Tools** menu, run the **Check for Content Update Restrictions** command. The **Build Data File** browser window opens. 4. Locate the `addressables_content_state.bin` file produced by the previous build. This file is in a subfolder of `Assets/AddressableAssestsData` named for the target platform. 5. Select **Open**. The **Content Update Preview** window searches for changes and identifies assets that must be moved to a new group for the update. If you have not changed any assets in groups set to "Cannot Change Post Release," then no changes will be listed in the preview. (When you change an asset in a group set to "Can Change Post Release," then Addressables rebuilds all the AssetBundles for the group; Addressables does not move the changed assets to a new group in this case.) 6. Select **Apply Changes** to accept any changes. 7. From the **Build** menu, run the **Update a Previous Build** command. 8. Open the `addressables_content_state.bin` file produced by the previous build. The build process starts. After the build is complete, you can upload the files from your **RemoteBuildPath** to your hosting server. ##### Important ``` Addressables uses the addressables_content_state.bin file to identify which assets you changed. You must preserve a copy of this file for each published build. Without the file, you can only create a full content build, not an update. ``` ## Addressables samples The Addressables package contains samples that you can download into your project. To access the samples go to **Window** > **Package Manager** > **Addressables**. These samples include examples on how to disable asset importing during a build, creating custom build and Play mode scripts, and providing an `AddressableUtility` class. When you download and import a sample, it's placed inside the `Assets/Samples/Addressables/{AddressablesVersionNumber}` path of your project. #### **Addressables Utility** Contains a set of utility functions for Addressables. The script contains a static method `GetAddressFromAssetReference` which provides the Addressable address used to reference a given `AssetRefence` internally. #### **ComponentReference** Creates an AssetReference that's restricted to having a specific component. For more information see the ComponentReference sample project located in the **Addressables Samples** repository. #### **Custom Build and Playmode Scripts** Includes two **custom scripts**: - A custom Play mode script located in `Editor/CustomPlayModeScript.cs` of the sample. This script works similarly to the Use Existing Build (requires built groups) play mode script already included. The methods added to accomplish this are `CreateCurrentSceneOnlyBuildSetup` and `RevertCurrentSceneSetup` on the `CustomBuildScript`. - A custom build script located in `Editor/CustomBuildScript.cs` of the sample. This custom build script creates a build that only includes the currently open scene. A bootstrap scene is automatically created and a script is added that loads the built scene on startup. For these examples, the build and load paths used by default are `[UnityEngine.AddressableAssets.Addressables.BuildPath]/[BuildTarget]` and `{UnityEngine.AddressableAssets.Addressables.RuntimePath}/[BuildTarget]` respectively. The `ScriptableObject` of the class has already been created, but you can use the Create menu to make another `ScriptableObject`. For this `CustomPlayModeScript` the create menu path is **Addressables > Content Builders > Use CustomPlayMode Script**. By default, this creates a CustomPlayMode.asset ScriptableObject. The same goes for the `CustomBuildScript`. #### **Disable Asset Import on Build** Provides a script that disables asset importing during a player build. This improves build performance because `AssetBundles` are copied into StreamingAssets at build time. This sample is only relevant for Editor versions below 2021.2. In 2021.2+, the Editor provides the ability to include folders outside of `Assets/` into `StreamingAssets`. When the sample is imported into the project, a player build without asset importing can be triggered by the new menu item **Build/Disabled Importer Build**. The build output is placed into `DisabledImporterBuildPath/{EditorUserBuildSettings.activeBuildTarget}/` by default. The sample class `DisableAssetImportOnBuild` can be edited to alter the build path. #### **Import Existing Group** Contains a tool that imports group assets, for example from a custom package, to the current project. The tool is located under `Window/Asset Management/Addressables/Import Groups`. The window requires a path to the `AddressableAssetGroup.asset` scriptable object, a name for the group, and a folder for any schemas related to the imported `AddressableAssetGroup`. #### **Prefab Spawner** Provides a basic script that instantiates and destroys a prefab `AssetReference`. To use the sample, attach the provided script, `PrefabSpawnerSample`, to a `GameObject` in your scene. Assign an `AdressableAsset` to the `AssetReference` field of that script. If you're using the `Use Existing Build` playmode script, ensure that your Addressable content is built. Then, enter Play mode. #### **Custom Analyze Rules** This sample shows how to create custom AnalyzeRules for use within the Analyze window. Both rules follow the recommended pattern for adding themselves to the UI. # Manage Addressables The main way to organize and manage addressables is to use groups and profiles. This section outlines how to use these to effectively manage addressables. | **Topic** | **Description** | | ------------------------------------- | --------------------------------------------------------------------------------- | | Manage Addressables introduction | Understand the different ways to manage addressables in your project. | | Organize Addressable assets | Understand the different approaches to organize addressable assets. | | Groups overview | Use groups to organize the different assets in your project. | | Profiles overview | Use profiles to manage how to build addressable assets. | | Asset references overview | Use asset references to customize `MonoBehaviour` and `ScriptableObject` scripts. | | Addressables Asset Settings reference | Reference information for Addressable Asset Settings | | Addressables Preferences reference | Reference information for the Addressables Preferences window. | ## Manage Addressables introduction Before you decide how you want to manage the assets in your project, refer to How Addressables interacts with your project assets. Addressable groups are the main unit of organization that you use to manage Addressable assets. An important consideration are your options for packing groups into AssetBundles. Alongside group settings, you can use the following to control how Addressables work in a project: * Addressable asset settings: The project-level settings of Addressable assets. * Profiles: Defines collections of build path settings that you can switch between depending on the purpose of a build. Primarily of interest if you plan to distribute content remotely. * Labels: Edit the Addressable asset labels used in your project. * Play mode scripts: Choose how the Addressables system loads assets when you enter Play mode in the Editor. AssetReferences offer a UI-friendly way to use Addressable assets. You can include AssetReference fields in MonoBehaviour and ScriptableObject classes and then assign assets to them in the Unity Editor using drag-and-drop or the object picker dialog. The Addressables system provides the following additional tools to help development: * Build layout report: provides a description of the AssetBundles produced by a build. * Build profile log: provides a log profiling the build process itself so that you can see which parts take the longest. ### Further resources Organize Addressable assets ## Organize Addressable assets The best way to organize your assets depends on the specific requirements of each project. Aspects to consider when planning how to manage your assets in a project include: - **Logical organization**: Keep assets in logical categories to make it easier to understand your organization and discover items that are out of place. - **Runtime performance**: Performance bottlenecks can happen if your AssetBundles grow in size, or if you have many AssetBundles. - **Runtime memory management**: Keep assets together that you use together to help lower peak memory requirements. - **Scale**: Some ways of organizing assets might work well in small games, but not large ones, and vice versa. - **Platform characteristics**: The characteristics and requirements of a platform can be a large consideration in how to organize your assets. Some examples: - Platforms that offer abundant virtual memory can handle large bundle sizes better than those with limited virtual memory. - Some platforms don't support downloading content, ruling out remote distribution of assets entirely. - Some platforms don't support AssetBundle caching, so putting assets in local bundles, when possible, is more efficient. - **Distribution**: Whether you distribute your content remotely or not means that you must separate your remote content from your local content. - **How often assets are updated**: Keep assets that you expect to update often separate from those that you plan to rarely update. - - **Version control**: The more people who work on the same assets and asset groups, the greater the chance for version control conflicts to happen in a project. ### Common strategies Typical strategies for organizing assets include: - **Concurrent usage**: Group assets that you load at the same time together, such as all the assets for a given level. This strategy is often the most effective in the long term and can help reduce peak memory use in a project. - **Logical entity**: Group assets belonging to the same logical entity together. For example, UI layout assets, textures, sound effects. Or character models and animations. - **Type**: Group assets of the same type together. For example, music files, textures. Depending on the needs of your project, one of these strategies might make more sense than the others. For example, in a game with many levels, organizing according to concurrent usage might be the most efficient both from a project management and from a runtime memory performance standpoint. At the same time, you might use different strategies for different types of assets. For example, your UI assets for menu screens might all be grouped together in a level-based game that otherwise groups its level data separately. You might also pack a group that has the assets for a level into bundles that contain a particular asset type. Refer to Preparing Assets for AssetBundles for additional information. ## Safely edit loaded assets You can safely edit loaded Assets in the following situations: * The Asset is loaded from an AssetBundle. * The application is running in a Player, not in the Editor. * When you enable the Use Existing Build (requires built groups) option in Play Mode Scripts. In these cases, the assets exist as a copy in active memory. Changes made to these copied assets don't affect the saved AssetBundle on disk and any changes don't persist between sessions. For other situations, including when you enable the Use Asset Database (fastest) property in the Play mode settings, Unity loads the Assets directly from the Project files. This means that Unity saves any modifications to the Asset during runtime to the Project Asset file and that those changes will persist between different sessions. If you want to make runtime changes to an asset, create a new instance of the GameObject you want to change and use the copy for any runtime changes. This eliminates the risk that you might accidentally change the original asset file. The following code example demonstrates creating a new copy of a loaded asset: ``` csharp var op = Addressables.LoadAssetAsync<GameObject>("myKey"); yield return op; if (op.Result != null) { GameObject inst = UnityEngine.Object.Instantiate(op.Result); // can now use and safely make edits to inst, without the source Project Asset being changed. } ``` If you use this example method to use a copy of an asset, be aware of the following: * You must use either the original asset or the AsyncOperationHandle when you release the asset, not the current instance of the asset. * When you instantiate an asset that has references to other assets in this way, Unity doesn't create new instances of the referenced assets. The references for the newly instantiated copy target the original project asset. * Unity invokes MonoBehaviour methods like Start(), OnEnable(), and OnDisable() on the new instance. ## Groups overview A group is the main organizational unit of the Addressables system. Create and manage your groups and the assets they contain with the Addressables Groups window. | Topic | Description | | ------------------------------------ | ----------------------------------------------------------- | | Groups introduction | Understand groups and how to work with them. | | Manage and create groups | Create profiles in the Unity Editor. | | Labels overview | Understand and work with labels. | | Create a group template | Create group templates. | | Pack groups into AssetBundles | Understand how you can put groups into AssetBundles. | | Addressables Groups window reference | Reference information for the Addressables Groups window. | | Group settings and schemas overview | Reference information for group settings and their schemas. | ### Groups introduction A group is the main organizational unit of the Addressables system. Create and manage your groups and the assets they contain with the Addressables Groups window. To control how Unity handles assets during a content build, organize Addressables into groups and assign different settings to each group as required. Refer to Organizing Addressable Assets for information about how to organize your assets. When you begin a content build, the build scripts create AssetBundles that contain the assets in a group. The build determines the number of bundles to create and where to create them from both the settings of the group and your overall Addressables system settings. Refer to Builds for more information. ##### Note ``` Addressable Groups only exist in the Unity Editor. The Addressables runtime code doesn't use a group concept. However, you can assign a label to the assets in a group if you want to find and load all the assets that were part of that group. Refer to Loading Addressable assets for more information about selecting the assets to load using labels. ``` ### Manage and create groups To manage your groups and Addressables assets, open the Addressables Groups window by going to **Window >Asset Management > Addressables > Groups**. Refer to Addressables Groups window for details about the features of this window. #### Create a group To create a group: 1. Go to **Window > Asset Management > Addressables** and select **Groups** to open the Addressables Groups window. 2. Select **New > Packed Asset** to create a new group. If you've created your own group templates, they are also displayed in the menu. 3. Context click the new group and select **Rename** to rename the group. 4. Open the context menu again and select **Inspect Group Settings**. 5. Adjust the group settings as desired. For groups that contain assets that you plan to distribute with your main application, the default settings are a reasonable starting point. For groups containing assets that you plan to distribute remotely, you must change the build and load paths to use the remote versions of the Profile path variables. To build AssetBundles for remote distribution, you must also enable the **Build Remote Catalog** option in the Addressable System Settings. Refer to Group settings for more information about individual settings. #### Add assets to a group Use one of the following methods to add an asset to a group: * Drag the assets from the Project window into the Group window and drop them into the desired group. * Drag the assets from one group into another. * Select the asset to open it in the Inspector window and enable the **Addressables** option. This adds the asset to the default group. Use the group context menu to change which group is the default group. * Add the folder containing the assets to a group. All assets added to the folder are included in the group. ##### Note ``` If you add assets in a Resources folder to a group, the Addressables system first moves the assets to a non-Resource location. You can move the assets elsewhere, but you can't store Addressable assets in a Resources folder in your project. ``` #### Remove assets from a group Select one or more assets in the Groups window and right-click to open the context menu, then select **Remove Addressables**. You can also select the assets and press the Delete key to remove the assets from the group. #### Add or remove labels Select one or more assets in the Groups window, then select the label field for one of the selected assets. To assign labels, enable or disable the checkboxes for the desired labels. To add, remove or rename your labels, select the + button, then select **Manage Labels**. To only add a new label, select the + button and then select **New Label**. Refer to Labels for more information on how to use labels. ### Labels overview You can tag your Addressable assets with one or more labels in the Addressables Groups window. Labels have a few uses in the Addressables system, including: * You can use one or more labels as keys to identify which assets to load at runtime. * You can pack assets in a group into AssetBundles based on their assigned labels. * You can use labels in the filter box of the Groups window to help find labeled assets When you load assets using a list of labels, you can specify whether you want to load all assets that have any label in the list or only assets that have every label in the list. For example, if you used the labels, `characters` and `animals` to load assets, you could choose to load the union of those two sets of assets, which includes all characters and all animals, or the intersection of those two sets, which includes only characters that are animals. Refer to Loading multiple assets for more information. When you choose to pack assets in a group based on their assigned labels using the group Bundle Mode setting, the Addressables build script creates a bundle for each unique combination of labels in the group. For example, if you have assets in a group that you have labeled as either cat or dog and either small or `large`, the build produces four bundles: one for small cats, one for small dogs, one for large cats, and another for large dogs. #### Managing labels To create and delete labels, use the Labels window, which is accessible from the Addressables Groups window (**Window > Asset Management > Addressables > Groups > Tools > Windows > Labels**). The Labels window displays a configurable list of labels. The Labels window. To create a new label, select the + button at the bottom of the list. Enter the new name and click **Save**. To delete a label, select it in the list and then select the - button. Deleting a label also removes it from all assets. ##### Tip ``` Until you run an Addressables build, you can undo the deletion of a label by adding it back to the Labels dialog (using the exact same string). This also adds the label back to its original assets. After you run an Addressables build, however, re-adding a deleted label no longer reapplies it to any assets. ``` ### Create a group template A group template defines which types of schema objects Unity creates for a new group. The Addressables system includes the Packed Assets template, which includes all the settings needed to build and load Addressables using the default build scripts. If you want to create your own build scripts or utilities that need additional settings, you can define these settings in your own schema objects and create your own group templates. The following instructions describe how to do this: 1. Navigate to the desired location in your Assets folder using the Project panel. 2. Create a Blank Group Template (menu: Assets > Addressables > Group Templates > Blank Group Templates). 3. Assign a name to the template. 4. In the Inspector window, add a description, if desired. 5. Click the Add Schema button and choose from the list of schemas. Repeat these steps to add as many new schemas as needed. ##### Note ``` If you use the default build script, a group must use the Content Packing & Loading schema. If you use content update builds, a group must include the Content Update Restrictions schema. Refer to Builds for more information. ``` ### Pack groups into AssetBundles You have a few options when choosing how the assets in a group are packed into AssetBundles: * You can pack all Addressables assigned to a group together in a single bundle. This corresponds to the Pack Together bundle mode. * You can pack each Addressable assigned to a group separately in its own bundle. This corresponds to the Pack Separately bundle mode. * You can pack all Addressables sharing the same set of labels into their own bundles. This corresponds to the Pack Together By Label bundle mode. For more information on bundle modes, refer to Advanced Group Settings. Scene assets are always packed separately from other Addressable assets in the group. Therefore, a group containing a mix of scene and non-scene assets always produces at least two bundles when built: one for scenes and one for everything else. Assets in folders that are marked as Addressable and compound assets like sprite sheets are treated specially when you choose to pack each Addressable separately: * All the assets in a folder that are marked as Addressable are packed together in the same folder (except for assets in the folder that are individually marked as Addressable themselves). * Sprites in an Addressable Sprite Atlas are included in the same bundle. See Content Packing & Loading settings for more information. ##### Note ``` Keeping many assets in the same group can increase the chance of version control conflicts when many people work on the same project. ``` #### AssetBundle packing strategy The choice whether to pack your content into a few large bundles or into many smaller bundles, can have consequences at either extreme: Dangers of too many bundles: * Each bundle has memory overhead. If you anticipate hundreds or even thousands of bundles loaded in memory at once, this could mean a noticeable amount of memory used. * There are concurrency limits for downloading bundles. If you have thousands of bundles you need all at once, they can't all be downloaded at the same time. Some number will be downloaded, and as they finish, more will trigger. In practice this is a fairly minor concern, so minor that you'll often be gated by the total size of your download, rather than how many bundles it's broken into. * Bundle information can bloat the catalog. To be able to download or load catalogs, Unity stores string-based information about your bundles. Thousands of bundles worth of data can greatly increase the size of the catalog. * Greater likelihood of duplicated assets. For example, if you have two materials are marked as Addressable and each depend on the same texture. If they are in the same bundle, then the texture is pulled in once, and referenced by both. If they are in separate bundles, and the texture is not itself Addressable, then it will be duplicated. You then either need to mark the texture as Addressable, accept the duplication, or put the materials in the same bundle. See Asset and AssetBundle dependencies for more information. Dangers of too few bundles: * The UnityWebRequest (which Unity uses to download) does not resume failed downloads. So if a large bundle is downloading and your user loses connection, the download is started over once they regain connection. * Items can be loaded individually from bundles, but cannot be unloaded individually. For example, if you have 10 materials in a bundle, load all 10, then tell Addressables to release 9 of them, all 10 will likely be in memory. See Memory management for more information. #### Scale implications as your project grows larger As your project grows larger, be aware of the following aspects of your assets and bundles: * Total bundle size: Historically Unity has not supported files larger than 4GB. This has been fixed in some recent editor versions, but there can still be issues. You should keep the content of a given bundle under this limit for best compatibility across all platforms. * Bundle layout at scale: The memory and performance trade-offs between the number of AssetBundles produced by your content build and the size of those bundles can change as your project grows larger. * Bundle dependencies: When an Addressable asset is loaded, all of its bundle dependencies are also loaded. Be aware of any references between assets when creating Addressable groups. Refer to Asset and AssetBundle dependencies for more information. * Sub assets affecting UI performance: There is no hard limit here, but if you have many assets, and those assets have many subassets, it might be best to disable sub-asset display. This option only affects how the data is displayed in the Groups window, and does not affect what you can and cannot load at runtime. The option is available in the groups window under Tools> Show Sprite and Subobject Addresses. Disabling this will make the UI more responsive. * Group hierarchy display: Another UI-only option to help with scale is Group Hierarchy with Dashes. This is available within the inspector of the top level settings. With this enabled, groups that contain dashes - in their names will display as if the dashes represented folder hierarchy. This does not affect the actual group name, or the way things are built. For example, two groups called x-y-z and x-y-w would display as if inside a folder called x, there was a folder called y. Inside that folder were two groups, called x-y-z and x-y-w. This doesn't affect UI responsiveness, but simply makes it easier to browse a large collection of groups. ### Addressables Groups window reference Use the Addressables Groups window to manage your groups and Addressable assets. To open the window, go to Window > Asset Management > Addressables > Groups. The Groups window also serves as a central location for starting content builds and accessing the tools and settings of the Addressables system. A group is the main organizational unit of the Addressables system. Use this window to create and manage your groups and the assets they contain. The Addressables Groups window showing the toolbar and list of groups and assets. The Addressables Groups window showing the toolbar and list of groups and assets. #### Group list The Group list displays the Addressable groups in your Project. Expand a group in the list to display the assets that it contains. You can also expand composite assets, such as sprite sheets, to display the sub-objects they contain. When you first install the Addressables package, the Groups window displays two groups of assets: * Default Local Group (Default): Initially empty, Unity adds any assets you make Addressable to this group. The group is set up so that its assets are built to your local build path and included in your Project builds. You can change the name, settings, and make another group the default group, if desired. The settings of the default group are also used to create shared AssetBundles. The list columns contain the following information: | **Column** | **Description** | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Notifications** | Any notifications about a Group, or asset, that's flagged during the build. | | **Group Name \ Addressable Name** | The name of the item. For groups, this is an arbitrary name that you can assign. For assets, this is the Addressable address. You can edit the name or address using the context menu. | | **Icon** | The Unity asset icon based on asset type. | | **Path** | The path to the source asset in your project. | | **Labels** | Displays any labels assigned to the asset. Click on a label entry to change the assigned labels or to manage your label definitions. | To sort the assets displayed in the group list, select one of the column headers. This sorts the assets within each group, but doesn't reorder the groups. To change the order that the groups are displayed, drag them into the desired position. #### Groups window toolbar The toolbar at the top of the Addressables Group window provides the following settings: | **Setting** | **Description** | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **New** | Choose a template to create a new group, or blank for no schema. Refer to [Group templates](https://docs.unity3d.com/Packages/com.unity.addressables@2.7/manual/GroupTemplates.html) for information about creating your own templates. | | **Profile** | Set the active Profile to select the paths used for building and loading Addressables. Choose an existing profile or select **Manage Profiles** to open the [Profiles window](https://docs.unity3d.com/Packages/com.unity.addressables@2.7/manual/AddressableAssetsProfiles.html). | | **Tools** | Open the various Addressables tools available. Choose from: <br> <br>- **Inspect System Settings**: Open the [Addressables Settings](https://docs.unity3d.com/Packages/com.unity.addressables@2.7/manual/AddressableAssetSettings.html) Inspector. <br>- **Check for Content Update Restrictions**: Run a pre-update content check. Refer to [Update Restrictions](https://docs.unity3d.com/Packages/com.unity.addressables@2.7/manual/ContentUpdateWorkflow.html) for more information. <br>- **Window**: Open other Addressables system windows: [Profiles](https://docs.unity3d.com/Packages/com.unity.addressables@2.7/manual/AddressableAssetsProfiles.html), [Labels](https://docs.unity3d.com/Packages/com.unity.addressables@2.7/manual/Labels.html), or the [Addressables Report](https://docs.unity3d.com/Packages/com.unity.addressables@2.7/manual/AddressablesReportOverview.md) window. <br>- **Groups View**: Set Group window display options: <br>- **Show Sprite and Subobject Addresses**: Enable to display sprite and sub-objects in the Group list or just the parent object <br>- **Group Hierarchy with Dashes**: Enable to display groups that contain dashes `-` in their names as if the dashes represented a group hierarchy. For example, if you name two groups `x-y-z` and `x-y-w`, the window displays an entry called `x` with a child called `y`, which contains two groups, called `x-y-z` and `x-y-w`. Enabling this option affects the group display only. | | **Play Mode Script** | Set the active Play Mode Script. The active Play Mode Script determines how Addressables are loaded in the Editor Play mode. Refer to [Play Mode Scripts](https://docs.unity3d.com/Packages/com.unity.addressables@2.7/manual/GroupsWindow.html#play-mode-scripts) for more information. | | **Build** | Select a content build command: <br> <br>- **New Build**: Choose a build script to run a full content build. <br>- **Update a Previous Build**: Run a differential update based on an earlier build. <br>- **Clear Build Cache**: choose a command to clean existing build artifacts. <br> <br>Refer to [Builds](https://docs.unity3d.com/Packages/com.unity.addressables@2.7/manual/Builds.html) for more information. | #### Play Mode Scripts The active Play Mode Script determines how the Addressable system accesses Addressable assets when you run your game in Play mode. When you select a Play Mode Script, it remains the active script until you choose a different one. The Play Mode Script has no effect on asset loading when you build and run your application outside the Unity Editor. The Play Mode Scripts include: * Use Asset Database: Loads assets directly from the Editor Asset Database, which is also used for all non-Addressable assets. You don't have to build your Addressable content when using this option. * Use Existing Build: Loads assets from bundles created by an earlier content build. You must run a full build using a Build Script such as Default Build Script before using this option. Remote content must be hosted at the RemoteLoadPath of the Profile used to build the content. #### Find an asset To locate an Addressable Asset in the Groups window, type all or part of its address, path, or a label into the filter control on the Groups window toolbar. Filtering the group list by the string "NP" to find all assets labeled NPC. Filtering the group list by the string "NP" to find all assets labeled NPC To locate the asset in your project, select it in the Groups window. Unity then selects the asset in the Project window and displays the asset's details in the Inspector window. ##### Tip ``` * To view the groups of the assets found, enable Hierarchical Search. Disable this option to only display groups if they match the search string. Select the magnifying glass icon in the search box to enable or disable Hierarchical Search. * To view sub-object addresses, such as the Sprites in a Sprite Atlas, enable the Show Sprite and Subobject Addresses option using the Tools menu on the Groups window toolbar. ``` #### Group context menu To open the Group context menu and access group-related commands, right-click on a group name. | **Command** | **Description** | | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Remove Group(s)** | Removes the Group and deletes its associated ScriptableObject asset. Unity reverts any assets in the group into non-Addressable assets. | | **Simplify Addressable Names** | Shortens the name of assets in the group by removing path-like components and extensions. | | **Set as Default** | Sets the group as the default group. When you mark an asset as Addressable without explicitly assigning a group, Unity adds the asset to the default group. | | **Inspect Group Settings** | Selects the group asset in the Unity Project window and in the Inspector window so that you can view the settings. | | **Rename** | Enables you to edit the name of the group. | | **Create New Group** | Creates a new group based on a group template. | #### Asset context menu To open the Addressable asset context menu and access asset-related commands, right-click on an asset. |**Command**|**Description**| |---|---| |**Move Addressables to Group**|Move the selected assets to a different, existing group.| |**Move Addressables to New Group**|Create a new group with the same settings as the current group and move the selected assets to it.| |**Remove Addressables**|Remove the selected assets from the Group and make the assets non-Addressable.| |**Simplify Addressable Names**|Shortens the names of the selected assets by removing path-like components and extensions.| |**Copy Address to CLipboard**|Copies the asset's assigned address string to your system Clipboard.| |**Change Address**|Edit the asset's name.| |**Create New Group**|Create a new group based on a group template. This doesn't move the selected assets.| # Build content overview # Distribute remote content # Use Addressable at runtime # Load Addressable assets # Diagnostic tools ## Analyze tool ## Addressables Profiler module ## Build layout report ## Build profile log ## Addressables Report window reference ### Addressables Report Inspector reference