Class AddressableExtensions

Provides extension methods for Unity Addressables types that enable a fluent, readable API for chaining completion callbacks, converting handles to Unity's Awaitable pattern, and loading assets directly from AssetReference or string address values.

Inheritance

object

AddressableExtensions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Scylla.Core.Util.Addressables

Assembly: ScyllaCore.dll

Syntax

public static class AddressableExtensions

Remarks

All members of this class are only compiled when the SCYLLA_HAS_ADDRESSABLES scripting define is present (i.e. the Unity Addressables package is installed). Without the package, the entire extension class body is stripped by the preprocessor and none of the methods are available.

Extension groups. Methods are organized into three functional groups:

AsyncOperationHandle extensions - AutoRelease<T>(AsyncOperationHandle<T>), OnComplete<T>(AsyncOperationHandle<T>, Action<T>, Action<AddressableException>), ToAwaitable<T>(AsyncOperationHandle<T>, CancellationToken), ToResult<T>(AsyncOperationHandle<T>, CancellationToken). These allow chaining and conversion of raw operation handles.
AssetReference extensions - LoadAssetAsync, LoadAssetAsyncAwaitable, InstantiateAsync, ReleaseAsset. Thin wrappers delegating to ScyllaAddressables for use on Inspector-assigned asset references.
String address extensions - LoadAddressable, LoadAddressableAwaitable, AddressableExists, InstantiateAddressable. Allow calling Addressables operations directly on address strings for concise call sites.

Methods

AddressableExists(string, CancellationToken)

Checks whether this address string resolves to at least one resource location in the Addressables catalog. Delegates to ExistsAsync(string, CancellationToken).

Declaration

