Class ScyllaAddressables

Provides a unified, opinionated API for Unity's Addressables system, covering the full lifecycle of addressable assets: loading, instantiation, scene management, dependency downloading, catalog updates, memory release, and RAII-style managed wrappers.

Inheritance
object
ScyllaAddressables
Inherited Members
Namespace: Scylla.Core.Util.Addressables
Assembly: ScyllaCore.dll
Syntax
public static class ScyllaAddressables
Remarks

This class requires the Unity Addressables package (com.unity.addressables, version 2.7.6 or later) to be installed. Enable it by adding the SCYLLA_HAS_ADDRESSABLES scripting define symbol to your project settings. Without this define, every method has a stub implementation that either throws AddressableException with NotInitialized or returns a failed AddressableResult<T>, allowing code that handles results gracefully to compile and run even without the package.

API Patterns. Each operation is available in up to four complementary forms:

  • Handle pattern (LoadAsync, InstantiateAsync, etc.) - returns a raw AsyncOperationHandle. The caller is responsible for releasing the handle via Release<T>(AsyncOperationHandle<T>) when done. Use this when you need frame-by-frame progress polling.
  • Awaitable pattern (LoadAsyncAwaitable, InstantiateAsyncAwaitable, etc.) - suspends execution until the operation completes. Throws AddressableException on failure. Handles are released automatically on cancellation but must be released by the caller after a successful load via Release<T>(T).
  • Result pattern (LoadWithResultAsync, InstantiateWithResultAsync, etc.) - like the Awaitable pattern but wraps both success and failure into an AddressableResult<T> instead of throwing. Suitable for callers that prefer explicit error checking over exception handling.
  • Callback pattern (LoadWithCallback, InstantiateWithCallback, etc.) - fires Action delegates on completion. Compatible with WebGL where async/await on the main thread is restricted.

RAII / Managed wrappers. Use LoadManagedAsync<T>(string, CancellationToken) and LoadAllManagedAsync<T>(string, CancellationToken) to obtain ManagedAddressable<T> or ManagedAddressableList<T> instances, which automatically release their underlying handles when disposed. Pair them with using statements for deterministic resource cleanup.

Cancellation. All Awaitable and Result overloads accept an optional CancellationToken. When cancellation is requested, in-flight handles are released before the exception propagates, preventing memory leaks.

Default settings. The static DefaultSettings property allows global configuration of timeout and retry behaviour. Individual call sites may override this by constructing and passing a custom AddressableSettings instance.

Properties

DefaultSettings

Gets or sets the fallback AddressableSettings applied when an operation is invoked without explicitly providing settings.

Declaration
public static AddressableSettings DefaultSettings { get; set; }
Property Value
Type Description
AddressableSettings

An AddressableSettings instance that governs timeout, retry count, retry delay, warning verbosity, and per-batch failure cleanup behaviour. Defaults to Default, which uses a 30-second timeout and no retries.
Remarks

Replace this value at application startup to establish project-wide Addressables behaviour. Methods that accept an explicit settings parameter use ResolveSettings(AddressableSettings) internally, which falls back to this property when null is passed.

Methods

CheckForCatalogUpdatesAsync(CancellationToken)

Checks the remote content delivery network for available updates to loaded catalogs and returns the catalog IDs that have newer versions available, suspending execution using Unity's Awaitable pattern.

Declaration
public static Awaitable<List<string>> CheckForCatalogUpdatesAsync(CancellationToken cancellationToken = default)
Parameters
Type Name Description
CancellationToken cancellationToken

An optional token that can cancel the in-flight check. The handle is always released in a finally block regardless of outcome.
Returns
Type Description
Awaitable<List<string>>

A list of catalog ID strings identifying which catalogs have updates available. An empty list means all catalogs are current. Pass these IDs to UpdateCatalogsAsyncAwaitable(CancellationToken) to selectively update stale catalogs.
Exceptions
Type Condition
AddressableException

Thrown with CatalogUpdateFailed when the check fails; or with OperationCancelled on cancellation.

DownloadDependenciesAsync(IList<string>)

Pre-downloads and caches the remote asset bundle dependencies for assets identified by multiple keys using a Union merge strategy, without loading the assets into memory, and returns a raw AsyncOperationHandle that the caller manages.

Declaration
public static AsyncOperationHandle DownloadDependenciesAsync(IList<string> keys)
Parameters
Type Name Description
IList<string> keys

A list of Addressables keys (addresses or labels) whose bundle dependencies should be pre-downloaded. Must not be null.
Returns
Type Description
AsyncOperationHandle

A non-generic AsyncOperationHandle for the download. Must be released after completion.
Exceptions
Type Condition
AddressableException

Thrown synchronously with NullAddress when keys is null.

DownloadDependenciesAsync(string)

Pre-downloads and caches the remote asset bundle dependencies for the asset identified by the specified key, without loading the asset into memory, and returns a raw AsyncOperationHandle that the caller manages.

Declaration
public static AsyncOperationHandle DownloadDependenciesAsync(string key)
Parameters
Type Name Description
string key

The Addressables key (address or label) whose bundle dependencies should be pre-downloaded. Must not be null or empty.
Returns
Type Description
AsyncOperationHandle

A non-generic AsyncOperationHandle for the download. Must be released after completion via Release(AsyncOperationHandle).
Remarks

Calling this before loading an asset ensures that subsequent load operations do not stall waiting for network downloads, improving perceived load times. For progress reporting or async/await support, use DownloadDependenciesAsyncAwaitable(string, IProgress<AddressableProgress>, CancellationToken) or DownloadDependenciesWithResultAsync(string, IProgress<AddressableProgress>, CancellationToken).

Exceptions
Type Condition
AddressableException

Thrown synchronously with NullAddress when key is null or empty.

DownloadDependenciesAsyncAwaitable(string, IProgress<AddressableProgress>, CancellationToken)

Pre-downloads the remote asset bundle dependencies for the asset identified by the specified key, suspending execution using Unity's Awaitable pattern and reporting per-frame progress through an optional IProgress callback.

