Addressables provides a system that can grow with your project. You can start with a simple setup and reorganize as your project grows in complexity and team size, and you can do it all with minimal code changes.
For example, you can start with a set of addressable assets, which Unity will load as a collection. Then, as you add more content, you can split your resources into groups so you only load the resources you need at a given time. As your team grows, you can create separate Unity projects to develop different types of assets. These side projects can generate their own builds of Addressables content that you can load from the main project (again with minimal code changes).
This overview discusses the following concepts to help you understand how to manage and use your assets with the Addressables system:
- Asset Address : A string ID that identifies an addressable asset. You can use addresses as keys to load assets.
- AssetReferences : A type that can be used to support the assignment of addressable assets to fields in inspector windows. You can use an AssetReference instance as a key for loading assets. The AssetReference class also provides its own load method.
- Label : A label that you can assign to multiple assets and use to load related assets together as a group. You can use tags as keys to load assets.
- Asset Location : A runtime object that describes how an asset and its dependencies are loaded. You can use a location object as a key for loading assets.
- Key : Identifies one or more addressable objects. Keys include addresses, labels, AssetReference instances, and location objects.
- Asset loading and unloading : The Addressables API provides its own functions to load and release assets at runtime.
- Dependencies : Asset dependencies are when an asset is used by another asset, 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 keep track of which Assets and AssetBundles are in use, including whether the system should load or unload dependencies (assets that are referenced by other).
- Groups : You can assign assets to groups in the editor. Group settings determine how Addressables packages group assets into AssetBundles, and how it loads them at runtime.
- Content Catalog : Addressables uses catalogs to map your assets to the resources that contain them.
- Content building : When using Addressables, you can organize and package your assets as a separate step before building the player.
- Multi-platform support : The build system separates what is built for the platform and resolves the correct path at runtime.
- Addressables Tools : The Addressables package contains several windows and tools for organizing, structuring, and optimizing content.
By default, Addressables uses AssetBundles to package your assets. You can also implement your own IResourceProvider class to support other ways of accessing assets.
asset address
A key feature of the Addressables system is that you can assign addresses to your assets and use those addresses to load them at runtime. The Addressables explorer looks up addresses in the content directory to find out where assets are stored. (Assets can be built into your application, cached locally, or hosted remotely.) The resource manager loads the asset and any dependencies, first downloading the content if necessary.
Addressables load assets by address, no matter where they are located
Since addresses are independent of the asset's physical location, you have more flexibility when managing and optimizing assets in the Unity editor and runtime. Directories map addresses to physical locations.
Although, you should generally assign unique addresses to your assets, asset addresses do not need to be unique. You can assign the same address string to multiple assets when useful. For example, if you have variants of an asset, you can assign the same address to all variants and use labels to differentiate the variants:
- Asset 1: address: "plate_armor_rusty", label: "hd"
- Asset 2: address: "plate_armor_rusty", label: "sd"
Addressable API functions that only load a single asset (such as LoadAssetAsync ) load the first instance found (if you call them with addresses assigned to multiple assets). Other functions, like LoadAssetsAsync , load multiple assets in one operation and load all assets with a specified address.
hint
You can use the MergeMode parameter of LoadAssetsAsync to load the intersection of two keys.
In the example above, you could specify the address "plate_armor_rusty" and the label "hd" as the key and intersection as the merge mode to load "asset 1". You can change the tag value to "sd" to load "Asset 2".
For information on how to assign addresses to assets, see Making Assets Addressable.
See Loading Assets to learn how to load assets by key, including addresses.
asset reference
AssetReference is a type that you can set to any type of addressable asset. Unity does not automatically load assets assigned to references, so you have more control over when it is loaded and unloaded.
Use fields of type AssetReference in MonoBehaviours and ScriptableObjects to help you specify the addressable asset to use for the field (instead of using a string specifying the address). AssetReferences support drag-and-drop and object picker assignment, which makes them easier to use in the Editor Inspector.
In addition to the basic AssetReference type, Addressables also provides some more specialized types, such as AssetReferenceGameObject and AssetReferenceTexture. You can use these specialized subclasses to eliminate the possibility of assigning the wrong type of asset to an AssetReference field. Additionally, you can use the AssetReferenceUILabelRestriction property to restrict assignments to assets with specific labels.
See Working with AssetReferences for details.
Load and release assets
To load an addressable asset, you can use its address or other keys such as tags or AssetReferences. See Loading Addressable Assets for details. You only need to load the main asset; Addressables will automatically load any dependent assets.
When your application no longer needs access to an Addressable asset at runtime, you must release it so that the Addressables can release the associated memory. The Addressables system keeps reference counts of loaded assets. It will not unload the asset until the reference count reaches zero. So you don't need to keep track of whether the asset or its dependencies are still in use; you just need to make sure that whenever you explicitly load the asset, you release the instance when your application no longer needs it. For more information, see Releasing Addressable Assets.
Dependency and resource management
An asset in Unity can depend on another asset. A scene may reference one or more prefabs; a prefab may use one or more materials. The same material can be used by multiple prefabs, and these prefabs can exist in different AssetBundles. When you load an addressable asset, the system automatically finds and loads any dependent assets it references. When the system unloads an asset, it also unloads its dependencies - unless they are still being used by a different asset.
The Addressables system keeps a reference count for each item as you load and release assets. Addressables will unload an asset when it is no longer referenced. If the asset is in a bundle that no longer contains any assets in use, Addressables will also uninstall the bundle.
See Memory Management for details.
Addressable Groups and Labels
Use addressable groups to organize your content. All addressable assets belong to a group. If you don't explicitly assign an asset to a group, Addressables will add it to the default group.
You can set group settings to specify how the Addressables build system should package assets in a group into bundles. For example, you can choose whether to package all assets in a set into one AssetBundle file.
Use tags to mark things that you want to work on together in a certain way. For example, if you define tags for "red", "hat" and "feather", you can load all red hats with feathers in one operation, whether they belong to the same AssetBundle or not. Additionally, you can use tags to determine how assets in a group are packaged into bundles.
Use the Addressables Groups window to add assets to groups and move assets between groups. You can also assign tags to your assets in the Groups window.
group mode
The schema assigned to a group defines the settings used to build assets in the group. Different modes can define different groups of settings. For example, a standard schema defines settings (among other options) for how assets are packaged and compressed into an AssetBundle. Another standard schema defines which of the "can change post-publish" and "cannot change post-publish" categories the assets in the group fall into.
You can define your own schema for use with custom build scripts.
For more information on group modes, see Modes.
content directory
The Addressables system generates a content catalog file that maps your asset addresses to their physical locations. It can also create a hash file which contains the hash value (mathematical fingerprint) of the directory. If you host addressable assets remotely, this hash file is used to determine if the content directory has changed and needs to be downloaded. See Contents for details.
The profile selected when performing content builds determines how addresses in the content directory are mapped to resource load paths. See the configuration file for details.
For information about hosting content remotely , see Distributing content remotely.
content construction
The Addressables system separates the construction of Addressable content from the construction of the player. Content builds generate a content catalog, a catalog hash, and an AssetBundle containing your assets.
Since the asset format is platform-specific, you must build the content for each platform before building the player.
For more information, see Building Addressable Content.
play mode script
When you run your game or application in editor play mode, it can be inconvenient and slow to always perform content builds before pressing the play button. At the same time, you really want to be able to run your game as close to the built-in player as possible. For flexibility, Addressables provides three options to determine how the Addressables system locates and loads assets in play mode:
- Using an asset database : Addressables loads assets directly from the asset database. If you're changing code and assets at the same time, this option usually provides the fastest iteration speed, but is also the least like a production build.
- Mock groups : Addressables loads assets when mocking groups. This option is useful if you are organizing and optimizing your Addressables group. It provides Addressables events without rebuilding the full content after each change.
- Use an existing build : Addressables loads content from your last content build. This option is most similar to a production build and provides a quick iterative turnaround if you don't change assets.
See Play Mode Scripts for details.
Support multiple platforms
Addressables supports projects designed for multiple platforms by including the target platform name in the build path and ensuring that the correct platform files are copied to the StreamingAssets folder when you build the player.
addressing tool
The Addressables system provides several tools and windows to help you manage Addressable assets:
- Addressable Groups window : The Groups window is the main interface for managing assets, group settings, and builds.
- Configuration file window : Helps set the paths used by your build.
- Addressables Event Viewer : Monitor and analyze runtime events related to your Addressable assets.
- Analysis tools : Analysis tools run analysis rules, checking that your addressable content conforms to the set of rules you define. The Addressables system provides some basic rules, such as checking for duplicate assets; you can add your own rules using the AnalyzeRule class.
- Hosting Tools : Hosting Tools provides a simple asset hosting service that runs from the Unity Editor to aid in the development and testing of projects.
- Build Layout Report : Describes the AssetBundle generated by the content build.