Version: v3

AssetLoaders

Important Attention Reminder

Coding Style wiki

AssetLoaders is the unified asset-loading entry point (Facade) of the AssetLoader module. It combines Unity's native Resources and Bundle (YooAsset) loading paths, covering sync/async loading, preloading, instantiation, unloading, and releasing of scenes, regular assets, and raw files, plus batch management by group (GroupCacher) keyed by a custom groupId. All caches are managed with reference counting.


Namespace	`OxGFrame.AssetLoader`
Type	`public static class`
Source	AssetLoaders.cs

using OxGFrame.AssetLoader;

Attention Before loading from bundles, a PatchLauncher must be set up in the scene and the packages must be initialized (see the AssetLoader Introduction and AssetPatcher).

Quick Start

// Load and instantiate a prefab (bundle assets use their Address)
var player = await AssetLoaders.InstantiateAssetAsync<GameObject>("PlayerUI");

// Load from Resources (res# prefix + relative path under Resources)
var icon = await AssetLoaders.LoadAssetAsync<Texture2D>("res#Textures/PlayerIcon");

// Preload assets in batch, so later loads hit the cache directly
await AssetLoaders.PreloadAssetAsync<GameObject>(new string[] { "PlayerUI", "EnemyUI" });

// Load a bundle scene (Additive)
await AssetLoaders.LoadAdditiveSceneAsync("BattleScene");

// Load raw file content (bundle only)
string json = await AssetLoaders.LoadRawFileAsync<string>("GameConfig");

// Unload the asset (pair with the load call to keep the reference count correct)
AssetLoaders.UnloadAsset("PlayerUI");

General Rules

Asset Name Prefix

assetName supports prefix resolution, which determines the loading source:

Prefix	Description	Example
res#	Loads the asset from Unity's native Resources (by relative path under Resources).	`res#Prefabs/PlayerUI`
None	Loads the asset from the Asset Bundle (YooAsset) by default (using its addressable name).	`PlayerUI`

Attention

Scene and raw file (RawFile) methods only support bundle loading — the res# prefix is not supported (passing res# to RawFile methods logs an error).
The build# prefix for Build Settings scenes (Scenes In Build) is handled by the CoreFrames.USFrame scene system, not by AssetLoaders.

Package

All bundle-loading methods provide packageName overloads:

Without packageName: the default package is used automatically (AssetPatcher.GetDefaultPackageName()).
With packageName: the asset is loaded from the specified package, useful for multi-package setups (see AssetPatcher General Rules for App/DLC package concepts and PlayMode).

YooAsset Version Compatibility

Since v3.7.0, both YooAsset 2.x and 3.x are supported: YOOASSET_2 / YOOASSET_3 is defined automatically from the installed version, the public API signatures are identical, and no project code changes are required (e.g., raw files are loaded internally as RawFileObject under v3 with the same behavior). See AssetPatcher › YooAsset Version Compatibility for the full comparison.

Reference Counting & Unloading

Attention

Every successful Load / Instantiate call increments the asset's cache reference count by +1; Unload decrements it by -1, and the asset is actually released and removed from the cache only when the count reaches zero.
Preload only loads the asset into the cache (count stays 0) and does not add a reference; assets already in the cache are skipped.
With forceUnload = true, the reference count is bypassed and the asset is released immediately.
The Release family (ReleaseAssets / ReleaseScenes / ReleaseRawFiles) force-releases the entire cache — only suitable for moments like level transitions or game shutdown.
If an unload is requested while the asset is still loading, the request is queued and executed after the load completes.

Important Instances created by the Instantiate family do not return their reference automatically when destroyed. For bundle assets, call Unload and Destroy in pairs instead of destroying the object only, to keep the reference count correct.

Load Retry

Failed loads are retried automatically, up to the limit given by the maxRetryCount parameter (default MAX_RETRY_COUNT = 3). Once retries are exhausted, a warning is logged and null (or default) is returned. Scene loading always uses a fixed retry count of 1, regardless of the parameter.

Progression Callback

public delegate void Progression(float progress, float currentCount, float totalCount)

Parameter	Type	Description
progress	`float`	Overall progress (`currentCount / totalCount`, 0–1).
currentCount	`float`	Current progress count. For batch preloading, the number of completed assets; for a single load, the loading progress (0–1).
totalCount	`float`	Total count. For batch preloading, the total number of assets; for a single load, `1`.

LoadType Enum

Batch release methods take a LoadType to select which cache to process:

Value	Description
`Any`	Processes both the Resources and Bundle caches.
`Resources`	Processes the Resources cache only.
`Bundle`	Processes the Bundle cache only.

Scene Loading

Sync/async loading of bundle scenes, supporting Single (replaces the current scene) and Additive (stacks scenes) modes. Additive scenes are tracked with a stack counter and must be unloaded manually.

Method Overview

Scene Loading

Method	Description
LoadSceneAsync	Loads a bundle scene asynchronously (full-parameter version).
LoadScene	Loads a bundle scene synchronously.
LoadSingleSceneAsync	Loads a scene asynchronously in `Single` mode (shortcut).
LoadSingleScene	Loads a scene synchronously in `Single` mode (shortcut).
LoadAdditiveSceneAsync	Loads a scene asynchronously in `Additive` mode (shortcut).
LoadAdditiveScene	Loads a scene synchronously in `Additive` mode (shortcut).

Scene Unloading

Method	Description
UnloadScene	Unloads an additive scene (optionally all stacked instances recursively).
ReleaseScenes	Force-releases all additive scene caches.

LoadSceneAsync

