Group settings
Group settings determine how the assets in a group are treated in content builds. For example, you can specify where AssetBundles are built, bundle compression settings, and so on.
A group's settings are declared in Schema objects attached to the group. When you create a group with the Packed Assets template, the Content Packing & Loading and Content Update Restriction schemas define the settings for the group. These settings are expected by the default Build scripts.
The Inspector window for the Default Local Group
Note
If you create a group with the Blank template, then no schemas are attached to the group. Assets in such a group cannot be processed by the default build scripts.
Content Packing & Loading settings
Build and Load Paths
The Build and Load Paths settings of the Content Packing & Loading schema determine where the artifacts for your content builds are created and where the Addressables system should look for them at runtime.
Building and loading paths
| Setting | Purpose |
|---|---|
| Build & Load Paths | The Profile path pair that defines where the Addressables build system creates artifacts for this group and where the Addressables system loads those artifacts at runtime. Choose a path pair from the list or select <custom> if you want to set the build and load paths separately. |
| Build Path | A Profile variable that defines where the Addressables build system creates artifacts for this group. You can also set a custom string. Use one of the following for the build path: - LocalBuildPath: use for assets that you plan to distribute as part of your application installation. - RemoteBuildPath: use for assets that you plan to distribute using a remote hosting service such Unity Cloud Content Delivery or other Content Delivery Network. - <custom>: specify a string as the build path for this group. Only shown if you set Build & Load Paths to <custom>. |
| Load Path | A Profile variable that defines where the Addressables system loads the build artifacts for this group at runtime. You can also set a custom string. Use one of the following for the load path: - LocalLoadPath: use for assets that you plan to distribute as part of your application installation. - RemoteLoadPath: use for assets that you plan to distribute using a remote hosting service such Unity Cloud Content Delivery or other Content Delivery Network. - <custom>: specify a string as the load path for this group. Only shown if you set Build & Load Paths to <custom>. |
The build and load path options are defined by variables in your Profiles. Note that only variables intended for a given purpose should be used for a setting. For example, choosing a load path variable for a build path setting wouldn't give you a useful result.
When you choose a Profile variable, the current evaluation of the path is shown in the Path Preview. Components of the path in braces, such as {UnityEngine.AddressableAssets.Addressable.RuntimePath}, indicate that static variable is used to construct the final path at runtime. That portion of the path is replaced by the current value of the static variable when the Addressables system initializes at runtime.
Warning
In most cases, you should not 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.
See Profiles for more information.
Advanced Options
The Advanced Options section
| Setting | Purpose |
|---|---|
| Asset Bundle Compression | The compression type for all bundles produced from the group. LZ4 is usually the most efficient option, but other options can be better in specific circumstances. See AssetBundle Compression for more information. |
| Include In Build | Whether to include assets in this group in a content build. |
| Force Unique Provider | Whether Addressables uses unique instances of Resource Provider classes for this group. Enable this option if you have custom Provider implementations for the asset types in this group and instances of those Providers must not be shared between groups. |
| Use Asset Bundle Cache | Whether to cache remotely distributed bundles. |
| Asset Bundle CRC | Whether to verify a bundle's integrity before loading it. • Disabled: Never check bundle integrity. • Enabled, Including Cached: Always check bundle integrity. • Enabled, Excluding Cached: Check integrity of bundles when downloading. |
| Use UnityWebRequest for Local Asset Bundles | Load local AssetBundle archives from this group using UnityWebRequestAssetBundle.GetAssetBundle instead of AssetBundle.LoadFromFileAsync. |
| Request Timeout | The timeout interval for downloading remote bundles. |
| Use Http Chunked Transfer | Whether to use the HTTP/1.1 chunked-transfer encoding method when downloading bundles. Deprecated and ignored in Unity 2019.3+. |
| Http Redirect Limit | The number of redirects allowed when downloading bundles. Set to -1 for no limit. |
| Retry Count | The number of times to retry failed downloads. |
| Include Addresses in Catalog | Whether to include the address strings in the catalog. If you don't load assets in the group using their address strings, you can decrease the size of the catalog by not including them. |
| Include GUIDs in Catalog | Whether to include GUID strings in the catalog. You must include GUID strings to access an asset with an AssetReference. If you don't load assets in the group using AssetReferences or GUID strings, you can decrease the size of the catalog by not including them. |
| Include Labels in Catalog | Whether to include label strings in the catalog. If you don't load assets in the group using labels, you can decrease the size of the catalog by not including them. |
| Internal Asset Naming Mode | Determines the identification of assets in AssetBundles and is used to load the asset from the bundle. This value is used as the internalId of the asset Location. Changing this setting affects a bundles CRC and Hash value. Warning: Do not modify this setting for Content update builds. The data stored in the content state file will become invalid. The different modes are: - Full Path: the path of the asset in your project. This mode is recommended to use during development because it allows you to identify Assets being loaded by their ID if needed. - Filename: the asset's filename. This can also be used to identify an asset. Note: You cannot have multiple assets with the same name. - GUID: a deterministic value for the asset. - Dynamic: the shortest id that can be constructed based on the assets in the group. This mode is recommended to use for release because it can reduce the amount of data in the AssetBundle and catalog, and lower runtime memory overhead. |
| Internal Bundle Id Mode | Determines how an AssetBundle is identified internally. This affects how an AssetBundle locates dependencies that are contained in other bundles. Changing this value affects the CRC and Hash of this bundle and all other bundles that reference it. Warning: Do not modify this setting for Content update builds. The data stored in the content state file will become invalid. The different modes are: - Group Guid: unique identifier for the Group. This mode is recommended to use as it does not change. - Group Guid Project Id Hash: uses a combination of the Group GUID and the Cloud Project Id (if Cloud Services are enabled). This changes if the Project is bound to a different Cloud Project Id. This mode is recommended when sharing assets between multiple projects because the id constructed is deterministic and unique between projects. - Group Guid Project Id Entries Hash: uses a combination of the Group GUID, Cloud Project Id (if Cloud Services are enabled), and asset entries in the Group. Note that using this mode can easily cause bundle cache version issues. Adding or removing entries results in a different hash. |
| Cache Clear Behavior | Determines when an installed application clears AssetBundles from the cache. |
| Bundle Mode | How to pack the assets in this group into bundles: - Pack Together: create a single bundle containing all assets. - Pack Separately: create a bundle for each primary asset in the group. Subassets, such as Sprites in a Sprite sheet are packed together. Assets within a folder added to the group are also packed together. - Pack Together by Label: create a bundle for assets sharing the same combination of labels. |
| Bundle Naming Mode | How to construct the file names of AssetBundles: - Filename: the filename is a string derived from the group name. No hash is appended to it. - Append Hash to Filename: the filename is a string derived from the group name with bundle hash appended to it. The bundle hash is calculated using the contents of the bundle. - Use Hash of AssetBundle: the filename is the bundle hash. - Use Hash of Filename: the filename is a hash calculated from the a string derived from the group name. |
| Asset Load Mode | Whether to load assets individually as you request them (the default) or always load all assets in the group together. It is recommended to use Requested Asset and Dependencies for most cases. See Asset Load Mode for more information. |
| Asset Provider | Defines which Provider class Addressables uses to load assets from the AssetBundles generated from this group. Set this option to Assets from Bundles Provider unless you have a custom Provider implementation to provide assets from an AssetBundle. |
| Asset Bundle Provider | Defines which Provider class Addressables uses to load AssetBundles generated from this group. Set this option to AssetBundle Provider unless you have a custom Provider implementation to provide AssetBundles. |
AssetBundle Compression
Addressables provides three different options for bundle compression: Uncompressed, LZ4, and LZMA. Generally speaking, LZ4 should be used for local content, and LZMA for remote, but more details are outlined below as there can be exceptions to this.
You can set the compression option using the Advanced settings on each group. Compression does not affect in-memory size of your loaded content.
- Uncompressed - This option is largest on disk, and generally fastest to load. If your game happens to have space to spare, this option should at least be considered for local content. A key advantage of uncompressed bundles is how they handle being patched. If you are developing for a platform where the platform itself provides patching (such as Steam or Switch), uncompressed bundles provide the most accurate (smallest) patching. Either of the other compression options will cause at least some bloat of patches.
- LZ4 - If Uncompressed is not a viable option, then LZ4 should be used for all other local content. This is a chunk-based compression which provides the ability to load parts of the file without needing to load it in its entirety.
- LZMA - LZMA should be used for all remote content, but not for any local content. It provides the smallest bundle size, but is slow to load. If you were to store local bundles in LZMA you could create a smaller player, but load times would be significantly worse than uncompressed or LZ4. For downloaded bundles, we avoid the slow load time by recompressing the downloaded bundle when storing it in the AssetBundle cache. By default, bundles will be stored in the cache with LZ4 compression.
Note
LZMA AssetBundle compression is not available for AssetBundles on WebGL. LZ4 compression can be used instead. For more WebGL AssetBundle information, see Building and running a WebGL project.
Note that the hardware characteristics of a platform can mean that uncompressed bundles are not always the fastest to load. The maximum speed of loading uncompressed bundles is gated by IO speed, while the speed of loading LZ4-compressed bundles can be gated by either IO speed or CPU, depending on hardware. On most platforms, loading LZ4-compressed bundles is CPU bound, and loading uncompressed bundles will be faster. On platforms that have low IO speeds and high CPU speeds, LZ4 loading can be faster. It is always a good practice to run performance analysis to validate whether your game fits the common patterns, or needs some unique tweaking.
More information on Unity's compression selection is available in the AssetBundle compression manual page.
Asset Load Mode
For most platforms and collection of content, it is recommended to use Requested Asset and Dependencies. This mode will only load what is required for the Assets requested with LoadAssetAsync or LoadAssetsAsync. Objects are loaded based in the order that they appear in a bundle file, which can result in reading the same file multiple times. Enabling the Contiguous Bundles option in Addressables Build settings can help reduce the number of extra file reads.
This prevents situations where Assets are loaded into memory that are not used.
Performance in situations where you will load all Assets that are packed together, such as a loading screen. Most types of content will have either have similar or improved performance when loading each individually using Requested Asset and Dependencies mode. This mode sequentially reads entire bundle files, which may be more preferrable in some platforms like the Switch.
Note
The examples below apply to Desktop and Mobile platforms. Performance may differ between platforms. The All Packed Assets and Dependencies mode typically performs better than loading assets individually on the Nintendo Switch due its hardware and memory reading limitations. It is recommended to profile loading performance for your specific content and platform to see what works for your Application.
Loading performance can vary between content type. As an example, large counts of serialized data such as Prefabs or ScriptableObjects with direct references to other serialized data will load faster using All Packed Assets and Dependencies. With some other Assets like Textures, you can often achieve better performance when you load each Asset individually.
If using Synchronous Addressables, there is little performance between between Asset load modes. Because of greater flexibility it is recommended to use Requested Asset and Dependencies where you know the content will be loaded synchronously.
On loading the first Asset with All Packed Assets and Dependencies, all Assets are loaded into memory. Later LoadAssetAsync calls for Assets from that pack will return the preloaded Asset without needing to load it.
Even though all the Assets in a group and any dependencies are loaded in memory when you use the All Packed Assets and Dependencies option, the reference count of an individual asset is not incremented unless you explicitly load it (or it is a dependency of an asset that you load explicitly). If you later call Resources.UnloadUnusedAssets, or you load a new Scene using LoadSceneMode.Single, then any unused assets (those with a reference count of zero) are unloaded.
Content Update Restriction
The Content Update Restriction options determine how the [Check for Content Update Restrictions] tool treats assets in the group. Run this tool to prepare your groups for a differential content update build (rather than a full content build). The tool moves modified assets in any groups set to Cannot Change Post Release to a new group.
The Update Restriction options include:
- Can Change Post Release: No assets are moved by the tool. If any assets in the bundle have changed, then the entire bundle is rebuilt.
- Cannot Change Post Release: If any assets in the bundle have changed, then the [Check for Content Update Restrictions] tool moves them to a new group created for the update. When you make the update build, the assets in the AssetBundles created from this new group override the versions found in the existing bundles.
See Content update builds for more information.
Group templates
A Group template defines which types of schema objects are created 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 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:
- Navigate to the desired location in your Assets folder using the Project panel.
- Create a Blank Group Template (menu: Assets > Addressables > Group Templates > Blank Group Templates).
- Assign a suitable name to the template.
- In the Inspector window, add a description, if desired.
- Click the Add Schema button and choose from the list of schemas.
- Continue adding schemas until all required schemas are added to the list.
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. See Builds for more information.
Schemas
A group schema is a ScriptableObject that defines a collection of settings for an Addressables group. You can assign any number of schemas to a group. The Addressables system defines a number of schemas for its own purposes. You can also create custom schemas to support your own build scripts and utilities.
The built-in schemas include:
- Content Packing & Loading: this is the main Addressables schema used by the default build script and defines the settings for building and loading Addressable assets.
- Content Update Restrictions: defines settings for making differential updates of a previous build. See Builds for more information about update builds.
- Resources and Built In Scenes: a special-purpose schema defining settings for which types of built-in assets to display in the Built In Data group.
Defining custom schemas
To create your own schema, extend the AddressableAssetGroupSchema class (which is a kind of ScriptableObject).
using UnityEditor.AddressableAssets.Settings;
public class __CustomSchema __: AddressableAssetGroupSchema
{
public string CustomDescription;
}
Once you have defined your custom schema object, you can add it to existing groups and group templates using the Add Schema buttons found on the Inspector windows of those entities.
You might also want to create a custom Editor script to help users interact with your custom settings. See Custom Inspector scripts.
In a build script, you can access the schema settings for a group using its AddressableAssetGroup object.