public static Awaitable<bool> AddressableExists(this 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 lookup.

Returns

Type	Description
Awaitable<bool>	`true` if the address maps to at least one resource location; `false` otherwise.

AddressableExists<T>(string, CancellationToken)

Checks whether this address string resolves to at least one resource location of the given asset type in the Addressables catalog. Delegates to ExistsAsync<T>(string, CancellationToken).

Declaration

public static Awaitable<bool> AddressableExists<T>(this 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 lookup.

Returns

Type	Description
Awaitable<bool>	`true` if the address maps to at least one resource location of type `T`; `false` otherwise.

Type Parameters

Name	Description
T	The asset type to filter the location query to.

AutoRelease<T>(AsyncOperationHandle<T>)

Registers a completion callback on the handle that automatically releases it via Addressables.Release as soon as the operation finishes, preventing the need for manual handle management when only the loaded result (not the handle) needs to be kept.

Declaration

public static AsyncOperationHandle<T> AutoRelease<T>(this AsyncOperationHandle<T> handle)

Parameters

Type	Name	Description
AsyncOperationHandle<T>	handle	The handle to configure for automatic release on completion.

Returns

Type	Description
AsyncOperationHandle<T>	The same `handle` instance, allowing fluent chaining with other extension methods such as OnComplete<T>(AsyncOperationHandle<T>, Action<T>, Action<AddressableException>).

Type Parameters

Name	Description
T	The type of the handle result.

Remarks

The release only happens if the handle is still valid at completion time. This guards against double-release in edge cases where the handle was released externally.

Be aware that once a handle is released, its Result may be garbage collected if there are no other references. Only use AutoRelease when you plan to retrieve the result from within the same Completed callback or immediately after awaiting, before the handle is released.

ScyllaAddressables.LoadAsync<Sprite>("ui/icon")
    .AutoRelease()
    .OnComplete(sprite => icon.sprite = sprite);

InstantiateAddressable(string)

Starts the asynchronous instantiation of the prefab at this address string at the world origin, returning a raw AsyncOperationHandle. Delegates to InstantiateAsync(string).

Declaration

public static AsyncOperationHandle<GameObject> InstantiateAddressable(this string address)

Parameters

Type	Name	Description
string	address	The Addressables key string identifying the prefab. Must not be `null` or empty.

Returns

Type	Description
AsyncOperationHandle<GameObject>	An `AsyncOperationHandle<GameObject>` for the instantiation. Use ReleaseInstance(GameObject) to destroy and release when done.

Exceptions

Type	Condition
AddressableException	Thrown synchronously with NullAddress when this address is `null` or empty.

InstantiateAddressable(string, Transform)

Starts the asynchronous instantiation of the prefab at this address string, parenting the result to the specified transform. Delegates to InstantiateAsync(string, Transform).

Declaration

public static AsyncOperationHandle<GameObject> InstantiateAddressable(this string address, Transform parent)

Parameters

Type	Name	Description
string	address	The Addressables key string identifying the prefab. Must not be `null` or empty.
Transform	parent	The `Transform` to parent the instantiated object to. May be `null` for scene root.

Returns

Type	Description
AsyncOperationHandle<GameObject>	An `AsyncOperationHandle<GameObject>` for the instantiation.

Exceptions

Type	Condition
AddressableException	Thrown synchronously with NullAddress when this address is `null` or empty.

InstantiateAddressable(string, Vector3, Quaternion)

Starts the asynchronous instantiation of the prefab at this address string at a specific world position and rotation. Delegates to InstantiateAsync(string, Vector3, Quaternion).

Declaration

public static AsyncOperationHandle<GameObject> InstantiateAddressable(this string address, Vector3 position, Quaternion rotation)

Parameters

Type	Name	Description
string	address	The Addressables key string identifying the prefab. 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>` for the instantiation.

Exceptions

Type	Condition
AddressableException	Thrown synchronously with NullAddress when this address is `null` or empty.

InstantiateAsync(AssetReference)

Starts the asynchronous instantiation of the prefab identified by this AssetReference at the world origin and returns a raw AsyncOperationHandle that the caller manages.

Declaration

public static AsyncOperationHandle<GameObject> InstantiateAsync(this AssetReference reference)

Parameters

Type	Name	Description
AssetReference	reference	The `AssetReference` pointing to the prefab asset.

Returns

Type	Description
AsyncOperationHandle<GameObject>	An `AsyncOperationHandle<GameObject>` whose result is the instantiated `GameObject`. Use ReleaseInstance(GameObject) to destroy the instance and release its Addressables reference.

InstantiateAsync(AssetReference, Transform)

Starts the asynchronous instantiation of the prefab identified by this AssetReference as a child of the specified parent transform, returning a raw AsyncOperationHandle.

Declaration

public static AsyncOperationHandle<GameObject> InstantiateAsync(this AssetReference reference, Transform parent)

Parameters

Type	Name	Description
AssetReference	reference	The `AssetReference` pointing to the prefab asset.
Transform	parent	The `Transform` to parent the instantiated object to. May be `null` for scene root.

Returns

Type	Description
AsyncOperationHandle<GameObject>	An `AsyncOperationHandle<GameObject>` for the instantiation. Use ReleaseInstance(GameObject) when done.

InstantiateAsync(AssetReference, Vector3, Quaternion)

Starts the asynchronous instantiation of the prefab identified by this AssetReference at a specific world position and rotation, returning a raw AsyncOperationHandle.

Declaration

public static AsyncOperationHandle<GameObject> InstantiateAsync(this AssetReference reference, Vector3 position, Quaternion rotation)

Parameters

Type	Name	Description
AssetReference	reference	The `AssetReference` pointing to the prefab asset.
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>` for the instantiation. Use ReleaseInstance(GameObject) when done.

LoadAddressableAwaitable<T>(string, CancellationToken)

Loads the asset at this address string using Unity's Awaitable pattern, suspending execution until the load completes. Delegates to LoadAsyncAwaitable<T>(string, CancellationToken).

Declaration

public static Awaitable<T> LoadAddressableAwaitable<T>(this string address, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	address	The Addressables key string. Must not be `null` or empty.
CancellationToken	cancellationToken	An optional token that can cancel the in-flight load.

Returns

Type	Description
Awaitable<T>	The loaded asset of type `T`.

Type Parameters

Name	Description
T	The type of asset to load.

Exceptions

Type	Condition
AddressableException	Thrown with NullAddress, LoadFailed, or OperationCancelled depending on the failure mode.

LoadAddressable<T>(string)

Starts an asynchronous load of the asset at this address string and returns a raw AsyncOperationHandle. Shorthand for LoadAsync<T>(string), enabling concise call sites such as "ui/icon".LoadAddressable<Sprite>().

Declaration

public static AsyncOperationHandle<T> LoadAddressable<T>(this string address)

Parameters

Type	Name	Description
string	address	The Addressables key string. Must not be `null` or empty.

Returns

Type	Description
AsyncOperationHandle<T>	An `AsyncOperationHandle<T>` for the load operation. Must be released when done.

Type Parameters

Name	Description
T	The type of asset to load.

Exceptions

Type	Condition
AddressableException	Thrown synchronously with NullAddress when this address is `null` or empty.

LoadAssetAsyncAwaitable<T>(AssetReference, CancellationToken)

Loads the asset referenced by this AssetReference and suspends execution using Unity's Awaitable pattern, returning the asset directly upon completion. Delegates to LoadAsyncAwaitable<T>(AssetReference, CancellationToken).

Declaration

public static Awaitable<T> LoadAssetAsyncAwaitable<T>(this AssetReference reference, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
AssetReference	reference	The `AssetReference` to load from. Must not be `null`.
CancellationToken	cancellationToken	An optional token that can cancel the in-flight load. When cancelled, the handle is released before the exception propagates.

Returns

Type	Description
Awaitable<T>	The loaded asset of type `T`. The caller is responsible for releasing it via ReleaseAsset(AssetReference) when done.

Type Parameters

Name	Description
T	The type of asset to load.

Exceptions

Type	Condition
AddressableException	Thrown with NullAddress when `reference` is `null`; with LoadFailed on failure; or with OperationCancelled on cancellation.

LoadAssetAsync<T>(AssetReference)

Starts an asynchronous load of the asset referenced by this AssetReference and returns a raw AsyncOperationHandle that the caller manages. Delegates to AssetReference.LoadAssetAsync<T>().

Declaration

public static AsyncOperationHandle<T> LoadAssetAsync<T>(this AssetReference reference)

Parameters

Type	Name	Description
AssetReference	reference	The `AssetReference` to load from. Must not be `null`.

Returns

Type	Description
AsyncOperationHandle<T>	An `AsyncOperationHandle<T>` for the load operation. Must be released via ReleaseAsset(AssetReference) or Release<T>(AsyncOperationHandle<T>) when the asset is no longer needed.

Type Parameters

Name	Description
T	The type of asset to load. Must be compatible with the asset type assigned to the reference.

Remarks

This extension provides a consistent call surface for AssetReference loads alongside the other members of this class. For async/await usage, prefer LoadAssetAsyncAwaitable<T>(AssetReference, CancellationToken).

OnComplete<T>(AsyncOperationHandle<T>, Action<T>, Action<AddressableException>)

Registers success and error completion callbacks on an AsyncOperationHandle, providing a cleaner alternative to accessing the raw handle.Completed event directly.

Declaration

public static AsyncOperationHandle<T> OnComplete<T>(this AsyncOperationHandle<T> handle, Action<T> onSuccess, Action<AddressableException> onError = null)

Parameters

Type	Name	Description
AsyncOperationHandle<T>	handle	The handle to attach callbacks to.
Action<T>	onSuccess	The callback invoked when `AsyncOperationStatus.Succeeded` is reported, receiving the loaded result of type `T`. Must not be `null` in practice, though the method accepts `null` without throwing.
Action<AddressableException>	onError	An optional callback invoked when the operation status is anything other than `Succeeded`, receiving an AddressableException with LoadFailed and the original operation exception as its inner exception. Pass `null` to silently discard errors.

Returns

Type	Description
AsyncOperationHandle<T>	The same `handle` instance for fluent chaining with AutoRelease<T>(AsyncOperationHandle<T>) or other extensions.

Type Parameters

Name	Description
T	The type of the handle result.

Remarks

The callback is registered on handle.Completed. Both callbacks are invoked on the Unity main thread when the operation finishes.

ScyllaAddressables.LoadAsync<AudioClip>("sfx/jump")
    .OnComplete(
        clip => audioSource.PlayOneShot(clip),
        ex => Debug.LogError($"Load failed: {ex.Message}")
    )
    .AutoRelease();

ReleaseAsset(AssetReference)

Releases the asset that was loaded from this AssetReference, decrementing its Addressables reference count and allowing the underlying bundle to be unloaded when no other references remain.

Declaration

public static void ReleaseAsset(this AssetReference reference)

Parameters

Type	Name	Description
AssetReference	reference	The `AssetReference` whose loaded asset should be released. This directly calls `AssetReference.ReleaseAsset()`. The reference object itself remains valid and can be used to load the asset again later.

Remarks

Only call this once per load. Calling it when no asset is loaded via this reference is handled internally by the Addressables system (no-op or harmless).

ToAwaitable<T>(AsyncOperationHandle<T>, CancellationToken)

Suspends execution until the AsyncOperationHandle completes and returns the result, bridging the Unity Addressables callback model to Unity's Awaitable async pattern.

Declaration

public static Awaitable<T> ToAwaitable<T>(this AsyncOperationHandle<T> handle, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
AsyncOperationHandle<T>	handle	The in-flight or already-completed handle to await. The caller retains ownership and must release this handle separately when done using the result.
CancellationToken	cancellationToken	An optional token that can cancel the wait. When cancelled, the suspension ends and an AddressableException with OperationCancelled is thrown. The handle itself is NOT released on cancellation - the caller must release it.

Returns

Type	Description
Awaitable<T>	The result of the completed operation of type `T`.

Type Parameters

Name	Description
T	The type of the handle result.

Remarks

This overload does NOT release the handle on cancellation, unlike the equivalent methods in ScyllaAddressables. Prefer ToResult<T>(AsyncOperationHandle<T>, CancellationToken) when exception-free error handling is preferred.

Exceptions

Type	Condition
AddressableException	Thrown with LoadFailed when the handle completes with a non-succeeded status; or with OperationCancelled when the `cancellationToken` fires before completion.

ToResult<T>(AsyncOperationHandle<T>, CancellationToken)

Suspends execution until the AsyncOperationHandle completes and wraps the outcome in an AddressableResult<T>, providing exception-free error handling for awaitable workflows.

Declaration

public static Awaitable<AddressableResult<T>> ToResult<T>(this AsyncOperationHandle<T> handle, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
AsyncOperationHandle<T>	handle	The in-flight or already-completed handle to await. The caller retains ownership and must release this handle separately when done.
CancellationToken	cancellationToken	An optional token that can cancel the wait. When cancelled, the returned result contains OperationCancelled rather than throwing an exception.

Returns

Type	Description
Awaitable<AddressableResult<T>>	An `Awaitable` that resolves to an AddressableResult<T>. On success, IsSuccess is `true` and Value contains the loaded result. On failure or cancellation, the result contains the relevant AddressableErrorCode.

Type Parameters

Name	Description
T	The type of the handle result.

Remarks

Unlike ToAwaitable<T>(AsyncOperationHandle<T>, CancellationToken), this overload never throws. Use it when the caller prefers to inspect a result object rather than handle exceptions.