public static async UniTask<BundlePack> LoadSceneAsync(string assetName, LoadSceneMode loadSceneMode = LoadSceneMode.Single, bool activateOnLoad = true, uint priority = 100, Progression progression = null)
public static async UniTask<BundlePack> LoadSceneAsync(string assetName, LoadSceneMode loadSceneMode = LoadSceneMode.Single, LocalPhysicsMode localPhysicsMode = LocalPhysicsMode.None, bool activateOnLoad = true, uint priority = 100, Progression progression = null)
public static async UniTask<BundlePack> LoadSceneAsync(string packageName, string assetName, LoadSceneMode loadSceneMode = LoadSceneMode.Single, bool activateOnLoad = true, uint priority = 100, Progression progression = null)
public static async UniTask<BundlePack> LoadSceneAsync(string packageName, string assetName, LoadSceneMode loadSceneMode = LoadSceneMode.Single, LocalPhysicsMode localPhysicsMode = LocalPhysicsMode.None, bool activateOnLoad = true, uint priority = 100, Progression progression = null)

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Scene asset name (Address; bundle scenes only).
loadSceneMode	`LoadSceneMode`	Scene loading mode (`Single` replaces the current scene / `Additive` stacks scenes). Default: `LoadSceneMode.Single`
localPhysicsMode	`LocalPhysicsMode`	Local physics mode of the scene (whether to create an independent 2D/3D physics scene). Default: `LocalPhysicsMode.None`
activateOnLoad	`bool`	Whether to activate the scene immediately after loading. When `false`, activation is suspended and can be resumed later via `BundlePack.UnsuspendScene()` on the returned pack. Default: `true`
priority	`uint`	YooAsset async loading priority (bundle loading only). Default: `100`
progression	`Progression`	Loading progress callback. Default: `null`

Returns

UniTask<BundlePack> — the scene wrapper object (holds the YooAsset SceneHandle; use GetScene() to get the Scene and UnsuspendScene() to resume activation); null if loading fails.

Description

Loads a bundle scene asynchronously.

Attention