Declaration
public static Awaitable DownloadDependenciesAsyncAwaitable(string key, IProgress<AddressableProgress> progress = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string key

The Addressables key (address or label) whose bundle dependencies should be pre-downloaded. Must not be null or empty.
IProgress<AddressableProgress> progress

An optional AddressableProgress reporter that receives per-frame updates containing bytes downloaded, total bytes, and the current percentage. Pass null if progress tracking is not needed.
CancellationToken cancellationToken

An optional token that can cancel the in-flight download. The underlying handle is always released in a finally block regardless of outcome.
Returns
Type Description
Awaitable
Remarks

Progress is reported once per frame while the operation is in-flight. The BytesDownloaded field reflects the Addressables DownloadStatus.DownloadedBytes value; TotalBytes is null when the total size is unknown (e.g. streaming catalog).

Exceptions
Type Condition
AddressableException

Thrown with NullAddress when key is null or empty; with DownloadFailed when the download fails; or with OperationCancelled on cancellation.

DownloadDependenciesWithResultAsync(string, IProgress<AddressableProgress>, CancellationToken)

Pre-downloads the remote asset bundle dependencies for the asset identified by the specified key and returns an AddressableResult indicating success or structured error information, never throwing an exception.

Declaration
public static Awaitable<AddressableResult> DownloadDependenciesWithResultAsync(string key, IProgress<AddressableProgress> progress = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string key

The Addressables key (address or label) whose bundle dependencies should be pre-downloaded. If null or empty, returns immediately with a failure result containing NullAddress.
IProgress<AddressableProgress> progress

An optional AddressableProgress reporter that receives per-frame download progress updates. Pass null to disable progress tracking.
CancellationToken cancellationToken

An optional token that can cancel the in-flight download.
Returns
Type Description
Awaitable<AddressableResult>

An Awaitable that resolves to an AddressableResult with IsSuccess set to true on success, or containing the relevant AddressableErrorCode on failure. The underlying handle is always released in a finally block.

ExistsAsync(string, CancellationToken)

Checks whether the specified address resolves to at least one resource location in the Addressables catalog, returning true if found or false for any reason including null/empty input, missing entries, or query failure.

Declaration
public static Awaitable<bool> ExistsAsync(string address, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string address

The Addressables key string to look up. Returns false immediately if null or empty.
CancellationToken cancellationToken

An optional token that can cancel the in-flight location query. The handle is always released in a finally block regardless of outcome.
Returns
Type Description
Awaitable<bool>

true if the address maps to at least one resource location in the loaded catalog; false if the address is null/empty, the location lookup operation fails, or the result list is empty.
Remarks

This method performs a lightweight catalog lookup (no asset loading). Use the typed overload ExistsAsync<T>(string, CancellationToken) to additionally constrain the result to a specific asset type.

ExistsAsync<T>(string, CancellationToken)

Checks whether the specified address resolves to at least one resource location of the given type in the Addressables catalog.

Declaration
public static Awaitable<bool> ExistsAsync<T>(string address, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string address

The Addressables key string to look up. Returns false immediately if null or empty.
CancellationToken cancellationToken

An optional token that can cancel the in-flight location query. The handle is always released in a finally block regardless of outcome.
Returns
Type Description
Awaitable<bool>

true if the address maps to at least one resource location of type T in the loaded catalog; false otherwise.
Type Parameters
Name Description
T

The asset type to filter for (e.g. Texture2D, AudioClip). Only locations that match both the address and this type are counted.
Remarks

Use this overload when you need to confirm both the address and the expected asset type before attempting to load. The untyped ExistsAsync(string, CancellationToken) overload succeeds as long as any asset is registered at the address, regardless of type.

GetDownloadSizeAsync(IList<string>)

Queries the total remote download size in bytes for the assets identified by multiple keys, returning a raw AsyncOperationHandle that the caller manages.

Declaration
public static AsyncOperationHandle<long> GetDownloadSizeAsync(IList<string> keys)
Parameters
Type Name Description
IList<string> keys

A list of Addressables keys (addresses or labels). Must not be null. The operation returns the combined size for all matched assets.
Returns
Type Description
AsyncOperationHandle<long>

An AsyncOperationHandle<long> whose result is the total download size in bytes across all matched assets. A result of 0 indicates all assets are already cached. Must be released when done.
Exceptions
Type Condition
AddressableException

Thrown synchronously with NullAddress when keys is null.

GetDownloadSizeAsync(string)

Queries the total remote download size in bytes for the asset or group of assets identified by the specified key, returning a raw AsyncOperationHandle that the caller manages.

Declaration
public static AsyncOperationHandle<long> GetDownloadSizeAsync(string key)
Parameters
Type Name Description
string key

The Addressables key (address or label) identifying the asset or asset group to query. Must not be null or empty.
Returns
Type Description
AsyncOperationHandle<long>

An AsyncOperationHandle<long> whose result is the total download size in bytes. A result of 0 indicates the assets are already cached locally and no download is needed. Must be released when done.
Remarks

Call this before DownloadDependenciesAsync(string) to determine whether a download prompt or progress indicator is warranted.

Exceptions
Type Condition
AddressableException

Thrown synchronously with NullAddress when key is null or empty.

GetDownloadSizeAsyncAwaitable(string, CancellationToken)

Queries the total remote download size in bytes for the asset or group identified by a key, suspending execution using Unity's Awaitable pattern.

Declaration
public static Awaitable<long> GetDownloadSizeAsyncAwaitable(string key, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string key

The Addressables key (address or label) identifying the asset or group to query. Must not be null or empty.
CancellationToken cancellationToken

An optional token that can cancel the in-flight query. When cancellation is requested, the handle is released in the finally block before the exception propagates.
Returns
Type Description
Awaitable<long>

The total download size in bytes. A value of 0 means the asset is already cached locally and no download will occur when loading.
Remarks

The underlying handle is always released in a finally block regardless of outcome, so callers do not need to perform manual cleanup.

Exceptions
Type Condition
AddressableException

Thrown with NullAddress when key is null or empty; with DownloadFailed when the query fails; or with OperationCancelled on cancellation.

GetResourceLocationsAsync(IList<string>)

Looks up all IResourceLocation entries registered under any of the specified keys in the Addressables catalog using a Union merge strategy, and returns a raw AsyncOperationHandle that the caller manages.

Declaration
public static AsyncOperationHandle<IList<IResourceLocation>> GetResourceLocationsAsync(IList<string> keys)
Parameters
Type Name Description
IList<string> keys

A list of Addressables keys (addresses or labels) to query. Must not be null.
Returns
Type Description
AsyncOperationHandle<IList<IResourceLocation>>

An AsyncOperationHandle<IList<IResourceLocation>> whose result contains all resource locations matching any of the keys. Must be released after use.
Exceptions
Type Condition
AddressableException

Thrown synchronously with NullAddress when keys is null.

GetResourceLocationsAsync(string)

Looks up all IResourceLocation entries registered under the specified key in the Addressables catalog and returns a raw AsyncOperationHandle that the caller manages.

Declaration
public static AsyncOperationHandle<IList<IResourceLocation>> GetResourceLocationsAsync(string key)
Parameters
Type Name Description
string key

The Addressables key (address or label) to query. Must not be null or empty.
Returns
Type Description
AsyncOperationHandle<IList<IResourceLocation>>

An AsyncOperationHandle<IList<IResourceLocation>> whose result contains all matching resource locations. Must be released after use.
Remarks

Resource locations describe how and where Addressables can load an asset (bundle path, provider, dependencies). Use this for advanced scenarios such as inspecting bundle sizes or provider types. For simple existence checks, prefer ExistsAsync(string, CancellationToken).

Exceptions
Type Condition
AddressableException

Thrown synchronously with NullAddress when key is null or empty.

GetResourceLocationsAsyncAwaitable(string, CancellationToken)

Looks up all IResourceLocation entries registered under the specified key and suspends execution using Unity's Awaitable pattern, returning the result list directly.

Declaration
public static Awaitable<IList<IResourceLocation>> GetResourceLocationsAsyncAwaitable(string key, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string key

The Addressables key (address or label) to query. Must not be null or empty.
CancellationToken cancellationToken

An optional token that can cancel the in-flight query. The handle is always released in a finally block regardless of outcome.
Returns
Type Description
Awaitable<IList<IResourceLocation>>

The list of IResourceLocation objects matching the key. May be empty if no locations are registered under the key.
Exceptions
Type Condition
AddressableException

Thrown with NullAddress when key is null or empty; with AssetNotFound when the lookup operation fails; or with OperationCancelled on cancellation.

GetResourceLocationsAsyncAwaitable<T>(string, CancellationToken)

Looks up all IResourceLocation entries registered under the specified key and filtered to the given asset type, suspending execution using Unity's Awaitable pattern.

Declaration
public static Awaitable<IList<IResourceLocation>> GetResourceLocationsAsyncAwaitable<T>(string key, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string key

The Addressables key (address or label) to query. Must not be null or empty.
CancellationToken cancellationToken

An optional token that can cancel the in-flight query. The handle is always released in a finally block regardless of outcome.
Returns
Type Description
Awaitable<IList<IResourceLocation>>

The list of IResourceLocation objects matching the key and type.
Type Parameters
Name Description
T

The asset type to filter for. Only locations that provide this type are returned.
Exceptions
Type Condition
AddressableException

Thrown with NullAddress when key is null or empty; with AssetNotFound when the lookup fails; or with OperationCancelled on cancellation.

GetResourceLocationsAsync<T>(string)

Looks up all IResourceLocation entries registered under the specified key and filtered to the given asset type, returning a raw AsyncOperationHandle that the caller manages.

Declaration
public static AsyncOperationHandle<IList<IResourceLocation>> GetResourceLocationsAsync<T>(string key)
Parameters
Type Name Description
string key

The Addressables key (address or label) to query. Must not be null or empty.
Returns
Type Description
AsyncOperationHandle<IList<IResourceLocation>>

An AsyncOperationHandle<IList<IResourceLocation>> whose result contains all resource locations matching the key and type. Must be released after use.
Type Parameters
Name Description
T

The asset type to filter for. Only locations that provide this type are included in the result.
Exceptions
Type Condition
AddressableException

Thrown synchronously with NullAddress when key is null or empty.

InitializeAsync()

Explicitly initializes the Addressables system and loads the default catalog, returning a raw AsyncOperationHandle whose result is the root IResourceLocator.

Declaration
public static AsyncOperationHandle<IResourceLocator> InitializeAsync()
Returns
Type Description
AsyncOperationHandle<IResourceLocator>

An AsyncOperationHandle<IResourceLocator> whose result is the primary resource locator used to resolve all subsequent Addressables queries. Must be released after use.
Remarks

Unity initializes Addressables automatically on the first load operation. Call this explicitly only when you need to warm up the Addressables system (e.g. during a splash screen) before any asset loads occur. Repeated calls are safe; Addressables caches the initialized state. For async/await usage, prefer InitializeAsyncAwaitable(CancellationToken).

InitializeAsyncAwaitable(CancellationToken)

Explicitly initializes the Addressables system and suspends execution using Unity's Awaitable pattern, returning the root IResourceLocator upon completion.

Declaration
public static Awaitable<IResourceLocator> InitializeAsyncAwaitable(CancellationToken cancellationToken = default)
Parameters
Type Name Description
CancellationToken cancellationToken

An optional token that can cancel the in-flight initialization.
Returns
Type Description
Awaitable<IResourceLocator>

The primary IResourceLocator that maps keys to resource locations. This locator is used internally by all subsequent Addressables operations.
Exceptions
Type Condition
AddressableException

Thrown with NotInitialized when Unity fails to initialize the Addressables system; or with OperationCancelled on cancellation.

InstantiateAsync(string)

Starts the asynchronous instantiation of an addressable prefab at the world origin and returns a raw AsyncOperationHandle that the caller manages.

Declaration
public static AsyncOperationHandle<GameObject> InstantiateAsync(string address)
Parameters
Type Name Description
string address

The Addressables key string identifying the prefab asset. Must not be null or empty.
Returns
Type Description
AsyncOperationHandle<GameObject>

An AsyncOperationHandle<GameObject> whose result is the instantiated GameObject once complete. Use ReleaseInstance(GameObject) to destroy the instance and release its Addressables reference simultaneously. Do not use Object.Destroy alone, as it will not release the underlying Addressables reference count.
Remarks

The instantiated GameObject is placed at the world origin with identity rotation and no parent. Use the overloads that accept a parent or position/rotation for custom placement.

Exceptions
Type Condition
AddressableException

Thrown synchronously with NullAddress when address is null or empty.

InstantiateAsync(string, Transform)

Starts the asynchronous instantiation of an addressable prefab as a child of the specified parent transform and returns a raw AsyncOperationHandle that the caller manages.

Declaration
public static AsyncOperationHandle<GameObject> InstantiateAsync(string address, Transform parent)
Parameters
Type Name Description
string address

The Addressables key string identifying the prefab asset. Must not be null or empty.
Transform parent

The Transform that will become the parent of the instantiated object. May be null to place the object at the scene root.
Returns
Type Description
AsyncOperationHandle<GameObject>

An AsyncOperationHandle<GameObject> whose result is the instantiated GameObject. Use ReleaseInstance(GameObject) to destroy the instance and release the underlying Addressables reference.
Exceptions
Type Condition
AddressableException

Thrown synchronously with NullAddress when address is null or empty.

InstantiateAsync(string, Vector3, Quaternion)

Starts the asynchronous instantiation of an addressable prefab at the specified world position and rotation, without a parent, and returns a raw AsyncOperationHandle that the caller manages.

Declaration
public static AsyncOperationHandle<GameObject> InstantiateAsync(string address, Vector3 position, Quaternion rotation)
Parameters
Type Name Description
string address

The Addressables key string identifying the prefab asset. Must not be null or empty.
Vector3 position

The world-space position at which to place the instantiated object.
Quaternion rotation

The world-space rotation to apply to the instantiated object.
Returns
Type Description
AsyncOperationHandle<GameObject>

An AsyncOperationHandle<GameObject> whose result is the instantiated GameObject. Use ReleaseInstance(GameObject) to destroy the instance and release the underlying Addressables reference.
Exceptions
Type Condition
AddressableException

Thrown synchronously with NullAddress when address is null or empty.

InstantiateAsync(string, Vector3, Quaternion, Transform)

Starts the asynchronous instantiation of an addressable prefab at a specified world position, rotation, and parent transform, and returns a raw AsyncOperationHandle that the caller manages.

Declaration
public static AsyncOperationHandle<GameObject> InstantiateAsync(string address, Vector3 position, Quaternion rotation, Transform parent)
Parameters
Type Name Description
string address

The Addressables key string identifying the prefab asset. Must not be null or empty.
Vector3 position

The world-space position at which to place the instantiated object.
Quaternion rotation

The world-space rotation to apply to the instantiated object.
Transform parent

The Transform that will become the parent of the instantiated object. May be null to place the object at the scene root.
Returns
Type Description
AsyncOperationHandle<GameObject>

An AsyncOperationHandle<GameObject> whose result is the instantiated GameObject. Use ReleaseInstance(GameObject) to destroy the instance and release the underlying Addressables reference.
Exceptions
Type Condition
AddressableException

Thrown synchronously with NullAddress when address is null or empty.

InstantiateAsyncAwaitable(string, CancellationToken)

Instantiates an addressable prefab at the world origin and suspends execution using Unity's Awaitable pattern, returning the instantiated GameObject upon completion.

Declaration
public static Awaitable<GameObject> InstantiateAsyncAwaitable(string address, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string address

The Addressables key string identifying the prefab asset. Must not be null or empty.
CancellationToken cancellationToken

An optional token that can cancel the in-flight operation. When cancellation fires before the instantiation completes, any partially-created instance is released and the exception propagates.
Returns
Type Description
Awaitable<GameObject>

The instantiated GameObject. Use ReleaseInstance(GameObject) to destroy the object and release the underlying Addressables reference when done.
Exceptions
Type Condition
AddressableException

Thrown with NullAddress when address is null or empty; with InstantiateFailed when Unity fails to create the instance; or with OperationCancelled on cancellation.

InstantiateAsyncAwaitable(string, Transform, CancellationToken)

Instantiates an addressable prefab as a child of the specified parent transform and suspends execution using Unity's Awaitable pattern, returning the instantiated GameObject.

Declaration
public static Awaitable<GameObject> InstantiateAsyncAwaitable(string address, Transform parent, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string address

The Addressables key string identifying the prefab asset. Must not be null or empty.
Transform parent

The Transform that will become the parent of the instantiated object. May be null.
CancellationToken cancellationToken

An optional token that can cancel the in-flight operation.
Returns
Type Description
Awaitable<GameObject>

The instantiated GameObject. Use ReleaseInstance(GameObject) when done.
Exceptions
Type Condition
AddressableException

Thrown with NullAddress when address is null or empty; with InstantiateFailed on Unity failure; or with OperationCancelled on cancellation.

InstantiateAsyncAwaitable(string, Vector3, Quaternion, Transform, CancellationToken)

Instantiates an addressable prefab at a specific world position and rotation with an optional parent transform, and suspends execution using Unity's Awaitable pattern.

Declaration
public static Awaitable<GameObject> InstantiateAsyncAwaitable(string address, Vector3 position, Quaternion rotation, Transform parent = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string address

The Addressables key string identifying the prefab asset. Must not be null or empty.
Vector3 position

The world-space position at which to place the instantiated object.
Quaternion rotation

The world-space rotation to apply to the instantiated object.
Transform parent

An optional parent Transform. Pass null to place the object at the scene root.
CancellationToken cancellationToken

An optional token that can cancel the in-flight operation. When cancellation fires before completion, any partially-created instance is released before the exception propagates.
Returns
Type Description
Awaitable<GameObject>

The instantiated GameObject. Use ReleaseInstance(GameObject) when done.
Exceptions
Type Condition
AddressableException

Thrown with NullAddress when address is null or empty; with InstantiateFailed on Unity failure; or with OperationCancelled on cancellation.

InstantiateAsync<T>(string, CancellationToken)

Instantiates an addressable prefab and returns a specific Component from the resulting GameObject, suspending execution using Unity's Awaitable pattern.

Declaration
public static Awaitable<T> InstantiateAsync<T>(string address, CancellationToken cancellationToken = default) where T : Component
Parameters
Type Name Description
string address

The Addressables key string identifying the prefab asset. Must not be null or empty.
CancellationToken cancellationToken

An optional token that can cancel the in-flight operation. When cancellation fires before the instantiation completes, the instance is released before the exception propagates.
Returns
Type Description
Awaitable<T>

The T component from the instantiated prefab root.
Type Parameters
Name Description
T

The Component type to retrieve from the instantiated GameObject. The prefab must have this component attached to its root or the operation will fail and the instance will be released automatically.
Remarks

The prefab root is checked for T via GetComponent. If the component lives on a child object, this overload will fail. Retrieve the GameObject directly using InstantiateAsyncAwaitable(string, CancellationToken) and search the hierarchy manually in that case.

Exceptions
Type Condition
AddressableException

Thrown with InstantiateFailed when Unity fails to create the instance; with InvalidType when the instantiated prefab does not have a component of type T (the instance is automatically released via ReleaseInstance(GameObject) in this case); or with OperationCancelled on cancellation.

InstantiateAsync<T>(string, Transform, CancellationToken)

Instantiates an addressable prefab under the specified parent transform and returns a specific Component from the resulting GameObject, suspending execution using Unity's Awaitable pattern.

Declaration
public static Awaitable<T> InstantiateAsync<T>(string address, Transform parent, CancellationToken cancellationToken = default) where T : Component
Parameters
Type Name Description
string address

The Addressables key string identifying the prefab asset. Must not be null or empty.
Transform parent

The Transform that will become the parent of the instantiated object. May be null.
CancellationToken cancellationToken

An optional token that can cancel the in-flight operation.
Returns
Type Description
Awaitable<T>

The T component from the instantiated prefab root.
Type Parameters
Name Description
T

The Component type to retrieve from the instantiated prefab root.
Exceptions
Type Condition
AddressableException

Thrown with InstantiateFailed when Unity fails to create the instance; with InvalidType when the component is not found on the prefab root (instance auto-released); or with OperationCancelled on cancellation.

InstantiateAsync<T>(string, Vector3, Quaternion, Transform, CancellationToken)

Instantiates an addressable prefab at a specific world position and rotation with an optional parent, and returns a specific Component from the resulting GameObject, suspending execution using Unity's Awaitable pattern.

Declaration
public static Awaitable<T> InstantiateAsync<T>(string address, Vector3 position, Quaternion rotation, Transform parent = null, CancellationToken cancellationToken = default) where T : Component
Parameters
Type Name Description
string address

The Addressables key string identifying the prefab asset. Must not be null or empty.
Vector3 position

The world-space position at which to place the instantiated object.
Quaternion rotation

The world-space rotation to apply to the instantiated object.
Transform parent

The optional Transform that will become the parent of the instantiated object. Pass null to place the object at the scene root.
CancellationToken cancellationToken

An optional token that can cancel the in-flight operation.
Returns
Type Description
Awaitable<T>

The T component from the instantiated prefab root.
Type Parameters
Name Description
T

The Component type to retrieve from the instantiated prefab root.
Exceptions
Type Condition
AddressableException

Thrown with InstantiateFailed when Unity fails to create the instance; with InvalidType when the component is not found on the prefab root (instance auto-released); or with OperationCancelled on cancellation.

InstantiateWithCallback(string, Action<GameObject>, Action<AddressableException>)

Starts the asynchronous instantiation of an addressable prefab at the world origin and notifies the caller through completion callbacks, making it compatible with WebGL.

Declaration
public static void InstantiateWithCallback(string address, Action<GameObject> onSuccess, Action<AddressableException> onError = null)
Parameters
Type Name Description
string address

The Addressables key string identifying the prefab. If null or empty, onError is invoked synchronously with NullAddress.
Action<GameObject> onSuccess

The callback invoked when instantiation succeeds, receiving the instantiated GameObject. Use ReleaseInstance(GameObject) to destroy and release the object when done.
Action<AddressableException> onError

An optional callback invoked when instantiation fails. If null, errors are silently discarded.
Remarks

This method returns immediately. Prefer InstantiateAsyncAwaitable(string, CancellationToken) on platforms that fully support async/await.

InstantiateWithCallback<T>(string, Action<T>, Action<AddressableException>)

Starts the asynchronous instantiation of an addressable prefab and, upon completion, retrieves a specific Component from the resulting GameObject, notifying the caller through completion callbacks. Compatible with WebGL.

Declaration
public static void InstantiateWithCallback<T>(string address, Action<T> onSuccess, Action<AddressableException> onError = null) where T : Component
Parameters
Type Name Description
string address

The Addressables key string identifying the prefab. If null or empty, onError is invoked synchronously with NullAddress.
Action<T> onSuccess

The callback invoked when instantiation and component retrieval succeed, receiving the T component.
Action<AddressableException> onError

An optional callback invoked when instantiation fails or the component is not found. If null, errors are silently discarded (and any instance is released on type mismatch).
Type Parameters
Name Description
T

The Component type to retrieve from the instantiated prefab root. If the component is not found, the instance is released via ReleaseInstance(GameObject) and onError is called with InvalidType.
Remarks

This method returns immediately. Prefer InstantiateAsync<T>(string, CancellationToken) on platforms that fully support async/await.

InstantiateWithResultAsync(string, CancellationToken)

Instantiates an addressable prefab at the world origin and returns an AddressableResult<T> encapsulating either the instantiated GameObject or structured error information, never throwing an exception.

Declaration
public static Awaitable<AddressableResult<GameObject>> InstantiateWithResultAsync(string address, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string address

The Addressables key string identifying the prefab asset. If null or empty, the method returns immediately with a failure result containing NullAddress.
CancellationToken cancellationToken

An optional token that can cancel the in-flight operation. On cancellation, any in-flight instance is released and the returned result contains OperationCancelled.
Returns
Type Description
Awaitable<AddressableResult<GameObject>>

An Awaitable that resolves to an AddressableResult<T> where T is GameObject. On success, use ReleaseInstance(GameObject) to destroy the instance and release the underlying Addressables reference when done.

LoadAllAsyncAwaitable<T>(IList<string>, CancellationToken)

Loads all assets identified by a list of Addressables keys using Unity's Awaitable pattern and a Union merge strategy, suspending execution until the entire batch completes.

Declaration
public static Awaitable<IList<T>> LoadAllAsyncAwaitable<T>(IList<string> keys, CancellationToken cancellationToken = default)
Parameters
Type Name Description
IList<string> keys

A list of Addressables key strings identifying the assets to load. Must not be null.
CancellationToken cancellationToken

An optional token that can cancel the in-flight batch operation. When cancellation is requested, the underlying handle is released before the exception propagates.
Returns
Type Description
Awaitable<IList<T>>

The full list of loaded assets. The caller is responsible for releasing them when done.
Type Parameters
Name Description
T

The common asset type shared by all assets under the provided keys.
Exceptions
Type Condition
AddressableException

Thrown with NullAddress when keys is null; with LoadFailed on operation failure; or with OperationCancelled on cancellation.

LoadAllAsyncAwaitable<T>(string, CancellationToken)

Loads all assets tagged with the specified Addressables label using Unity's Awaitable pattern, suspending execution until the entire batch completes.

Declaration
public static Awaitable<IList<T>> LoadAllAsyncAwaitable<T>(string label, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string label

The Addressables label that groups the target assets. Must not be null or empty.
CancellationToken cancellationToken

An optional token that can cancel the in-flight batch operation. When cancellation is requested, the underlying handle is released before the exception propagates.
Returns
Type Description
Awaitable<IList<T>>

The full list of loaded assets. The caller is responsible for releasing the assets via Release<T>(AsyncOperationHandle<T>) when done. For automatic release, prefer LoadAllManagedAsync<T>(string, CancellationToken).
Type Parameters
Name Description
T

The common asset type shared by all assets under the label.
Exceptions
Type Condition
AddressableException

Thrown with NullAddress when label is null or empty; with LoadFailed when the batch operation fails; or with OperationCancelled on cancellation.

LoadAllAsync<T>(IList<string>)

Starts an asynchronous batch load of assets identified by a list of Addressables keys, using a Union merge strategy to combine results, and returns a raw AsyncOperationHandle that the caller manages.

Declaration
public static AsyncOperationHandle<IList<T>> LoadAllAsync<T>(IList<string> keys)
Parameters
Type Name Description
IList<string> keys

A list of Addressables key strings. Each key may represent an address, label, or GUID. The union merge strategy means an asset matching any key in the list is included in the result. Must not be null.
Returns
Type Description
AsyncOperationHandle<IList<T>>

An AsyncOperationHandle<IList<T>> representing the batch load. Must be released when the assets are no longer needed.
Type Parameters
Name Description
T

The common asset type shared by all assets under the provided keys.
Exceptions
Type Condition
AddressableException

Thrown synchronously with NullAddress when keys is null.
See Also

LoadAllAsync<T>(IList<string>, MergeMode)

Starts an asynchronous batch load of assets identified by a list of Addressables keys, applying the specified merge mode to control which assets are included in the result.

Declaration
public static AsyncOperationHandle<IList<T>> LoadAllAsync<T>(IList<string> keys, Addressables.MergeMode mergeMode)
Parameters
Type Name Description
IList<string> keys

A list of Addressables key strings. Must not be null.
Addressables.MergeMode mergeMode

Determines how results from multiple keys are combined:

  • Union - includes all assets matching any key (logical OR).
  • Intersection - includes only assets matching all keys (logical AND).
  • UseFirst - returns results for the first key only.
Returns
Type Description
AsyncOperationHandle<IList<T>>

An AsyncOperationHandle<IList<T>> representing the batch load. Must be released when the assets are no longer needed.
Type Parameters
Name Description
T

The common asset type shared by all assets under the provided keys.
Exceptions
Type Condition
AddressableException

Thrown synchronously with NullAddress when keys is null.

LoadAllAsync<T>(string)

Starts an asynchronous batch load of all assets tagged with the specified Addressables label and returns a raw AsyncOperationHandle that the caller manages.

Declaration
public static AsyncOperationHandle<IList<T>> LoadAllAsync<T>(string label)
Parameters
Type Name Description
string label

The Addressables label that groups the target assets. Must not be null or empty. Labels are configured in the Addressables Groups window in the Unity Editor.
Returns
Type Description
AsyncOperationHandle<IList<T>>

An AsyncOperationHandle<IList<T>> whose result is the full collection of loaded assets once the operation completes. Must be released via Release<T>(AsyncOperationHandle<T>) when the assets are no longer needed.
Type Parameters
Name Description
T

The common asset type shared by all assets under the label (e.g. Sprite, AudioClip).
Remarks

For async/await usage, prefer LoadAllAsyncAwaitable<T>(string, CancellationToken). For RAII lifetime management, prefer LoadAllManagedAsync<T>(string, CancellationToken).

Exceptions
Type Condition
AddressableException

Thrown synchronously with NullAddress when label is null or empty.

LoadAllManagedAsync<T>(IList<string>, CancellationToken)

Loads all assets identified by a list of Addressables keys using a Union merge strategy and wraps them in a ManagedAddressableList<T> that automatically releases the underlying handle when disposed.

Declaration
public static Awaitable<ManagedAddressableList<T>> LoadAllManagedAsync<T>(IList<string> keys, CancellationToken cancellationToken = default)
Parameters
Type Name Description
IList<string> keys

A list of Addressables key strings identifying the assets to load. Must not be null.
CancellationToken cancellationToken

An optional token that can cancel the in-flight batch load.
Returns
Type Description
Awaitable<ManagedAddressableList<T>>

A ManagedAddressableList<T> wrapping all loaded assets. The caller must dispose this wrapper to release the underlying Addressables handle.
Type Parameters
Name Description
T

The common asset type shared by all assets under the provided keys.
Exceptions
Type Condition
AddressableException

Thrown with NullAddress when keys is null; with LoadFailed on batch failure; or with OperationCancelled on cancellation.
See Also

LoadAllManagedAsync<T>(string, CancellationToken)

Loads all assets tagged with the specified Addressables label and wraps them in a ManagedAddressableList<T> that automatically releases the underlying handle when disposed, providing RAII-style resource management for batch loads.

Declaration
public static Awaitable<ManagedAddressableList<T>> LoadAllManagedAsync<T>(string label, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string label

The Addressables label that groups the target assets. Must not be null or empty.
CancellationToken cancellationToken

An optional token that can cancel the in-flight batch load. When cancellation is requested, the handle is released before the exception propagates.
Returns
Type Description
Awaitable<ManagedAddressableList<T>>

A ManagedAddressableList<T> wrapping all loaded assets. The caller must dispose this wrapper (e.g. via a using statement) to release the underlying Addressables handle and all assets in the batch simultaneously.
Type Parameters
Name Description
T

The common asset type shared by all assets under the label.
Exceptions
Type Condition
AddressableException

Thrown with NullAddress when label is null or empty; with LoadFailed when the batch fails; or with OperationCancelled on cancellation.
See Also

LoadAllWithCallback<T>(string, Action<IList<T>>, Action<AddressableException>)

Starts an asynchronous batch load of all assets tagged with the specified label and notifies the caller through completion callbacks, making it compatible with WebGL.

Declaration
public static void LoadAllWithCallback<T>(string label, Action<IList<T>> onSuccess, Action<AddressableException> onError = null)
Parameters
Type Name Description
string label

The Addressables label that groups the target assets. If null or empty, onError is invoked synchronously with NullAddress.
Action<IList<T>> onSuccess

The callback invoked when the batch load succeeds, receiving the complete asset list. The caller is responsible for releasing the handle when done.
Action<AddressableException> onError

An optional callback invoked when the load fails. If null, errors are silently discarded.
Type Parameters
Name Description
T

The common asset type shared by all assets under the label.
Remarks

This method returns immediately. Prefer LoadAllAsyncAwaitable<T>(string, CancellationToken) on platforms that fully support async/await.

LoadAllWithResultAsync<T>(string, CancellationToken)

Loads all assets tagged with the specified Addressables label and returns an AddressableResult<T> encapsulating either the loaded list or structured error information, never throwing an exception.

Declaration
public static Awaitable<AddressableResult<IList<T>>> LoadAllWithResultAsync<T>(string label, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string label

The Addressables label that groups the target assets. If null or empty, the method returns immediately with a failure result containing NullAddress.
CancellationToken cancellationToken

An optional token that can cancel the in-flight batch operation. On cancellation, any in-flight handle is released and the returned result contains OperationCancelled.
Returns
Type Description
Awaitable<AddressableResult<IList<T>>>

An Awaitable that resolves to an AddressableResult<T> where T is IList<T>. Check IsSuccess before accessing Value. On success, the caller is responsible for releasing the loaded assets when done.
Type Parameters
Name Description
T

The common asset type shared by all assets under the label.

LoadAsyncAwaitable<T>(string, CancellationToken)

Loads an asset by address and suspends execution using Unity's Awaitable pattern, returning the loaded asset directly upon completion.

Declaration
public static Awaitable<T> LoadAsyncAwaitable<T>(string address, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string address

The Addressables key string identifying the asset in the catalog. Must not be null or empty.
CancellationToken cancellationToken

An optional token that can cancel the in-flight operation. When cancellation is requested, the underlying handle is released before the exception propagates, preventing memory leaks.
Returns
Type Description
Awaitable<T>

The loaded asset of type T. The caller is responsible for releasing the Addressables asset when done by calling Release<T>(T).
Type Parameters
Name Description
T

The type of asset to load.
Remarks

This is the recommended overload for async/await workflows. For error-code-based error handling without exceptions, use LoadWithResultAsync<T>(string, CancellationToken) instead. For automatic resource cleanup, use LoadManagedAsync<T>(string, CancellationToken).

Exceptions
Type Condition
AddressableException

Thrown with NullAddress when address is null or empty; with LoadFailed when Unity reports an operation failure; or with OperationCancelled when the cancellationToken fires.
See Also

LoadAsyncAwaitable<T>(AssetReference, CancellationToken)

Loads an asset from an AssetReference and suspends execution using Unity's Awaitable pattern, returning the loaded asset directly upon completion.

Declaration
public static Awaitable<T> LoadAsyncAwaitable<T>(AssetReference reference, CancellationToken cancellationToken = default)
Parameters
Type Name Description
AssetReference reference

The AssetReference identifying the asset. Must not be null.
CancellationToken cancellationToken

An optional token that can cancel the in-flight operation. When cancellation is requested, the underlying handle is released before the exception propagates.
Returns
Type Description
Awaitable<T>

The loaded asset of type T. The caller is responsible for releasing the asset when done by calling Release<T>(T).
Type Parameters
Name Description
T

The type of asset to load.
Exceptions
Type Condition
AddressableException

Thrown with NullAddress when reference is null; with LoadFailed when the operation fails; or with OperationCancelled when the cancellationToken fires.

LoadAsync<T>(string)

Starts an asynchronous load of a single asset identified by its Addressables address string and returns a raw AsyncOperationHandle that the caller manages.

Declaration
public static AsyncOperationHandle<T> LoadAsync<T>(string address)
Parameters
Type Name Description
string address

The Addressables key string that identifies the asset in the catalog. Must not be null or empty. Addresses are configured in the Addressables Groups window in the Unity Editor.
Returns
Type Description
AsyncOperationHandle<T>

An AsyncOperationHandle<T> representing the in-flight or completed load. Poll handle.IsDone and handle.Status to track progress. The handle is valid until explicitly released via Release<T>(AsyncOperationHandle<T>).
Type Parameters
Name Description
T

The type of asset to load (e.g. Texture2D, AudioClip, ScriptableObject). The Addressables runtime performs a type-safe cast; a mismatch will cause the operation to fail.
Remarks

This overload returns the raw handle and does not await completion. Prefer LoadAsyncAwaitable<T>(string, CancellationToken) for cleaner async/await code, or LoadWithResultAsync<T>(string, CancellationToken) when exception-free error handling is desired. Always release the handle after use to avoid Addressables memory leaks.

Exceptions
Type Condition
AddressableException

Thrown synchronously with NullAddress when address is null or empty, before the operation is started.
See Also

LoadAsync<T>(AssetReference)

Starts an asynchronous load of a single asset from an AssetReference and returns a raw AsyncOperationHandle that the caller manages.

Declaration
public static AsyncOperationHandle<T> LoadAsync<T>(AssetReference reference)
Parameters
Type Name Description
AssetReference reference

The AssetReference configured in the Inspector that identifies the target asset. Must not be null.
Returns
Type Description
AsyncOperationHandle<T>

An AsyncOperationHandle<T> representing the in-flight or completed load. The handle must be released via Release<T>(AsyncOperationHandle<T>) when no longer needed.
Type Parameters
Name Description
T

The type of asset to load. Must match or be compatible with the type assigned to reference in the Inspector.
Remarks

Prefer this overload when working with assets referenced via Unity's AssetReference Inspector field. For key-based loading, use LoadAsync<T>(string). For managed lifetime, use LoadManagedAsync<T>(AssetReference, CancellationToken).

Exceptions
Type Condition
AddressableException

Thrown synchronously with NullAddress when reference is null.

LoadManagedAsync<T>(string, CancellationToken)

Loads an addressable asset by address and wraps it in a ManagedAddressable<T> that automatically releases the underlying handle when disposed, providing RAII-style resource management compatible with using statements.

Declaration
public static Awaitable<ManagedAddressable<T>> LoadManagedAsync<T>(string address, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string address

The Addressables key string identifying the asset. Must not be null or empty.
CancellationToken cancellationToken

An optional token that can cancel the in-flight load. When cancellation is requested, the handle is released before the exception propagates.
Returns
Type Description
Awaitable<ManagedAddressable<T>>

A ManagedAddressable<T> wrapping the loaded asset. The caller must dispose this wrapper (e.g. via a using statement) to release the underlying Addressables handle.
Type Parameters
Name Description
T

The type of asset to load.
Remarks
using (var managed = await ScyllaAddressables.LoadManagedAsync<Texture2D>("ui/banner"))
{
    bannerImage.texture = managed.Asset;
    /* Asset is released automatically when the using block exits. */
}
Exceptions
Type Condition
AddressableException

Thrown with NullAddress when address is null or empty; with LoadFailed when the operation fails; or with OperationCancelled on cancellation.
See Also

LoadManagedAsync<T>(AssetReference, CancellationToken)

Loads an asset from an AssetReference and wraps it in a ManagedAddressable<T> that automatically releases the underlying handle when disposed, providing RAII-style resource management.

Declaration
public static Awaitable<ManagedAddressable<T>> LoadManagedAsync<T>(AssetReference reference, CancellationToken cancellationToken = default)
Parameters
Type Name Description
AssetReference reference

The AssetReference identifying the asset. Must not be null.
CancellationToken cancellationToken

An optional token that can cancel the in-flight load. When cancellation is requested, the handle is released before the exception propagates.
Returns
Type Description
Awaitable<ManagedAddressable<T>>

A ManagedAddressable<T> wrapping the loaded asset. The caller must dispose this wrapper to release the underlying Addressables handle.
Type Parameters
Name Description
T

The type of asset to load.
Exceptions
Type Condition
AddressableException

Thrown with NullAddress when reference is null; with LoadFailed when the operation fails; or with OperationCancelled on cancellation.
See Also

LoadSceneAsync(string, LoadSceneMode, bool)

Starts the asynchronous load of an Addressable scene and returns a raw AsyncOperationHandle that the caller manages.

Declaration
public static AsyncOperationHandle<SceneInstance> LoadSceneAsync(string address, LoadSceneMode loadMode = LoadSceneMode.Single, bool activateOnLoad = true)
Parameters
Type Name Description
string address

The Addressables key string identifying the scene asset in the catalog. Must not be null or empty.
LoadSceneMode loadMode

Controls how the scene is loaded relative to any currently active scenes. Single (the default) unloads all existing scenes; Additive loads the scene alongside existing scenes.
bool activateOnLoad

When true (default), the scene is activated immediately upon load. Set to false to defer activation and call SceneInstance.ActivateAsync() manually, which is useful for pre-loading without causing a visible frame hitch.
Returns
Type Description
AsyncOperationHandle<SceneInstance>

An AsyncOperationHandle<SceneInstance> whose result is the loaded SceneInstance. Pass this or its Result to UnloadSceneAsync(SceneInstance) when the scene is no longer needed.
Remarks

For async/await usage, prefer LoadSceneAsyncAwaitable(string, LoadSceneMode, CancellationToken). For explicit error handling without exceptions, prefer LoadSceneWithResultAsync(string, LoadSceneMode, CancellationToken).

Exceptions
Type Condition
AddressableException

Thrown synchronously with NullAddress when address is null or empty.

LoadSceneAsync(AssetReference, LoadSceneMode, bool)

Starts the asynchronous load of an Addressable scene using an AssetReference and returns a raw AsyncOperationHandle that the caller manages.

Declaration
public static AsyncOperationHandle<SceneInstance> LoadSceneAsync(AssetReference reference, LoadSceneMode loadMode = LoadSceneMode.Single, bool activateOnLoad = true)
Parameters
Type Name Description
AssetReference reference

The AssetReference identifying the scene asset configured in the Inspector. Must not be null.
LoadSceneMode loadMode

Controls how the scene is loaded relative to existing active scenes. Defaults to Single (unloads existing scenes).
bool activateOnLoad

When true (default), the scene is activated immediately upon load.
Returns
Type Description
AsyncOperationHandle<SceneInstance>

An AsyncOperationHandle<SceneInstance> whose result is the loaded SceneInstance. Pass this to UnloadSceneAsync(AsyncOperationHandle<SceneInstance>) when unloading.
Exceptions
Type Condition
AddressableException

Thrown synchronously with NullAddress when reference is null.

LoadSceneAsyncAwaitable(string, LoadSceneMode, CancellationToken)

Loads an Addressable scene and suspends execution using Unity's Awaitable pattern, returning the SceneInstance upon completion.

Declaration
public static Awaitable<SceneInstance> LoadSceneAsyncAwaitable(string address, LoadSceneMode loadMode = LoadSceneMode.Single, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string address

The Addressables key string identifying the scene asset. Must not be null or empty.
LoadSceneMode loadMode

Controls how the scene is loaded relative to existing active scenes. Defaults to Single (unloads existing scenes).
CancellationToken cancellationToken

An optional token that can cancel the in-flight operation. Note that scene operations in Unity cannot always be reliably cancelled mid-way; the exception will propagate but the scene may have been partially loaded.
Returns
Type Description
Awaitable<SceneInstance>

The SceneInstance representing the loaded scene. Pass it to UnloadSceneAsyncAwaitable(SceneInstance, CancellationToken) to unload and release the scene when done.
Exceptions
Type Condition
AddressableException

Thrown with NullAddress when address is null or empty; with SceneLoadFailed when Unity fails to load the scene; or with OperationCancelled on cancellation.

LoadSceneWithResultAsync(string, LoadSceneMode, CancellationToken)

Loads an Addressable scene and returns an AddressableResult<T> encapsulating either the loaded SceneInstance or structured error information, never throwing.

Declaration
public static Awaitable<AddressableResult<SceneInstance>> LoadSceneWithResultAsync(string address, LoadSceneMode loadMode = LoadSceneMode.Single, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string address

The Addressables key string identifying the scene asset. If null or empty, returns immediately with a failure result containing NullAddress.
LoadSceneMode loadMode

Controls how the scene is loaded. Defaults to Single (unloads existing scenes).
CancellationToken cancellationToken

An optional token that can cancel the in-flight operation.
Returns
Type Description
Awaitable<AddressableResult<SceneInstance>>

An Awaitable that resolves to an AddressableResult<T> where T is SceneInstance. On success, use UnloadSceneAsyncAwaitable(SceneInstance, CancellationToken) to unload.

LoadWithCallback<T>(string, Action<T>, Action<AddressableException>)

Starts an asynchronous asset load and notifies the caller through completion callbacks rather than async/await, making it compatible with WebGL where async on the main thread has restrictions.

Declaration
public static void LoadWithCallback<T>(string address, Action<T> onSuccess, Action<AddressableException> onError = null)
Parameters
Type Name Description
string address

The Addressables key string identifying the asset. If null or empty, onError is invoked synchronously with NullAddress.
Action<T> onSuccess

The callback invoked when the load succeeds, receiving the loaded asset of type T. The caller is responsible for releasing the asset when done. May be null, in which case the asset is loaded but immediately leaked.
Action<AddressableException> onError

An optional callback invoked when the load fails, receiving an AddressableException describing the failure. If null, errors are silently discarded.
Type Parameters
Name Description
T

The type of asset to load.
Remarks

This method returns immediately and never blocks. Callbacks are invoked on the same thread that completes the Addressables operation (typically the Unity main thread). Prefer LoadAsyncAwaitable<T>(string, CancellationToken) on platforms that fully support async/await.

LoadWithResultAsync<T>(string, CancellationToken)

Loads an asset by address and returns an AddressableResult<T> that encapsulates either the loaded asset or structured error information, never throwing an exception.

Declaration
public static Awaitable<AddressableResult<T>> LoadWithResultAsync<T>(string address, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string address

The Addressables key string identifying the asset. If null or empty, the method returns immediately with a failure result containing NullAddress, without starting an Addressables operation.
CancellationToken cancellationToken

An optional token that can cancel the in-flight operation. On cancellation, any in-flight handle is released and the returned result contains OperationCancelled.
Returns
Type Description
Awaitable<AddressableResult<T>>

An Awaitable that resolves to an AddressableResult<T>. Check IsSuccess before accessing Value. On success, the caller is responsible for releasing the loaded asset via Release<T>(T) when done.
Type Parameters
Name Description
T

The type of asset to load.
Remarks

This is the preferred overload when callers want structured error handling over exception-based flow. Use LoadAsyncAwaitable<T>(string, CancellationToken) when exception propagation is acceptable and simpler code is preferred.

See Also

Release(AsyncOperationHandle)

Releases a non-generic AsyncOperationHandle, decrementing the reference count of any loaded assets it references. Only releases when the handle is valid.

Declaration
public static void Release(AsyncOperationHandle handle)
Parameters
Type Name Description
AsyncOperationHandle handle

The non-generic handle to release. Handles returned by DownloadDependenciesAsync(string) use this overload. If the handle is already invalid (e.g. already released), this call is a no-op.

ReleaseAll(IEnumerable<AsyncOperationHandle>)

Releases all valid non-generic AsyncOperationHandle instances in the provided sequence, safely skipping any that are already invalid.

Declaration
public static void ReleaseAll(IEnumerable<AsyncOperationHandle> handles)
Parameters
Type Name Description
IEnumerable<AsyncOperationHandle> handles

An enumerable sequence of handles to release. May be null, in which case the method returns immediately without error.
Remarks

Use this to bulk-release a collection of handles gathered during a multi-step load workflow. Each handle is individually validated before release, so partially-completed collections are handled safely.

ReleaseAll<T>(IEnumerable<AsyncOperationHandle<T>>)

Releases all valid typed AsyncOperationHandle instances in the provided sequence, safely skipping any that are already invalid.

Declaration
public static void ReleaseAll<T>(IEnumerable<AsyncOperationHandle<T>> handles)
Parameters
Type Name Description
IEnumerable<AsyncOperationHandle<T>> handles

An enumerable sequence of typed handles to release. May be null, in which case the method returns immediately without error.
Type Parameters
Name Description
T

The result type of the handles.

ReleaseInstance(GameObject)

Destroys an Addressable-instantiated GameObject and releases its underlying Addressables reference, decrementing the reference count of the original prefab asset.

Declaration
public static bool ReleaseInstance(GameObject instance)
Parameters
Type Name Description
GameObject instance

The GameObject previously returned by an InstantiateAsync or InstantiateAsyncAwaitable call. Passing null returns false immediately without error.
Returns
Type Description
bool

true if the instance was recognized as an Addressable instance and was destroyed; false if instance is null or was not created through the Addressables system (in which case Object.Destroy should be used instead).
Remarks

Always use this method - not Object.Destroy - to destroy Addressable instances. Using Object.Destroy alone destroys the scene object but does not release the Addressables reference count, potentially preventing the bundle from being unloaded.

Release<T>(AsyncOperationHandle<T>)

Releases a typed AsyncOperationHandle, decrementing the reference count of any loaded assets it references. Only releases when the handle is valid.

Declaration
public static void Release<T>(AsyncOperationHandle<T> handle)
Parameters
Type Name Description
AsyncOperationHandle<T> handle

The typed handle to release. If the handle is already invalid (e.g. already released or not yet started), this call is a no-op.
Type Parameters
Name Description
T

The type of the handle result.

Release<T>(T)

Releases a loaded Addressable asset, decrementing its reference count and allowing the Addressables system to unload the underlying asset bundle when the count reaches zero.

Declaration
public static void Release<T>(T asset)
Parameters
Type Name Description
T asset

The asset reference previously returned by a successful load operation. Passing an invalid or already-released reference is handled internally by Addressables.
Type Parameters
Name Description
T

The type of the asset to release.
Remarks

Use this overload after assets loaded via LoadAsync<T>(string), LoadAsyncAwaitable<T>(string, CancellationToken), or similar methods. Do not call this on instantiated GameObject instances - use ReleaseInstance(GameObject) instead.

TryLoadAsync<T>(string, out AsyncOperationHandle<T>)

Attempts to start an asynchronous asset load without throwing exceptions, returning a boolean indicating whether the operation was successfully started.

Declaration
public static bool TryLoadAsync<T>(string address, out AsyncOperationHandle<T> handle)
Parameters
Type Name Description
string address

The Addressables key string identifying the asset. If null or empty the method immediately returns false without starting an operation.
AsyncOperationHandle<T> handle

When this method returns true, contains the started AsyncOperationHandle<T>. When this method returns false, contains default(AsyncOperationHandle<T>) which is an invalid, zero-initialized handle that must not be released.
Returns
Type Description
bool

true if the operation was successfully enqueued with Addressables; false if address is null/empty or if the Addressables system threw internally.
Type Parameters
Name Description
T

The type of asset to load.
Remarks

Use this overload in fire-and-check scenarios where the caller will poll handle.IsDone over subsequent frames and prefers not to handle exceptions. When the returned handle is valid, the caller must still release it via Release<T>(AsyncOperationHandle<T>).

UnloadSceneAsync(AsyncOperationHandle<SceneInstance>)

Starts the asynchronous unload of an Addressable scene using the original load handle, and returns a raw AsyncOperationHandle for the operation.

Declaration
public static AsyncOperationHandle<SceneInstance> UnloadSceneAsync(AsyncOperationHandle<SceneInstance> handle)
Parameters
Type Name Description
AsyncOperationHandle<SceneInstance> handle

The AsyncOperationHandle<SceneInstance> returned by the original LoadSceneAsync(string, LoadSceneMode, bool) call. Using the original handle ensures the Addressables reference count is properly decremented.
Returns
Type Description
AsyncOperationHandle<SceneInstance>

An AsyncOperationHandle<SceneInstance> for the unload operation.

UnloadSceneAsync(SceneInstance)

Starts the asynchronous unload of an Addressable scene identified by its SceneInstance and returns a raw AsyncOperationHandle for the operation.

Declaration
public static AsyncOperationHandle<SceneInstance> UnloadSceneAsync(SceneInstance sceneInstance)
Parameters
Type Name Description
SceneInstance sceneInstance

The SceneInstance to unload, as returned by a previous LoadSceneAsync(string, LoadSceneMode, bool) call.
Returns
Type Description
AsyncOperationHandle<SceneInstance>

An AsyncOperationHandle<SceneInstance> for the unload operation. The Addressables reference count is decremented automatically upon completion.
Remarks

For async/await usage, prefer UnloadSceneAsyncAwaitable(SceneInstance, CancellationToken).

UnloadSceneAsyncAwaitable(SceneInstance, CancellationToken)

Unloads an Addressable scene and suspends execution using Unity's Awaitable pattern, resuming once the scene has been fully unloaded and its Addressables reference decremented.

Declaration
public static Awaitable UnloadSceneAsyncAwaitable(SceneInstance sceneInstance, CancellationToken cancellationToken = default)
Parameters
Type Name Description
SceneInstance sceneInstance

The SceneInstance to unload, obtained from a prior load operation.
CancellationToken cancellationToken

An optional token that can cancel waiting for the unload to complete. Note that Unity does not always support mid-way scene-unload cancellation; the exception propagates but the scene may continue unloading in the background.
Returns
Type Description
Awaitable
Exceptions
Type Condition
AddressableException

Thrown with SceneUnloadFailed when Unity reports a failure; or with OperationCancelled on cancellation.

UnloadSceneWithResultAsync(SceneInstance, CancellationToken)

Unloads an Addressable scene and returns an AddressableResult indicating success or structured error information, never throwing an exception.

Declaration
public static Awaitable<AddressableResult> UnloadSceneWithResultAsync(SceneInstance sceneInstance, CancellationToken cancellationToken = default)
Parameters
Type Name Description
SceneInstance sceneInstance

The SceneInstance to unload, as returned by a prior load operation.
CancellationToken cancellationToken

An optional token that can cancel waiting for the unload to complete.
Returns
Type Description
Awaitable<AddressableResult>

An Awaitable that resolves to an AddressableResult with IsSuccess set to true on success, or containing SceneUnloadFailed or OperationCancelled on failure.

UpdateCatalogsAsync()

Checks with the remote content delivery network for updated versions of all loaded catalogs and downloads any that have changed, returning a raw AsyncOperationHandle whose result is the list of updated IResourceLocator instances.

Declaration
public static AsyncOperationHandle<List<IResourceLocator>> UpdateCatalogsAsync()
Returns
Type Description
AsyncOperationHandle<List<IResourceLocator>>

An AsyncOperationHandle<List<IResourceLocator>> whose result contains the updated resource locators. Must be released after use. For individual catalog IDs, prefer UpdateCatalogsAsyncAwaitable(CancellationToken), which extracts the locator ID strings.
Remarks

Call CheckForCatalogUpdatesAsync(CancellationToken) first to determine whether an update is available before committing to the full download.

UpdateCatalogsAsyncAwaitable(CancellationToken)

Updates all stale remote catalogs and suspends execution using Unity's Awaitable pattern, returning the IDs of the catalogs that were updated.

Declaration
public static Awaitable<List<string>> UpdateCatalogsAsyncAwaitable(CancellationToken cancellationToken = default)
Parameters
Type Name Description
CancellationToken cancellationToken

An optional token that can cancel the in-flight update. The handle is always released in a finally block regardless of outcome.
Returns
Type Description
Awaitable<List<string>>

A list of catalog ID strings (one per updated IResourceLocator). Returns an empty list when all catalogs are already up to date. The list does not include catalogs that failed to update.
Remarks

Combine with CheckForCatalogUpdatesAsync(CancellationToken) to selectively update only when stale catalogs exist, avoiding unnecessary network round-trips on every session start.

Exceptions
Type Condition
AddressableException

Thrown with CatalogUpdateFailed when Unity fails to complete the catalog update; or with OperationCancelled on cancellation.

See Also