After a successful Single load, the internal additive scene counters are cleared (previous scenes are unloaded automatically by Unity).
In Additive mode, the same scene can be loaded multiple times; instances are tracked with a stack counter (name#index) and must be unloaded manually via UnloadScene.
Single mode deduplicates concurrent loads of the same scene: calling again while loading awaits the same in-flight task.

Reminder The overloads differ only in the type of the third parameter (bool vs. LocalPhysicsMode), so short calls that omit the later arguments can be ambiguous to the compiler. For everyday use, prefer LoadSingleSceneAsync / LoadAdditiveSceneAsync, or pass enough arguments explicitly.

Example

// Fully specified call: load the main scene with activation suspended
var pack = await AssetLoaders.LoadSceneAsync("MainScene", LoadSceneMode.Single, LocalPhysicsMode.None, activateOnLoad: false);

// Activate the scene when appropriate
pack.UnsuspendScene();

LoadScene

public static BundlePack LoadScene(string assetName, LoadSceneMode loadSceneMode = LoadSceneMode.Single, Progression progression = null)
public static BundlePack LoadScene(string assetName, LoadSceneMode loadSceneMode = LoadSceneMode.Single, LocalPhysicsMode localPhysicsMode = LocalPhysicsMode.None, Progression progression = null)
public static BundlePack LoadScene(string packageName, string assetName, LoadSceneMode loadSceneMode = LoadSceneMode.Single, Progression progression = null)
public static BundlePack LoadScene(string packageName, string assetName, LoadSceneMode loadSceneMode = LoadSceneMode.Single, LocalPhysicsMode localPhysicsMode = LocalPhysicsMode.None, Progression progression = null)

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Scene asset name (Address; bundle scenes only).
loadSceneMode	`LoadSceneMode`	Scene loading mode. Default: `LoadSceneMode.Single`
localPhysicsMode	`LocalPhysicsMode`	Local physics mode of the scene. Default: `LocalPhysicsMode.None`
progression	`Progression`	Loading progress callback. Default: `null`

Returns

BundlePack — the scene wrapper object; null if loading fails.

Description

Loads a bundle scene synchronously. Behaves like LoadSceneAsync (without the activateOnLoad and priority parameters).

LoadSingleSceneAsync

public static async UniTask<BundlePack> LoadSingleSceneAsync(string assetName, bool activateOnLoad = true, uint priority = 100, Progression progression = null)
public static async UniTask<BundlePack> LoadSingleSceneAsync(string packageName, string assetName, bool activateOnLoad = true, uint priority = 100, Progression progression = null)

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Scene asset name (Address; bundle scenes only).
activateOnLoad	`bool`	Whether to activate the scene immediately after loading. Default: `true`
priority	`uint`	YooAsset async loading priority. Default: `100`
progression	`Progression`	Loading progress callback. Default: `null`

Returns

UniTask<BundlePack> — the scene wrapper object; null if loading fails.

Description

Shortcut for loading a scene asynchronously in Single mode (replacing the current scene). Equivalent to calling LoadSceneAsync with loadSceneMode = LoadSceneMode.Single and localPhysicsMode = LocalPhysicsMode.None.

Example

await AssetLoaders.LoadSingleSceneAsync("MainScene");

LoadSingleScene

public static BundlePack LoadSingleScene(string assetName, Progression progression = null)
public static BundlePack LoadSingleScene(string packageName, string assetName, Progression progression = null)

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Scene asset name (Address; bundle scenes only).
progression	`Progression`	Loading progress callback. Default: `null`

Returns

BundlePack — the scene wrapper object; null if loading fails.

Description

Shortcut for loading a scene synchronously in Single mode.

LoadAdditiveSceneAsync

public static async UniTask<BundlePack> LoadAdditiveSceneAsync(string assetName, bool activateOnLoad = true, uint priority = 100, Progression progression = null)
public static async UniTask<BundlePack> LoadAdditiveSceneAsync(string packageName, string assetName, bool activateOnLoad = true, uint priority = 100, Progression progression = null)

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Scene asset name (Address; bundle scenes only).
activateOnLoad	`bool`	Whether to activate the scene immediately after loading. Default: `true`
priority	`uint`	YooAsset async loading priority. Default: `100`
progression	`Progression`	Loading progress callback. Default: `null`

Returns

UniTask<BundlePack> — the scene wrapper object; null if loading fails.

Description

Shortcut for loading a scene asynchronously in Additive mode (stacking). The same scene can be loaded multiple times; instances are tracked with a stack counter and must be unloaded manually via UnloadScene.

Example

// Stack the battle scene on top
await AssetLoaders.LoadAdditiveSceneAsync("BattleScene");

// Unload it when the battle ends
AssetLoaders.UnloadScene("BattleScene");

LoadAdditiveScene

public static BundlePack LoadAdditiveScene(string assetName, Progression progression = null)
public static BundlePack LoadAdditiveScene(string packageName, string assetName, Progression progression = null)

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Scene asset name (Address; bundle scenes only).
progression	`Progression`	Loading progress callback. Default: `null`

Returns

BundlePack — the scene wrapper object; null if loading fails.

Description

Shortcut for loading a scene synchronously in Additive mode.

UnloadScene

public static void UnloadScene(string assetName, bool recursively = false)

Parameters

Parameter	Type	Description
assetName	`string`	Scene asset name.
recursively	`bool`	Whether to unload all stacked instances of the scene. When `false`, only the most recently loaded one is unloaded (last in, first out). Default: `false`

Description

Unloads an additive scene. When the stack counter for the scene reaches zero, YooAsset is asked to release unused assets.

Attention Only scenes loaded in Additive mode can be unloaded here. Calling this for a Single scene or an unknown name logs an error (Single scenes are unloaded automatically by Unity on scene switch).

ReleaseScenes

public static void ReleaseScenes()

Description

Force-unloads all additive scenes, clears the stack counters, and finally calls Resources.UnloadUnusedAssets() to reclaim memory.

Important This releases every additive scene — call it only when none of them is needed anymore (e.g., a full level transition).

Cache Query

Query and retrieve the asset wrapper objects currently held in the cache.

Method Overview

Method	Description
HasInCache	Checks whether an asset is already in the cache.
GetFromCache<T>	Gets the cached asset wrapper object (`ResourcePack` / `BundlePack`).

HasInCache

public static bool HasInCache(string assetName)

Parameters

Parameter	Type	Description
assetName	`string`	Asset name (supports the `res#` prefix).

Returns

bool — whether the asset exists in the cache (the Resources or Bundle cache is selected automatically by prefix).

Description

Checks whether the asset is already in the cache (preloaded or loaded).

GetFromCache<T>

public static T GetFromCache<T>(string assetName) where T : AssetObject

Parameters

Parameter	Type	Description
assetName	`string`	Asset name (supports the `res#` prefix).

Returns

T — the cached asset wrapper object; null if not found.

Description

Gets the cached asset wrapper object. For assets loaded from Resources the type is ResourcePack; for bundle assets it is BundlePack (which exposes the YooAsset operation handle via GetOperationHandle<T>()).

Example

var pack = AssetLoaders.GetFromCache<BundlePack>("PlayerUI");
if (pack != null)
    Debug.Log($"Reference count: {pack.refCount}");

Asset Loading

Preloading, loading, instantiation, and unloading of regular assets (UnityEngine.Object such as prefabs, textures, audio clips), supporting both Resources (res#) and Bundle sources.

Method Overview

Preload

Method	Description
PreloadAssetAsync<T>	Preloads assets into the cache asynchronously (supports batches).
PreloadAsset<T>	Preloads assets into the cache synchronously (supports batches).

Load

Method	Description
LoadAssetAsync<T>	Loads an asset asynchronously and returns the asset object.
LoadAsset<T>	Loads an asset synchronously and returns the asset object.

Instantiate

Method	Description
InstantiateAssetAsync<T>	Loads an asset asynchronously and instantiates it directly (various position/parent overloads).
InstantiateAsset<T>	Loads an asset synchronously and instantiates it directly.

Unload & Release

Method	Description
UnloadAsset	Unloads a single asset (reference count -1; can force-unload).
ReleaseAssets	Force-releases the entire asset cache (scoped by `LoadType`).

PreloadAssetAsync<T>

public static async UniTask PreloadAssetAsync<T>(string assetName, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static async UniTask PreloadAssetAsync<T>(string packageName, string assetName, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static async UniTask PreloadAssetAsync<T>(string[] assetNames, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static async UniTask PreloadAssetAsync<T>(string packageName, string[] assetNames, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Asset name (bundle assets use their Address; supports the `res#` prefix).
assetNames	`string[]`	Array of asset names (batch preloading; `res#` and bundle names can be mixed and are routed automatically).
priority	`uint`	YooAsset async loading priority (bundle loading only). Default: `0`
progression	`Progression`	Preloading progress callback. Default: `null`
maxRetryCount	`byte`	Maximum retry count on load failure. Default: `MAX_RETRY_COUNT` (`3`)

Returns

UniTask — an awaitable async operation.

Description

Loads assets into the cache ahead of time, so later LoadAssetAsync or InstantiateAssetAsync calls hit the cache directly without a loading delay.

Attention Preloading does not add a reference; assets already in the cache are skipped.

Example

// Preload a single asset
await AssetLoaders.PreloadAssetAsync<GameObject>("PlayerUI");

// Preload in batch (mixing Bundle and Resources) while tracking progress
await AssetLoaders.PreloadAssetAsync<GameObject>(
    new string[] { "PlayerUI", "res#Prefabs/EnemyUI" },
    progression: (progress, currentCount, totalCount) =>
    {
        Debug.Log($"Preload progress: {progress * 100f}% ({currentCount}/{totalCount})");
    });

PreloadAsset<T>

public static void PreloadAsset<T>(string assetName, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static void PreloadAsset<T>(string packageName, string assetName, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static void PreloadAsset<T>(string[] assetNames, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static void PreloadAsset<T>(string packageName, string[] assetNames, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Asset name (bundle assets use their Address; supports the `res#` prefix).
assetNames	`string[]`	Array of asset names (batch preloading).
progression	`Progression`	Preloading progress callback. Default: `null`
maxRetryCount	`byte`	Maximum retry count on load failure. Default: `MAX_RETRY_COUNT` (`3`)

Description

Preloads assets into the cache synchronously. Behaves like PreloadAssetAsync.

LoadAssetAsync<T>

public static async UniTask<T> LoadAssetAsync<T>(string assetName, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static async UniTask<T> LoadAssetAsync<T>(string packageName, string assetName, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Asset name (bundle assets use their Address; supports the `res#` prefix).
priority	`uint`	YooAsset async loading priority (bundle loading only). Default: `0`
progression	`Progression`	Loading progress callback. Default: `null`
maxRetryCount	`byte`	Maximum retry count on load failure. Default: `MAX_RETRY_COUNT` (`3`)

Returns

UniTask<T> — the loaded asset object (reference count +1); null if loading fails.

Description

Loads an asset asynchronously and returns the asset object (without instantiating it).

Attention

Assets already in the cache are returned directly (the reference count is still incremented).
If the same asset is already loading, the call awaits the in-flight task and shares its result instead of loading again.

Example

// Load from a bundle
var uiPrefab = await AssetLoaders.LoadAssetAsync<GameObject>("PlayerUI");

// Load from a specific package
var dlcPrefab = await AssetLoaders.LoadAssetAsync<GameObject>("Dlc01Package", "DlcShopUI");

// Load from Resources
var icon = await AssetLoaders.LoadAssetAsync<Texture2D>("res#Textures/PlayerIcon");

LoadAsset<T>

public static T LoadAsset<T>(string assetName, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static T LoadAsset<T>(string packageName, string assetName, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Asset name (bundle assets use their Address; supports the `res#` prefix).
progression	`Progression`	Loading progress callback. Default: `null`
maxRetryCount	`byte`	Maximum retry count on load failure. Default: `MAX_RETRY_COUNT` (`3`)

Returns

T — the loaded asset object (reference count +1); null if loading fails.

Description

Loads an asset synchronously and returns the asset object. Behaves like LoadAssetAsync.

InstantiateAssetAsync<T>

public static async UniTask<T> InstantiateAssetAsync<T>(string assetName, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static async UniTask<T> InstantiateAssetAsync<T>(string packageName, string assetName, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static async UniTask<T> InstantiateAssetAsync<T>(string assetName, Vector3 position, Quaternion rotation, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static async UniTask<T> InstantiateAssetAsync<T>(string packageName, string assetName, Vector3 position, Quaternion rotation, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static async UniTask<T> InstantiateAssetAsync<T>(string assetName, Vector3 position, Quaternion rotation, Transform parent, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static async UniTask<T> InstantiateAssetAsync<T>(string packageName, string assetName, Vector3 position, Quaternion rotation, Transform parent, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static async UniTask<T> InstantiateAssetAsync<T>(string assetName, Transform parent, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static async UniTask<T> InstantiateAssetAsync<T>(string packageName, string assetName, Transform parent, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static async UniTask<T> InstantiateAssetAsync<T>(string assetName, Transform parent, bool worldPositionStays, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static async UniTask<T> InstantiateAssetAsync<T>(string packageName, string assetName, Transform parent, bool worldPositionStays, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Asset name (bundle assets use their Address; supports the `res#` prefix).
position	`Vector3`	Position of the instance.
rotation	`Quaternion`	Rotation of the instance.
parent	`Transform`	Parent node the instance is attached to.
worldPositionStays	`bool`	Whether to keep the world position when parenting.
priority	`uint`	YooAsset async loading priority (bundle loading only). Default: `0`
progression	`Progression`	Loading progress callback. Default: `null`
maxRetryCount	`byte`	Maximum retry count on load failure. Default: `MAX_RETRY_COUNT` (`3`)

Returns

UniTask<T> — the instantiated clone; null if loading fails (no instantiation is performed).

Description

Loads an asset asynchronously and instantiates it directly with Object.Instantiate. The overloads map to Unity's instantiation parameters (position, rotation, parent, world-position preservation).

Important Every call increments the source asset's reference count by +1. Destroying the instance does not return the reference — pair the call with UnloadAsset.

Example

// Load and instantiate
var player = await AssetLoaders.InstantiateAssetAsync<GameObject>("PlayerUI");

// With position and rotation
var enemy = await AssetLoaders.InstantiateAssetAsync<GameObject>("EnemyUI", new Vector3(0, 1, 0), Quaternion.identity);

// Attached to a parent
var hpBar = await AssetLoaders.InstantiateAssetAsync<GameObject>("HpBar", this.transform);

// After destroying the instance, return the reference in pair
Object.Destroy(player);
AssetLoaders.UnloadAsset("PlayerUI");

InstantiateAsset<T>

public static T InstantiateAsset<T>(string assetName, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static T InstantiateAsset<T>(string packageName, string assetName, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static T InstantiateAsset<T>(string assetName, Vector3 position, Quaternion rotation, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static T InstantiateAsset<T>(string packageName, string assetName, Vector3 position, Quaternion rotation, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static T InstantiateAsset<T>(string assetName, Vector3 position, Quaternion rotation, Transform parent, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static T InstantiateAsset<T>(string packageName, string assetName, Vector3 position, Quaternion rotation, Transform parent, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static T InstantiateAsset<T>(string assetName, Transform parent, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static T InstantiateAsset<T>(string packageName, string assetName, Transform parent, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static T InstantiateAsset<T>(string assetName, Transform parent, bool worldPositionStays, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static T InstantiateAsset<T>(string packageName, string assetName, Transform parent, bool worldPositionStays, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Asset name (bundle assets use their Address; supports the `res#` prefix).
position	`Vector3`	Position of the instance.
rotation	`Quaternion`	Rotation of the instance.
parent	`Transform`	Parent node the instance is attached to.
worldPositionStays	`bool`	Whether to keep the world position when parenting.
progression	`Progression`	Loading progress callback. Default: `null`
maxRetryCount	`byte`	Maximum retry count on load failure. Default: `MAX_RETRY_COUNT` (`3`)

Returns

T — the instantiated clone; null if loading fails.

Description

Loads an asset synchronously and instantiates it directly. Behaves like InstantiateAssetAsync.

UnloadAsset

public static void UnloadAsset(string assetName, bool forceUnload = false)

Parameters

Parameter	Type	Description
assetName	`string`	Asset name (supports the `res#` prefix).
forceUnload	`bool`	Whether to bypass reference counting and force-unload. Default: `false`

Description

Unloads a single asset: decrements the reference count by 1; when the count reaches zero (or forceUnload = true) the asset is actually released and removed from the cache. For bundle assets, YooAsset is then asked to unload unused assets.

Attention

If the asset is not in the cache, a warning is logged and the call is skipped.
If the asset is still loading, the unload request is queued and executed after the load completes.

Example

// Regular unload (reference count -1)
AssetLoaders.UnloadAsset("PlayerUI");

// Force unload (bypasses reference counting)
AssetLoaders.UnloadAsset("PlayerUI", true);

ReleaseAssets

public static void ReleaseAssets(LoadType loadType = LoadType.Any)

Parameters

Parameter	Type	Description
loadType	`LoadType`	Release scope (`Any` / `Resources` / `Bundle`; see the LoadType enum). Default: `LoadType.Any`

Description

Force-releases all assets in the selected cache (bypassing reference counting) and calls Resources.UnloadUnusedAssets() to reclaim memory.

Important Make sure the assets are no longer referenced before releasing.

Raw File Loading

Loading of raw files (Config, Json, Bin, Mp4, etc.), returning text content, byte data, or the local file path directly.

Attention RawFile only supports Bundle loading (the res# prefix is not supported and logs an error).

Method Overview

File Path

Method	Description
GetRawFilePathAsync	Gets the local physical path of a raw file asynchronously.
GetRawFilePath	Gets the local physical path of a raw file synchronously.

Preload

Method	Description
PreloadRawFileAsync	Preloads raw files into the cache asynchronously (supports batches).
PreloadRawFile	Preloads raw files into the cache synchronously (supports batches).

Load

Method	Description
LoadRawFileAsync<T>	Loads raw file content asynchronously (`string` or `byte[]`).
LoadRawFile<T>	Loads raw file content synchronously (`string` or `byte[]`).

Unload & Release

Method	Description
UnloadRawFile	Unloads a single raw file (reference count -1; can force-unload).
ReleaseRawFiles	Force-releases the entire raw file cache.

GetRawFilePathAsync

public static async UniTask<string> GetRawFilePathAsync(string assetName)
public static async UniTask<string> GetRawFilePathAsync(string packageName, string assetName)

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Raw file asset name (Address; bundle only).

Returns

UniTask<string> — the local physical path of the raw file; null if loading fails or the file is not found.

Description

Gets the physical path of a raw file in the local cache for subsequent file access (FileStream / IO) or third-party plugins (e.g., video playback). Internally the file is preloaded to obtain the path and then unloaded once normally (other holders' reference counts are unaffected), so no extra reference is left afterwards.

Example

string videoPath = await AssetLoaders.GetRawFilePathAsync("OpeningVideo");
if (videoPath != null)
{
    // Hand the path to a VideoPlayer
    videoPlayer.url = videoPath;
}

GetRawFilePath

public static string GetRawFilePath(string assetName)
public static string GetRawFilePath(string packageName, string assetName)

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Raw file asset name (Address; bundle only).

Returns

string — the local physical path of the raw file; null if loading fails or the file is not found.

Description

Gets the physical path of a raw file synchronously. Behaves like GetRawFilePathAsync.

PreloadRawFileAsync

public static async UniTask PreloadRawFileAsync(string assetName, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT)
public static async UniTask PreloadRawFileAsync(string packageName, string assetName, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT)
public static async UniTask PreloadRawFileAsync(string[] assetNames, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT)
public static async UniTask PreloadRawFileAsync(string packageName, string[] assetNames, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT)

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Raw file asset name (Address; bundle only).
assetNames	`string[]`	Array of raw file asset names (batch preloading).
priority	`uint`	YooAsset async loading priority. Default: `0`
progression	`Progression`	Preloading progress callback. Default: `null`
maxRetryCount	`byte`	Maximum retry count on load failure. Default: `MAX_RETRY_COUNT` (`3`)

Returns

UniTask — an awaitable async operation.

Description

Loads raw files into the cache ahead of time, so later LoadRawFileAsync calls hit the cache directly. Preloading does not add a reference; files already in the cache are skipped.

PreloadRawFile

public static void PreloadRawFile(string assetName, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT)
public static void PreloadRawFile(string packageName, string assetName, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT)
public static void PreloadRawFile(string[] assetNames, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT)
public static void PreloadRawFile(string packageName, string[] assetNames, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT)

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Raw file asset name (Address; bundle only).
assetNames	`string[]`	Array of raw file asset names (batch preloading).
progression	`Progression`	Preloading progress callback. Default: `null`
maxRetryCount	`byte`	Maximum retry count on load failure. Default: `MAX_RETRY_COUNT` (`3`)

Description

Preloads raw files into the cache synchronously. Behaves like PreloadRawFileAsync.

LoadRawFileAsync<T>

public static async UniTask<T> LoadRawFileAsync<T>(string assetName, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT)
public static async UniTask<T> LoadRawFileAsync<T>(string packageName, string assetName, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT)

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Raw file asset name (Address; bundle only).
priority	`uint`	YooAsset async loading priority. Default: `0`
progression	`Progression`	Loading progress callback. Default: `null`
maxRetryCount	`byte`	Maximum retry count on load failure. Default: `MAX_RETRY_COUNT` (`3`)

Returns

UniTask<T> — the file content (reference count +1); default if loading fails.

Description

Loads raw file content asynchronously and converts it to the requested type.

Important The generic T only supports string (text content) and byte[] (byte data).

Example

// Read a Json config as text
string json = await AssetLoaders.LoadRawFileAsync<string>("GameConfig");

// Read binary data as bytes
byte[] bytes = await AssetLoaders.LoadRawFileAsync<byte[]>("DataTable");

// Unload when done
AssetLoaders.UnloadRawFile("GameConfig");

LoadRawFile<T>

public static T LoadRawFile<T>(string assetName, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT)
public static T LoadRawFile<T>(string packageName, string assetName, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT)

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Raw file asset name (Address; bundle only).
progression	`Progression`	Loading progress callback. Default: `null`
maxRetryCount	`byte`	Maximum retry count on load failure. Default: `MAX_RETRY_COUNT` (`3`)

Returns

T — the file content (reference count +1); default if loading fails.

Description

Loads raw file content synchronously. Behaves like LoadRawFileAsync (the generic T only supports string and byte[]).

UnloadRawFile

public static void UnloadRawFile(string assetName, bool forceUnload = false)

Parameters

Parameter	Type	Description
assetName	`string`	Raw file asset name.
forceUnload	`bool`	Whether to bypass reference counting and force-unload. Default: `false`

Description

Unloads a single raw file: decrements the reference count by 1; when the count reaches zero (or forceUnload = true) the file is actually released and removed from the cache.

ReleaseRawFiles

public static void ReleaseRawFiles()

Description

Force-releases the entire raw file cache (bypassing reference counting) and reclaims memory.

Important Make sure the files are no longer in use before releasing.

Group Loading (GroupCacher)

Tags loaded assets with a custom groupId (soft reference), designed for "load a whole level's/module's assets in batch, unload them in batch" scenarios. Loading behaves the same as the regular methods, with an extra layer of group bookkeeping:

On a successful group load, both the group record count and the underlying cache reference count are incremented by +1; preloading increments neither.
Unloading a group (UnloadAssets / UnloadRawFiles) decrements the underlying cache references once per recorded count, so assets shared with other groups (or regular loads) are not force-released while other references remain.

Method Overview

Cache Query

Method	Description
HasInCache	Checks whether an asset is recorded in the given group's cache.

Assets

Method	Description
PreloadAssetAsync<T>	Preloads assets asynchronously and records them in a group.
PreloadAsset<T>	Preloads assets synchronously and records them in a group.
LoadAssetAsync<T>	Loads an asset asynchronously and records it in a group.
LoadAsset<T>	Loads an asset synchronously and records it in a group.
InstantiateAssetAsync<T>	Loads an asset asynchronously, records it in a group, and instantiates it.
InstantiateAsset<T>	Loads an asset synchronously, records it in a group, and instantiates it.
UnloadAsset	Unloads a single asset from a group (group and cache references each -1).
UnloadAssets	Unloads all assets of a group (released by counting down).

Raw Files

Method	Description
PreloadRawFileAsync	Preloads raw files asynchronously and records them in a group.
PreloadRawFile	Preloads raw files synchronously and records them in a group.
LoadRawFileAsync<T>	Loads a raw file asynchronously and records it in a group.
LoadRawFile<T>	Loads a raw file synchronously and records it in a group.
UnloadRawFile	Unloads a single raw file from a group.
UnloadRawFiles	Unloads all raw files of a group.

HasInCache

public static bool HasInCache(int groupId, string assetName)

Parameters

Parameter	Type	Description
groupId	`int`	Group ID (user-defined).
assetName	`string`	Asset name (supports the `res#` prefix).

Returns

bool — whether the asset is recorded in the given group's cache.

Description

Checks whether the asset has been loaded/preloaded through the group and recorded under the given group.

PreloadAssetAsync<T> (Group)

public static async UniTask PreloadAssetAsync<T>(int groupId, string assetName, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static async UniTask PreloadAssetAsync<T>(int groupId, string packageName, string assetName, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static async UniTask PreloadAssetAsync<T>(int groupId, string[] assetNames, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static async UniTask PreloadAssetAsync<T>(int groupId, string packageName, string[] assetNames, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object

Parameters

Parameter	Type	Description
groupId	`int`	Group ID (user-defined).
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Asset name (bundle assets use their Address; supports the `res#` prefix).
assetNames	`string[]`	Array of asset names (batch preloading).
priority	`uint`	YooAsset async loading priority (bundle loading only). Default: `0`
progression	`Progression`	Preloading progress callback. Default: `null`
maxRetryCount	`byte`	Maximum retry count on load failure. Default: `MAX_RETRY_COUNT` (`3`)

Returns

UniTask — an awaitable async operation.

Description

Preloads assets into the cache and records them in the given group. Otherwise behaves like PreloadAssetAsync.

Example

const int LEVEL_GROUP = 101;

// Before the level starts, preload in batch and record them in the group
await AssetLoaders.PreloadAssetAsync<GameObject>(LEVEL_GROUP, new string[]
{
    "EnemyBoss",
    "LevelProps",
    "res#Prefabs/LevelEffect"
});

PreloadAsset<T> (Group)

public static void PreloadAsset<T>(int groupId, string assetName, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static void PreloadAsset<T>(int groupId, string packageName, string assetName, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static void PreloadAsset<T>(int groupId, string[] assetNames, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static void PreloadAsset<T>(int groupId, string packageName, string[] assetNames, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object

Parameters

Parameter	Type	Description
groupId	`int`	Group ID (user-defined).
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Asset name (bundle assets use their Address; supports the `res#` prefix).
assetNames	`string[]`	Array of asset names (batch preloading).
progression	`Progression`	Preloading progress callback. Default: `null`
maxRetryCount	`byte`	Maximum retry count on load failure. Default: `MAX_RETRY_COUNT` (`3`)

Description

Preloads assets synchronously and records them in a group. Behaves like PreloadAssetAsync (Group).

LoadAssetAsync<T> (Group)

public static async UniTask<T> LoadAssetAsync<T>(int groupId, string assetName, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static async UniTask<T> LoadAssetAsync<T>(int groupId, string packageName, string assetName, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object

Parameters

Parameter	Type	Description
groupId	`int`	Group ID (user-defined).
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Asset name (bundle assets use their Address; supports the `res#` prefix).
priority	`uint`	YooAsset async loading priority (bundle loading only). Default: `0`
progression	`Progression`	Loading progress callback. Default: `null`
maxRetryCount	`byte`	Maximum retry count on load failure. Default: `MAX_RETRY_COUNT` (`3`)

Returns

UniTask<T> — the loaded asset object (group record and cache reference each +1); null if loading fails.

Description

Loads an asset and records it in the given group. Otherwise behaves like LoadAssetAsync.

Example

const int LEVEL_GROUP = 101;

var bossPrefab = await AssetLoaders.LoadAssetAsync<GameObject>(LEVEL_GROUP, "EnemyBoss");

LoadAsset<T> (Group)

public static T LoadAsset<T>(int groupId, string assetName, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static T LoadAsset<T>(int groupId, string packageName, string assetName, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object

Parameters

Parameter	Type	Description
groupId	`int`	Group ID (user-defined).
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Asset name (bundle assets use their Address; supports the `res#` prefix).
progression	`Progression`	Loading progress callback. Default: `null`
maxRetryCount	`byte`	Maximum retry count on load failure. Default: `MAX_RETRY_COUNT` (`3`)

Returns

T — the loaded asset object (group record and cache reference each +1); null if loading fails.

Description

Loads an asset synchronously and records it in a group. Behaves like LoadAssetAsync (Group).

InstantiateAssetAsync<T> (Group)

public static async UniTask<T> InstantiateAssetAsync<T>(int groupId, string assetName, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static async UniTask<T> InstantiateAssetAsync<T>(int groupId, string packageName, string assetName, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static async UniTask<T> InstantiateAssetAsync<T>(int groupId, string assetName, Vector3 position, Quaternion rotation, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static async UniTask<T> InstantiateAssetAsync<T>(int groupId, string packageName, string assetName, Vector3 position, Quaternion rotation, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static async UniTask<T> InstantiateAssetAsync<T>(int groupId, string assetName, Vector3 position, Quaternion rotation, Transform parent, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static async UniTask<T> InstantiateAssetAsync<T>(int groupId, string packageName, string assetName, Vector3 position, Quaternion rotation, Transform parent, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static async UniTask<T> InstantiateAssetAsync<T>(int groupId, string assetName, Transform parent, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static async UniTask<T> InstantiateAssetAsync<T>(int groupId, string packageName, string assetName, Transform parent, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static async UniTask<T> InstantiateAssetAsync<T>(int groupId, string assetName, Transform parent, bool worldPositionStays, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static async UniTask<T> InstantiateAssetAsync<T>(int groupId, string packageName, string assetName, Transform parent, bool worldPositionStays, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object

Parameters

Parameter	Type	Description
groupId	`int`	Group ID (user-defined).
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Asset name (bundle assets use their Address; supports the `res#` prefix).
position	`Vector3`	Position of the instance.
rotation	`Quaternion`	Rotation of the instance.
parent	`Transform`	Parent node the instance is attached to.
worldPositionStays	`bool`	Whether to keep the world position when parenting.
priority	`uint`	YooAsset async loading priority (bundle loading only). Default: `0`
progression	`Progression`	Loading progress callback. Default: `null`
maxRetryCount	`byte`	Maximum retry count on load failure. Default: `MAX_RETRY_COUNT` (`3`)

Returns

UniTask<T> — the instantiated clone; null if loading fails (no instantiation is performed).

Description

Loads an asset, records it in the group, and instantiates it directly. Otherwise behaves like InstantiateAssetAsync.

Important Destroying the instance does not return the reference automatically — pair with UnloadAsset (Group), or unload the whole group with UnloadAssets at the end of the level.

InstantiateAsset<T> (Group)

public static T InstantiateAsset<T>(int groupId, string assetName, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static T InstantiateAsset<T>(int groupId, string packageName, string assetName, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static T InstantiateAsset<T>(int groupId, string assetName, Vector3 position, Quaternion rotation, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static T InstantiateAsset<T>(int groupId, string packageName, string assetName, Vector3 position, Quaternion rotation, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static T InstantiateAsset<T>(int groupId, string assetName, Vector3 position, Quaternion rotation, Transform parent, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static T InstantiateAsset<T>(int groupId, string packageName, string assetName, Vector3 position, Quaternion rotation, Transform parent, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static T InstantiateAsset<T>(int groupId, string assetName, Transform parent, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static T InstantiateAsset<T>(int groupId, string packageName, string assetName, Transform parent, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static T InstantiateAsset<T>(int groupId, string assetName, Transform parent, bool worldPositionStays, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object
public static T InstantiateAsset<T>(int groupId, string packageName, string assetName, Transform parent, bool worldPositionStays, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT) where T : UnityEngine.Object

Parameters

Parameter	Type	Description
groupId	`int`	Group ID (user-defined).
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Asset name (bundle assets use their Address; supports the `res#` prefix).
position	`Vector3`	Position of the instance.
rotation	`Quaternion`	Rotation of the instance.
parent	`Transform`	Parent node the instance is attached to.
worldPositionStays	`bool`	Whether to keep the world position when parenting.
progression	`Progression`	Loading progress callback. Default: `null`
maxRetryCount	`byte`	Maximum retry count on load failure. Default: `MAX_RETRY_COUNT` (`3`)

Returns

T — the instantiated clone; null if loading fails.

Description

Loads an asset synchronously, records it in the group, and instantiates it. Behaves like InstantiateAssetAsync (Group).

UnloadAsset (Group)

public static void UnloadAsset(int groupId, string assetName)

Parameters

Parameter	Type	Description
groupId	`int`	Group ID (user-defined).
assetName	`string`	Asset name (supports the `res#` prefix).

Description

Unloads a single asset from a group: the group record count and the underlying cache reference count are each decremented by -1. The group record is removed when its count reaches zero, and the asset itself is released when the cache reference count reaches zero.

Attention Group unloading always uses reference counting — there is no force-unload option.

UnloadAssets

public static void UnloadAssets(int groupId, LoadType loadType = LoadType.Any)

Parameters

Parameter	Type	Description
groupId	`int`	Group ID (user-defined).
loadType	`LoadType`	Release scope (`Any` / `Resources` / `Bundle`; see the LoadType enum). Default: `LoadType.Any`

Description

Unloads all asset records of a group: for each record, the underlying cache reference is decremented once per recorded count, and the group record is then removed.

Reminder Actual release still follows reference counting — assets shared with other groups (or regular loads) are not released while other references remain.

Example

const int LEVEL_GROUP = 101;

// At the end of the level, unload all assets of the group in one call
AssetLoaders.UnloadAssets(LEVEL_GROUP);

PreloadRawFileAsync (Group)

public static async UniTask PreloadRawFileAsync(int groupId, string assetName, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT)
public static async UniTask PreloadRawFileAsync(int groupId, string packageName, string assetName, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT)
public static async UniTask PreloadRawFileAsync(int groupId, string[] assetNames, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT)
public static async UniTask PreloadRawFileAsync(int groupId, string packageName, string[] assetNames, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT)

Parameters

Parameter	Type	Description
groupId	`int`	Group ID (user-defined).
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Raw file asset name (Address; bundle only).
assetNames	`string[]`	Array of raw file asset names (batch preloading).
priority	`uint`	YooAsset async loading priority. Default: `0`
progression	`Progression`	Preloading progress callback. Default: `null`
maxRetryCount	`byte`	Maximum retry count on load failure. Default: `MAX_RETRY_COUNT` (`3`)

Returns

UniTask — an awaitable async operation.

Description

Preloads raw files and records them in a group. Otherwise behaves like PreloadRawFileAsync (bundle only).

PreloadRawFile (Group)

public static void PreloadRawFile(int groupId, string assetName, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT)
public static void PreloadRawFile(int groupId, string packageName, string assetName, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT)
public static void PreloadRawFile(int groupId, string[] assetNames, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT)
public static void PreloadRawFile(int groupId, string packageName, string[] assetNames, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT)

Parameters

Parameter	Type	Description
groupId	`int`	Group ID (user-defined).
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Raw file asset name (Address; bundle only).
assetNames	`string[]`	Array of raw file asset names (batch preloading).
progression	`Progression`	Preloading progress callback. Default: `null`
maxRetryCount	`byte`	Maximum retry count on load failure. Default: `MAX_RETRY_COUNT` (`3`)

Description

Preloads raw files synchronously and records them in a group. Behaves like PreloadRawFileAsync (Group).

LoadRawFileAsync<T> (Group)

public static async UniTask<T> LoadRawFileAsync<T>(int groupId, string assetName, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT)
public static async UniTask<T> LoadRawFileAsync<T>(int groupId, string packageName, string assetName, uint priority = 0, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT)

Parameters

Parameter	Type	Description
groupId	`int`	Group ID (user-defined).
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Raw file asset name (Address; bundle only).
priority	`uint`	YooAsset async loading priority. Default: `0`
progression	`Progression`	Loading progress callback. Default: `null`
maxRetryCount	`byte`	Maximum retry count on load failure. Default: `MAX_RETRY_COUNT` (`3`)

Returns

UniTask<T> — the file content (group record and cache reference each +1); default if loading fails.

Description

Loads raw file content and records it in a group. Otherwise behaves like LoadRawFileAsync (the generic T only supports string and byte[]).

LoadRawFile<T> (Group)

public static T LoadRawFile<T>(int groupId, string assetName, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT)
public static T LoadRawFile<T>(int groupId, string packageName, string assetName, Progression progression = null, byte maxRetryCount = MAX_RETRY_COUNT)

Parameters

Parameter	Type	Description
groupId	`int`	Group ID (user-defined).
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Raw file asset name (Address; bundle only).
progression	`Progression`	Loading progress callback. Default: `null`
maxRetryCount	`byte`	Maximum retry count on load failure. Default: `MAX_RETRY_COUNT` (`3`)

Returns

T — the file content (group record and cache reference each +1); default if loading fails.

Description

Loads a raw file synchronously and records it in a group. Behaves like LoadRawFileAsync (Group).

UnloadRawFile (Group)

public static void UnloadRawFile(int groupId, string assetName)

Parameters

Parameter	Type	Description
groupId	`int`	Group ID (user-defined).
assetName	`string`	Raw file asset name.

Description

Unloads a single raw file from a group (soft-reference unload): the group record count and the underlying cache reference count are each decremented by -1. The file is actually released only when all references reach zero.

UnloadRawFiles

public static void UnloadRawFiles(int groupId)

Parameters

Parameter	Type	Description
groupId	`int`	Group ID (user-defined).

Description

Unloads all raw file records of a group: for each record, the underlying cache reference is decremented once per recorded count. Files shared with other groups are not released while other references remain.

Deprecated Methods

Attention The following methods are marked [System.Obsolete] and kept for compatibility only — use the replacements instead.

Deprecated method	Replacement
`ReleaseBundleScenes()`	ReleaseScenes
`ReleaseBundleRawFiles()`	ReleaseRawFiles
`ReleaseResourceAssets()`	ReleaseAssets
`ReleaseBundleAssets()`	ReleaseAssets
`ReleaseBundleRawFiles(int groupId)`	UnloadRawFiles
`ReleaseResourceAssets(int groupId)`	UnloadAssets
`ReleaseBundleAssets(int groupId)`	UnloadAssets

Coding Style wiki​

Quick Start​

General Rules​

Asset Name Prefix​

Package​

YooAsset Version Compatibility​

Reference Counting & Unloading​

Load Retry​

Progression Callback​

LoadType Enum​

Scene Loading​

Method Overview​

Scene Loading​

Scene Unloading​

LoadSceneAsync​

LoadScene​

LoadSingleSceneAsync​

LoadSingleScene​

LoadAdditiveSceneAsync​

LoadAdditiveScene​

UnloadScene​

ReleaseScenes​

Cache Query​

Method Overview​

HasInCache​

GetFromCache<T>​

Asset Loading​

Method Overview​

Preload​

Load​

Instantiate​

Unload & Release​

PreloadAssetAsync<T>​

PreloadAsset<T>​

LoadAssetAsync<T>​

LoadAsset<T>​

InstantiateAssetAsync<T>​

InstantiateAsset<T>​

UnloadAsset​

ReleaseAssets​

Raw File Loading​

Method Overview​

File Path​

Preload​

Load​

Unload & Release​

GetRawFilePathAsync​

GetRawFilePath​

PreloadRawFileAsync​

PreloadRawFile​

LoadRawFileAsync<T>​

LoadRawFile<T>​

UnloadRawFile​

ReleaseRawFiles​

Group Loading (GroupCacher)​

Method Overview​

Cache Query​

Assets​

Raw Files​

HasInCache​

PreloadAssetAsync<T> (Group)​

PreloadAsset<T> (Group)​

LoadAssetAsync<T> (Group)​

LoadAsset<T> (Group)​

InstantiateAssetAsync<T> (Group)​

InstantiateAsset<T> (Group)​

UnloadAsset (Group)​

UnloadAssets​

PreloadRawFileAsync (Group)​

PreloadRawFile (Group)​

LoadRawFileAsync<T> (Group)​

LoadRawFile<T> (Group)​

UnloadRawFile (Group)​

UnloadRawFiles​

Deprecated Methods​

Coding Style wiki

Quick Start

General Rules

Asset Name Prefix

Package

YooAsset Version Compatibility

Reference Counting & Unloading

Load Retry

Progression Callback

LoadType Enum

Scene Loading

Method Overview

Scene Loading

Scene Unloading

LoadSceneAsync

LoadScene

LoadSingleSceneAsync

LoadSingleScene

LoadAdditiveSceneAsync

LoadAdditiveScene

UnloadScene

ReleaseScenes

Cache Query

Method Overview

HasInCache

GetFromCache<T>

Asset Loading

Method Overview

Preload

Load

Instantiate

Unload & Release

PreloadAssetAsync<T>

PreloadAsset<T>

LoadAssetAsync<T>

LoadAsset<T>

InstantiateAssetAsync<T>

InstantiateAsset<T>

UnloadAsset

ReleaseAssets

Raw File Loading

Method Overview

File Path

Preload

Load

Unload & Release

GetRawFilePathAsync

GetRawFilePath

PreloadRawFileAsync

PreloadRawFile

LoadRawFileAsync<T>

LoadRawFile<T>

UnloadRawFile

ReleaseRawFiles

Group Loading (GroupCacher)

Method Overview

Cache Query

Assets

Raw Files

HasInCache

PreloadAssetAsync<T> (Group)

PreloadAsset<T> (Group)

LoadAssetAsync<T> (Group)

LoadAsset<T> (Group)

InstantiateAssetAsync<T> (Group)

InstantiateAsset<T> (Group)

UnloadAsset (Group)

UnloadAssets

PreloadRawFileAsync (Group)

PreloadRawFile (Group)

LoadRawFileAsync<T> (Group)

LoadRawFile<T> (Group)

UnloadRawFile (Group)

UnloadRawFiles

Deprecated Methods