Version: v3

CoreFrames

Important Attention Reminder

Coding Style wiki

CoreFrames is the unified entry point (Facade) of the CoreFrame module. It exposes four groups of APIs through nested static classes — UIFrame (UI windows), SRFrame (scene resources), USFrame (Unity scenes), and CPFrame (clone prefabs) — covering preloading, showing, closing, hiding, loading, and unloading of interface objects and scenes, all wired into AssetLoader's reference counting.


Namespace	`OxGFrame.CoreFrame`
Type	`public static class`
Source	CoreFrames.cs

using OxGFrame.CoreFrame;

Reminder The managers of each subsystem (UIManager, SRManager, etc.) are created automatically on first use and persist across scenes (DontDestroyOnLoad) — no scene setup is required beforehand.

Attention UIFrame requires a Canvas object in the scene whose name matches UISettings.canvasName on the UI prefab. See the CoreFrame Introduction for setup details.

Quick Start

// Show a UI (data can be passed to the UI's OnShow)
var ui = await CoreFrames.UIFrame.Show("PlayerUI");

// Close the UI
CoreFrames.UIFrame.Close("PlayerUI");

// Show a scene resource (SR)
await CoreFrames.SRFrame.Show("BattleField");

// Load a scene in Single mode (no prefix = bundle scene, using its Address)
await CoreFrames.USFrame.LoadSingleSceneAsync("MainScene");

// Load a scene from Build Settings (build# prefix)
await CoreFrames.USFrame.LoadSingleSceneAsync("build#MainScene");

// Clone a prefab (CP); simply Destroy it when no longer needed
var cp = await CoreFrames.CPFrame.LoadWithCloneAsync<CPBase>("BulletCP");

General Rules

Name Prefix Resolution

CoreFrames has a built-in resolver that determines the loading source based on the name prefix:

Prefix	Applicable Subsystems	Description	Example
res#	UIFrame, SRFrame, CPFrame	Loads the asset from Unity's native Resources (by relative path under Resources).	`res#Prefabs/PlayerUI`
build#	USFrame	Loads the scene from the Scenes In Build list of Build Settings.	`build#MainScene`
None	All	Loads the asset from the Asset Bundle (YooAsset) by default (using its addressable name).	`PlayerUI`

Package

All 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 management.

Group (groupId)

UIFrame and SRFrame support multi-group management: every instance opened via Show records a groupId (e.g., lobby-group UIs, battle-group UIs), and batch operations (CloseAll, HideAll, RevealAll, CheckHasAnyHiding) filter their scope by groupId. The framework defines the following internal constants:

Constant	Value	Description
DEFAULT_GROUP_ID	`0`	The group id used by overloads that do not take a `groupId`.
DO_ALL_GROUPS	`-1`	Passing `-1` as `groupId` extends the operation to all groups (equivalent to calling the `...ForAllGroups` methods).

Progression Callback

The progression parameter of the loading methods is of type OxGFrame.AssetLoader.Progression:

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

progress: overall progress (0 to 1).
currentCount / totalCount: number of completed items and total items.

Close, Hide & Destroy

Close runs the regular closing flow (OnPreClose → OnClose); Hide merely deactivates the object and marks it hidden (triggering OnHide), after which Reveal restores it (triggering OnReveal). A closed object cannot be revealed.
Whether Close destroys the instance depends on: the caller passing forceDestroy, or the prefab having allowInstantiate (multi-instance) / onCloseAndDestroy (destroy on close) checked. When an instance is destroyed, the asset is automatically unloaded through AssetLoader (reference counting).
Objects with Exclude From Close All (whenCloseAllToSkip) / Exclude From Hide All (whenHideAllToSkip) checked on the prefab are skipped by CloseAll / HideAll; use the ...AndExcluded methods to include them as well.

CoreFrames.UIFrame

The unified UI window API. It manages all UI windows and supports Group multi-group management (e.g., lobby-group UIs, battle-group UIs), Stack management (automatic sorting-order control within a node), reverse switching (reverseChanges), and stack-by-stack closing (allowCloseStackByStack). UI instances are automatically attached to the matching node under the Canvas, based on canvasName and nodeType of the UISettings on the prefab.

Properties

Property	Type	Default	Description
ignoreTimeScale	`bool`	`false`	Whether the UI update timing ignores `Time.timeScale` (uses unscaled time instead).
enableUpdate	`bool`	`true`	Whether the UI `OnUpdate` polling is driven.
enableFixedUpdate	`bool`	`true`	Whether the UI `OnFixedUpdate` polling is driven.
enableLateUpdate	`bool`	`true`	Whether the UI `OnLateUpdate` polling is driven.

Reminder The old names enabledUpdate / enabledFixedUpdate / enabledLateUpdate remain as [Obsolete] forwards; prefer the new names.

Method Overview

Initialization & Canvas Environment

Method	Description
InitInstance	Initializes the `UIManager` singleton instance.
SetupAndCheckUICanvas	Finds the Canvas object by name, then sets up and checks the UICanvas environment.
GetUICanvas	Gets the `UICanvas` component by name.

State Queries

Method	Description
CheckIsShowing	Checks whether the given UI is showing.
CheckIsHiding	Checks whether the given UI is hidden (via Hide).
CheckHasAnyHiding	Checks whether any UI in the group is hidden.
CheckHasAnyHidingForAllGroups	Checks whether any UI in any group is hidden.
GetStackByStackCount	Gets the current size of the stack-by-stack close stack.

Component Access

Method	Description
GetComponent<T>	Gets the instance component of the given UI (top of the stack).
GetComponents<T>	Gets all instance components of the given UI.

Data Refresh

Method	Description
SendRefreshData	Sends a data refresh notification to specific UIs.
SendRefreshDataToAll	Broadcasts a data refresh notification to all UIs.

Preloading & Showing

Method	Description
Preload	Preloads UI assets into the cache.
Show	Loads and shows a UI, returning its `UIBase` instance (generic supported).

Closing

Method	Description
Close	Closes the given UI.
CloseAll	Closes all UIs in a group.
CloseAllForAllGroups	Closes all UIs across all groups.
CloseAllAndExcluded	Closes all UIs in a group, including those marked as excluded.
CloseAllAndExcludedForAllGroups	Closes all UIs across all groups, including those marked as excluded.
CloseStackByStack	Closes the top UI of the given Canvas stack by stack (LIFO).

Hiding & Revealing

Method	Description
Reveal	Re-displays a UI that was hidden via Hide.
RevealAll	Reveals all hidden UIs in a group.
RevealAllForAllGroups	Reveals all hidden UIs across all groups.
Hide	Hides the given UI (keeping its instance and state).
HideAll	Hides all UIs in a group.
HideAllForAllGroups	Hides all UIs across all groups.
HideAllAndExcluded	Hides all UIs in a group, including those marked as excluded.
HideAllAndExcludedForAllGroups	Hides all UIs across all groups, including those marked as excluded.

InitInstance

public static void InitInstance()

Description

Explicitly initializes the UIManager singleton instance. The manager object is created automatically and persists across scenes (DontDestroyOnLoad). It is recommended to call this once during game startup so the manager is ready ahead of time.

SetupAndCheckUICanvas

public static bool SetupAndCheckUICanvas(string canvasName)

Parameters

Parameter	Type	Description
canvasName	`string`	Canvas name (must match a `Canvas` object in the scene).

Returns

bool — true when the setup succeeds (or has already been done); false with an error log when no matching Canvas is found in the scene.

Description

Finds the Canvas object in the scene by name, then sets up and checks the UICanvas environment (automatically creating the UIRoot, the NodeType nodes, and the Mask / Freeze containers).

Reminder Show runs this flow automatically; you can also call it manually after a scene switch to prepare the UI environment ahead of time.

GetUICanvas

public static UICanvas GetUICanvas(string canvasName)

Parameters

Parameter	Type	Description
canvasName	`string`	Canvas name.

Returns

UICanvas — the UICanvas component matching the name; null if the environment has not been set up or no match is found.

Description

Gets a UICanvas that has been set up, giving further access to its uiRoot, UI nodes, and the Mask / Freeze managers.

CheckIsShowing

public static bool CheckIsShowing(string assetName)
public static bool CheckIsShowing(UIBase uiBase)

Parameters

Parameter	Type	Description
assetName	`string`	UI asset name.
uiBase	`UIBase`	UI instance component.

Returns

bool — true if showing; false if not found or not showing.

Description

Checks whether the given UI is showing. When queried by name, the state of the top instance of the UI's stack is used.

CheckIsHiding

public static bool CheckIsHiding(string assetName)
public static bool CheckIsHiding(UIBase uiBase)

Parameters

Parameter	Type	Description
assetName	`string`	UI asset name.
uiBase	`UIBase`	UI instance component.

Returns

bool — true if in the hidden (Hide) state; false if not found or not hidden.

Description

Checks whether the given UI is in the hidden state caused by Hide (the isHidden flag). A UI closed via Close does not count as hidden.

CheckHasAnyHiding

public static bool CheckHasAnyHiding()
public static bool CheckHasAnyHiding(int groupId)

Parameters

Parameter	Type	Description
groupId	`int`	Group id. Default: `0` (parameterless overload)

Returns

bool — true when any UI in the group is hidden.

Description

Checks whether any UI in the group is in the hidden state.

CheckHasAnyHidingForAllGroups

public static bool CheckHasAnyHidingForAllGroups()

Returns

bool — true when any UI in any group is hidden.

Description

Behaves like CheckHasAnyHiding, but checks all groups.

GetStackByStackCount

public static int GetStackByStackCount(string canvasName)
public static int GetStackByStackCount(int groupId, string canvasName)

Parameters

Parameter	Type	Description
groupId	`int`	Group id. Default: `0` (overloads without it)
canvasName	`string`	Canvas name.

Returns

int — the current size of the stack-by-stack close stack for that group + Canvas; 0 if not found.

Description

Gets the size of the stack-by-stack close stack. Only UIs with allowCloseStackByStack enabled are counted (pushed when opened via Show). Use together with CloseStackByStack.

GetComponent<T>

public static T GetComponent<T>(string assetName) where T : UIBase

Parameters

Parameter	Type	Description
assetName	`string`	UI asset name.

Returns

T — the top instance component of the UI's stack; null if not found.

Description

Gets the instance component of the given UI, castable to a subclass for advanced operations.

Example

var playerUI = CoreFrames.UIFrame.GetComponent<PlayerUI>("PlayerUI");
if (playerUI != null)
{
    // Perform advanced operations on the instance
}

GetComponents<T>

public static T[] GetComponents<T>(string assetName) where T : UIBase

Parameters

Parameter	Type	Description
assetName	`string`	UI asset name.

Returns

T[] — all instance components of the UI; an empty array if none is found.

Description

Gets all instance components of the given UI. Useful for batch access when multiple instances of a UI with allowInstantiate (multi-instance) enabled exist at once.

SendRefreshData

public static void SendRefreshData(RefreshInfo refreshInfo)
public static void SendRefreshData(RefreshInfo[] refreshInfos)

Parameters

Parameter	Type	Description
refreshInfo	`RefreshInfo`	Refresh info struct holding the target UI asset name and the data to pass: `new RefreshInfo(assetName, data)`.
refreshInfos	`RefreshInfo[]`	Array of refresh infos (notify multiple UIs in batch).

Description

Sends a refresh notification to all instances of the given UI, triggering their OnReceiveAndRefresh(data) (both showing and hidden instances receive it). Commonly used for language-switch refreshes and display refreshes after receiving server data (e.g., refreshing the money display after a top-up).

Example

// Tell PlayerUI to refresh the coin display
CoreFrames.UIFrame.SendRefreshData(new RefreshInfo("PlayerUI", newCoinAmount));

SendRefreshDataToAll

public static void SendRefreshDataToAll()
public static void SendRefreshDataToAll(object data)
public static void SendRefreshDataToAll(RefreshInfo[] specificRefreshInfos)
public static void SendRefreshDataToAll(object data, RefreshInfo[] specificRefreshInfos)

Parameters

Parameter	Type	Description
data	`object`	Shared data broadcast to all UIs. Default: `null` (notification only, no data)
specificRefreshInfos	`RefreshInfo[]`	Specific list. UIs on the list receive the data from their own `RefreshInfo`, while the rest receive the shared `data`.

Description

Broadcasts a refresh notification to all UIs, triggering OnReceiveAndRefresh on each instance. Commonly used to refresh every UI after a language switch.

Example

// After switching languages, tell all UIs to refresh their texts
CoreFrames.UIFrame.SendRefreshDataToAll();

Preload

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

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	UI asset name (bundle assets use their Address; supports the `res#` prefix).
assetNames	`string[]`	Array of UI asset names (batch preloading).
priority	`uint`	Asset loading priority. Default: `0`
progression	`Progression`	Loading progress callback. Default: `null`

Returns

UniTask — an awaitable async operation.

Description

Loads UI assets into the cache ahead of time (without showing them), so a later Show call can use them immediately without a loading delay.

Example

// Preload frequently used UIs in batch
await CoreFrames.UIFrame.Preload(new string[] { "PlayerUI", "SettingsUI" });

Show

public static async UniTask<UIBase> Show(string assetName, object data = null, string awaitingUIAssetName = null, uint priority = 0, Progression progression = null, Transform parent = null, float awaitingUIExtraDuration = 0f)
public static async UniTask<UIBase> Show(string packageName, string assetName, object data = null, string awaitingUIAssetName = null, uint priority = 0, Progression progression = null, Transform parent = null, float awaitingUIExtraDuration = 0f)
public static async UniTask<UIBase> Show(int groupId, string assetName, object data = null, string awaitingUIAssetName = null, uint priority = 0, Progression progression = null, Transform parent = null, float awaitingUIExtraDuration = 0f)
public static async UniTask<UIBase> Show(int groupId, string packageName, string assetName, object data = null, string awaitingUIAssetName = null, uint priority = 0, Progression progression = null, Transform parent = null, float awaitingUIExtraDuration = 0f)
public static async UniTask<T> Show<T>(string assetName, object data = null, string awaitingUIAssetName = null, uint priority = 0, Progression progression = null, Transform parent = null, float awaitingUIExtraDuration = 0f) where T : UIBase
public static async UniTask<T> Show<T>(string packageName, string assetName, object data = null, string awaitingUIAssetName = null, uint priority = 0, Progression progression = null, Transform parent = null, float awaitingUIExtraDuration = 0f) where T : UIBase
public static async UniTask<T> Show<T>(int groupId, string assetName, object data = null, string awaitingUIAssetName = null, uint priority = 0, Progression progression = null, Transform parent = null, float awaitingUIExtraDuration = 0f) where T : UIBase
public static async UniTask<T> Show<T>(int groupId, string packageName, string assetName, object data = null, string awaitingUIAssetName = null, uint priority = 0, Progression progression = null, Transform parent = null, float awaitingUIExtraDuration = 0f) where T : UIBase

Parameters

Parameter	Type	Description
groupId	`int`	Group id. Default: `0` (overloads without it)
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	UI asset name (bundle assets use their Address; supports the `res#` prefix).
data	`object`	Data passed to the UI's `OnShow(obj)`. Default: `null`
awaitingUIAssetName	`string`	Transition UI asset name. Shown before the main UI opens (e.g., a loading overlay) and closed automatically once the main UI has opened. Default: `null` (no transition UI)
priority	`uint`	Asset loading priority. Default: `0`
progression	`Progression`	Loading progress callback. Default: `null`
parent	`Transform`	Parent node to attach to. Default: `null` (attached automatically to the matching node under the UICanvas, based on `uiSettings.nodeType`)
awaitingUIExtraDuration	`float`	Extra time in seconds the transition UI stays visible. Default: `0f`

Returns

UniTask<UIBase> — the opened UI instance component (generic overloads return UniTask<T>); null with an error log when loading fails (asset not found).

Description

Loads and shows a UI, recording its groupId for batch-operation filtering. Opening triggers OnPreShow → OnShow in order.

Attention

If the same UI is already showing and allowInstantiate is not checked, it is not opened again — a warning is logged and the existing instance is returned.
When a UI with reverseChanges (reverse switching) enabled opens, the previous UI in the reverse stack of the same Canvas is hidden automatically; closing it restores the previous UI.

Example

// Open a UI and pass data
var ui = await CoreFrames.UIFrame.Show("PlayerUI", new PlayerData(100));

// Open generically to get the subclass directly
var playerUI = await CoreFrames.UIFrame.Show<PlayerUI>("PlayerUI");

// Open with a specific group and package
await CoreFrames.UIFrame.Show(1, "OtherPackage", "BattleUI");

// Show a transition UI first (staying an extra 0.5 seconds)
await CoreFrames.UIFrame.Show("LobbyUI", null, "LoadingUI", awaitingUIExtraDuration: 0.5f);

Close

public static void Close(string assetName, bool disableOnPreClose = false, bool forceDestroy = false)

Parameters

Parameter	Type	Description
assetName	`string`	UI asset name.
disableOnPreClose	`bool`	Whether to skip the `OnPreClose` callback. Default: `false`
forceDestroy	`bool`	Whether to destroy the instance forcibly. If not forced, the `allowInstantiate` / `onCloseAndDestroy` settings on the prefab decide. Default: `false`

Description

Closes the given UI (for multi-instance UIs, the top instance of the stack). Does nothing when the UI is not showing and forceDestroy is not passed. When instances are destroyed, the asset is unloaded accordingly (see Close, Hide & Destroy).

Example

// Regular close (the prefab settings decide whether to destroy)
CoreFrames.UIFrame.Close("PlayerUI");

// Force destroy + skip OnPreClose
CoreFrames.UIFrame.Close("PlayerUI", true, true);

CloseAll

public static void CloseAll(bool disableOnPreClose = false, bool forceDestroy = false, params string[] withoutAssetNames)
public static void CloseAll(int groupId, bool disableOnPreClose = false, bool forceDestroy = false, params string[] withoutAssetNames)

Parameters

Parameter	Type	Description
groupId	`int`	Group id. Default: `0` (overloads without it)
disableOnPreClose	`bool`	Whether to skip the `OnPreClose` callback. Default: `false`
forceDestroy	`bool`	Whether to destroy the instances forcibly. Default: `false`
withoutAssetNames	`params string[]`	Exclusion list. UIs on the list are not closed.

Description

Closes all UIs in the group (including every instance in each UI's stack).

Attention

UIs with Exclude From Close All (whenCloseAllToSkip) checked are skipped — use CloseAllAndExcluded instead.
UIs that are not showing are skipped (unless forceDestroy is passed or the UI has allowInstantiate checked).

Example

// Close all UIs in the default group, but keep MainMenuUI
CoreFrames.UIFrame.CloseAll(false, false, "MainMenuUI");

CloseAllForAllGroups

public static void CloseAllForAllGroups(bool disableOnPreClose = false, bool forceDestroy = false, params string[] withoutAssetNames)

Parameters

Parameter	Type	Description
disableOnPreClose	`bool`	Whether to skip the `OnPreClose` callback. Default: `false`
forceDestroy	`bool`	Whether to destroy the instances forcibly. Default: `false`
withoutAssetNames	`params string[]`	Exclusion list.

Description

Behaves like CloseAll, but applies to all groups.

CloseAllAndExcluded

public static void CloseAllAndExcluded(bool disableOnPreClose = false, bool forceDestroy = false, params string[] withoutAssetNames)
public static void CloseAllAndExcluded(int groupId, bool disableOnPreClose = false, bool forceDestroy = false, params string[] withoutAssetNames)

Parameters

Parameter	Type	Description
groupId	`int`	Group id. Default: `0` (overloads without it)
disableOnPreClose	`bool`	Whether to skip the `OnPreClose` callback. Default: `false`
forceDestroy	`bool`	Whether to destroy the instances forcibly. Default: `false`
withoutAssetNames	`params string[]`	Exclusion list (still effective).

Description

Behaves like CloseAll, but also closes UIs with Exclude From Close All (whenCloseAllToSkip) checked.

CloseAllAndExcludedForAllGroups

public static void CloseAllAndExcludedForAllGroups(bool disableOnPreClose = false, bool forceDestroy = false, params string[] withoutAssetNames)

Parameters

Parameter	Type	Description
disableOnPreClose	`bool`	Whether to skip the `OnPreClose` callback. Default: `false`
forceDestroy	`bool`	Whether to destroy the instances forcibly. Default: `false`
withoutAssetNames	`params string[]`	Exclusion list.

Description

Behaves like CloseAllAndExcluded, but applies to all groups.

CloseStackByStack

public static void CloseStackByStack(string canvasName, bool disableOnPreClose = false, bool forceDestroy = false)
public static void CloseStackByStack(int groupId, string canvasName, bool disableOnPreClose = false, bool forceDestroy = false)

Parameters

Parameter	Type	Description
groupId	`int`	Group id. Default: `0` (overloads without it)
canvasName	`string`	Canvas name.
disableOnPreClose	`bool`	Whether to skip the `OnPreClose` callback. Default: `false`
forceDestroy	`bool`	Whether to destroy the instance forcibly. Default: `false`

Description

Closes the topmost (most recently opened) UI in the stack-by-stack close stack of the given group + Canvas (LIFO). Only affects UIs with allowCloseStackByStack enabled — commonly used to implement back-key behavior that closes windows one layer at a time.

Example

// Back key: close the top UI layer by layer
if (CoreFrames.UIFrame.GetStackByStackCount("Canvas") > 0)
    CoreFrames.UIFrame.CloseStackByStack("Canvas");

Reveal

public static void Reveal(string assetName)

Parameters

Parameter	Type	Description
assetName	`string`	UI asset name.

Description

Re-displays a UI hidden via Hide, triggering OnReveal (not OnShow). Only works on hidden UIs (a UI closed via Close cannot be revealed); a warning is logged if the UI is already showing.

RevealAll

public static void RevealAll()
public static void RevealAll(int groupId)

Parameters

Parameter	Type	Description
groupId	`int`	Group id. Default: `0` (parameterless overload)

Description

Reveals all hidden UIs in the group.

RevealAllForAllGroups

public static void RevealAllForAllGroups()

Description

Behaves like RevealAll, but applies to all groups.

Hide

public static void Hide(string assetName)

Parameters

Parameter	Type	Description
assetName	`string`	UI asset name.

Description

Hides all instances of the given UI (only deactivating the objects and setting the isHidden flag, keeping instances and data state), triggering OnHide. The UI can then be restored via Reveal or Show.

Example

// Hide temporarily (state preserved)
CoreFrames.UIFrame.Hide("PlayerUI");

// Reveal again
CoreFrames.UIFrame.Reveal("PlayerUI");

HideAll

public static void HideAll(params string[] withoutAssetNames)
public static void HideAll(int groupId, params string[] withoutAssetNames)

Parameters

Parameter	Type	Description
groupId	`int`	Group id. Default: `0` (overloads without it)
withoutAssetNames	`params string[]`	Exclusion list. UIs on the list are not hidden.

Description

Hides all UIs in the group.

Attention UIs with Exclude From Hide All (whenHideAllToSkip) checked are skipped (unless the UI has reverseChanges enabled, in which case it is still hidden) — use HideAllAndExcluded instead.

HideAllForAllGroups

public static void HideAllForAllGroups(params string[] withoutAssetNames)

Parameters

Parameter	Type	Description
withoutAssetNames	`params string[]`	Exclusion list.

Description

Behaves like HideAll, but applies to all groups.

HideAllAndExcluded

public static void HideAllAndExcluded(params string[] withoutAssetNames)
public static void HideAllAndExcluded(int groupId, params string[] withoutAssetNames)

Parameters

Parameter	Type	Description
groupId	`int`	Group id. Default: `0` (overloads without it)
withoutAssetNames	`params string[]`	Exclusion list (still effective).

Description

Behaves like HideAll, but also hides UIs with Exclude From Hide All (whenHideAllToSkip) checked.

HideAllAndExcludedForAllGroups

public static void HideAllAndExcludedForAllGroups(params string[] withoutAssetNames)

Parameters

Parameter	Type	Description
withoutAssetNames	`params string[]`	Exclusion list.

Description

Behaves like HideAllAndExcluded, but applies to all groups.

CoreFrames.SRFrame

The unified Scene Resource API. It manages 3D resources in a scene (such as NPCs, buildings, effect objects, in-scene management components, an AudioListener, etc.). Its operation logic mirrors UIFrame (group management, Show / Close / Hide / Reveal, data refresh), but without the Canvas node and stack sorting mechanics. Instances are attached under the SRManager node by default.

Properties

Property	Type	Default	Description
ignoreTimeScale	`bool`	`false`	Whether the SR update timing ignores `Time.timeScale` (uses unscaled time instead).
enableUpdate	`bool`	`true`	Whether the SR `OnUpdate` polling is driven.
enableFixedUpdate	`bool`	`true`	Whether the SR `OnFixedUpdate` polling is driven.
enableLateUpdate	`bool`	`true`	Whether the SR `OnLateUpdate` polling is driven.

Reminder The old names enabledUpdate / enabledFixedUpdate / enabledLateUpdate remain as [Obsolete] forwards; prefer the new names.

Method Overview

Initialization

Method	Description
InitInstance	Initializes the `SRManager` singleton instance.

State Queries

Method	Description
CheckIsShowing	Checks whether the given SR is showing.
CheckIsHiding	Checks whether the given SR is hidden (via Hide).
CheckHasAnyHiding	Checks whether any SR in the group is hidden.
CheckHasAnyHidingForAllGroups	Checks whether any SR in any group is hidden.

Component Access

Method	Description
GetComponent<T>	Gets the instance component of the given SR (top of the stack).
GetComponents<T>	Gets all instance components of the given SR.

Data Refresh

Method	Description
SendRefreshData	Sends a data refresh notification to specific SRs.
SendRefreshDataToAll	Broadcasts a data refresh notification to all SRs.

Preloading & Showing

Method	Description
Preload	Preloads SR assets into the cache.
Show	Loads and shows an SR, returning its `SRBase` instance (generic supported).

Closing

Method	Description
Close	Closes the given SR.
CloseAll	Closes all SRs in a group.
CloseAllForAllGroups	Closes all SRs across all groups.
CloseAllAndExcluded	Closes all SRs in a group, including those marked as excluded.
CloseAllAndExcludedForAllGroups	Closes all SRs across all groups, including those marked as excluded.

Hiding & Revealing

Method	Description
Reveal	Re-displays an SR that was hidden via Hide.
RevealAll	Reveals all hidden SRs in a group.
RevealAllForAllGroups	Reveals all hidden SRs across all groups.
Hide	Hides the given SR (keeping its instance and state).
HideAll	Hides all SRs in a group.
HideAllForAllGroups	Hides all SRs across all groups.
HideAllAndExcluded	Hides all SRs in a group, including those marked as excluded.
HideAllAndExcludedForAllGroups	Hides all SRs across all groups, including those marked as excluded.

InitInstance

public static void InitInstance()

Description

Explicitly initializes the SRManager singleton instance. The manager object is created automatically and persists across scenes (DontDestroyOnLoad). It is recommended to call this once during game startup so the manager is ready ahead of time.

CheckIsShowing

public static bool CheckIsShowing(string assetName)
public static bool CheckIsShowing(SRBase srBase)

Parameters

Parameter	Type	Description
assetName	`string`	SR asset name.
srBase	`SRBase`	SR instance component.

Returns

bool — true if showing; false if not found or not showing.

Description

Checks whether the given SR is showing. When queried by name, the state of the top instance of the SR's stack is used.

CheckIsHiding

public static bool CheckIsHiding(string assetName)
public static bool CheckIsHiding(SRBase srBase)

Parameters

Parameter	Type	Description
assetName	`string`	SR asset name.
srBase	`SRBase`	SR instance component.

Returns

bool — true if in the hidden (Hide) state; false if not found or not hidden.

Description

Checks whether the given SR is in the hidden state caused by Hide (the isHidden flag). An SR closed via Close does not count as hidden.

CheckHasAnyHiding

public static bool CheckHasAnyHiding()
public static bool CheckHasAnyHiding(int groupId)

Parameters

Parameter	Type	Description
groupId	`int`	Group id. Default: `0` (parameterless overload)

Returns

bool — true when any SR in the group is hidden.

Description

Checks whether any SR in the group is in the hidden state.

CheckHasAnyHidingForAllGroups

public static bool CheckHasAnyHidingForAllGroups()

Returns

bool — true when any SR in any group is hidden.

Description

Behaves like CheckHasAnyHiding, but checks all groups.

GetComponent<T>

public static T GetComponent<T>(string assetName) where T : SRBase

Parameters

Parameter	Type	Description
assetName	`string`	SR asset name.

Returns

T — the top instance component of the SR's stack; null if not found.

Description

Gets the instance component of the given SR, castable to a subclass for advanced operations.

Example

var battleField = CoreFrames.SRFrame.GetComponent<BattleFieldSR>("BattleField");

GetComponents<T>

public static T[] GetComponents<T>(string assetName) where T : SRBase

Parameters

Parameter	Type	Description
assetName	`string`	SR asset name.

Returns

T[] — all instance components of the SR; an empty array if none is found.

Description

Gets all instance components of the given SR. Useful for batch access when multiple instances of an SR with allowInstantiate (multi-instance) enabled exist at once.

SendRefreshData

public static void SendRefreshData(RefreshInfo refreshInfo)
public static void SendRefreshData(RefreshInfo[] refreshInfos)

Parameters

Parameter	Type	Description
refreshInfo	`RefreshInfo`	Refresh info struct holding the target SR asset name and the data to pass: `new RefreshInfo(assetName, data)`.
refreshInfos	`RefreshInfo[]`	Array of refresh infos (notify multiple SRs in batch).

Description

Sends a refresh notification to all instances of the given SR, triggering their OnReceiveAndRefresh(data) (both showing and hidden instances receive it).

SendRefreshDataToAll

public static void SendRefreshDataToAll()
public static void SendRefreshDataToAll(object data)
public static void SendRefreshDataToAll(RefreshInfo[] specificRefreshInfos)
public static void SendRefreshDataToAll(object data, RefreshInfo[] specificRefreshInfos)

Parameters

Parameter	Type	Description
data	`object`	Shared data broadcast to all SRs. Default: `null` (notification only, no data)
specificRefreshInfos	`RefreshInfo[]`	Specific list. SRs on the list receive the data from their own `RefreshInfo`, while the rest receive the shared `data`.

Description

Broadcasts a refresh notification to all SRs, triggering OnReceiveAndRefresh on each instance.

Preload

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

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	SR asset name (bundle assets use their Address; supports the `res#` prefix).
assetNames	`string[]`	Array of SR asset names (batch preloading).
priority	`uint`	Asset loading priority. Default: `0`
progression	`Progression`	Loading progress callback. Default: `null`

Returns

UniTask — an awaitable async operation.

Description

Loads SR assets into the cache ahead of time (without showing them), so a later Show call can use them immediately without a loading delay, improving runtime performance.

Example

await CoreFrames.SRFrame.Preload("BattleField");

Show

public static async UniTask<SRBase> Show(string assetName, object data = null, string awaitingUIAssetName = null, uint priority = 0, Progression progression = null, Transform parent = null, float awaitingUIExtraDuration = 0f)
public static async UniTask<SRBase> Show(string packageName, string assetName, object data = null, string awaitingUIAssetName = null, uint priority = 0, Progression progression = null, Transform parent = null, float awaitingUIExtraDuration = 0f)
public static async UniTask<SRBase> Show(int groupId, string assetName, object data = null, string awaitingUIAssetName = null, uint priority = 0, Progression progression = null, Transform parent = null, float awaitingUIExtraDuration = 0f)
public static async UniTask<SRBase> Show(int groupId, string packageName, string assetName, object data = null, string awaitingUIAssetName = null, uint priority = 0, Progression progression = null, Transform parent = null, float awaitingUIExtraDuration = 0f)
public static async UniTask<T> Show<T>(string assetName, object data = null, string awaitingUIAssetName = null, uint priority = 0, Progression progression = null, Transform parent = null, float awaitingUIExtraDuration = 0f) where T : SRBase
public static async UniTask<T> Show<T>(string packageName, string assetName, object data = null, string awaitingUIAssetName = null, uint priority = 0, Progression progression = null, Transform parent = null, float awaitingUIExtraDuration = 0f) where T : SRBase
public static async UniTask<T> Show<T>(int groupId, string assetName, object data = null, string awaitingUIAssetName = null, uint priority = 0, Progression progression = null, Transform parent = null, float awaitingUIExtraDuration = 0f) where T : SRBase
public static async UniTask<T> Show<T>(int groupId, string packageName, string assetName, object data = null, string awaitingUIAssetName = null, uint priority = 0, Progression progression = null, Transform parent = null, float awaitingUIExtraDuration = 0f) where T : SRBase

Parameters

Parameter	Type	Description
groupId	`int`	Group id. Default: `0` (overloads without it)
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	SR asset name (bundle assets use their Address; supports the `res#` prefix).
data	`object`	Data passed to the SR's `OnShow(obj)`. Default: `null`
awaitingUIAssetName	`string`	Transition UI asset name (a UIFrame UI). Shown before the SR opens and closed automatically once the SR has opened. Default: `null` (no transition UI)
priority	`uint`	Asset loading priority. Default: `0`
progression	`Progression`	Loading progress callback. Default: `null`
parent	`Transform`	Parent node to attach to. Default: `null` (attached under the `SRManager` node)
awaitingUIExtraDuration	`float`	Extra time in seconds the transition UI stays visible. Default: `0f`

Returns

UniTask<SRBase> — the opened SR instance component (generic overloads return UniTask<T>); null with an error log when loading fails (asset not found).

Description

Loads and shows a scene resource, recording its groupId for batch-operation filtering. Opening triggers OnPreShow → OnShow in order.

Attention If the same SR is already showing and allowInstantiate is not checked, it is not opened again — a warning is logged and the existing instance is returned.

Example

// Show a scene resource
var sr = await CoreFrames.SRFrame.Show("BattleField");

// Open generically with a specific parent
var npc = await CoreFrames.SRFrame.Show<NpcSR>("VillageNpc", parent: npcRoot);

// Open with a specific group
await CoreFrames.SRFrame.Show(2, "BattleEffects");

Close

public static void Close(string assetName, bool disableOnPreClose = false, bool forceDestroy = false)

Parameters

Parameter	Type	Description
assetName	`string`	SR asset name.
disableOnPreClose	`bool`	Whether to skip the `OnPreClose` callback. Default: `false`
forceDestroy	`bool`	Whether to destroy the instance forcibly. If not forced, the `allowInstantiate` / `onCloseAndDestroy` settings on the prefab decide. Default: `false`

Description

Closes the given SR (for multi-instance SRs, the top instance of the stack). Does nothing when the SR is not showing and forceDestroy is not passed. When instances are destroyed, the asset is unloaded accordingly (see Close, Hide & Destroy).

Example

CoreFrames.SRFrame.Close("BattleField");

CloseAll

public static void CloseAll(bool disableOnPreClose = false, bool forceDestroy = false, params string[] withoutAssetNames)
public static void CloseAll(int groupId, bool disableOnPreClose = false, bool forceDestroy = false, params string[] withoutAssetNames)

Parameters

Parameter	Type	Description
groupId	`int`	Group id. Default: `0` (overloads without it)
disableOnPreClose	`bool`	Whether to skip the `OnPreClose` callback. Default: `false`
forceDestroy	`bool`	Whether to destroy the instances forcibly. Default: `false`
withoutAssetNames	`params string[]`	Exclusion list. SRs on the list are not closed.

Description

Closes all SRs in the group (including every instance in each SR's stack).

Attention

SRs with Exclude From Close All (whenCloseAllToSkip) checked are skipped — use CloseAllAndExcluded instead.
SRs that are not showing are skipped (unless forceDestroy is passed).

CloseAllForAllGroups

public static void CloseAllForAllGroups(bool disableOnPreClose = false, bool forceDestroy = false, params string[] withoutAssetNames)

Parameters

Parameter	Type	Description
disableOnPreClose	`bool`	Whether to skip the `OnPreClose` callback. Default: `false`
forceDestroy	`bool`	Whether to destroy the instances forcibly. Default: `false`
withoutAssetNames	`params string[]`	Exclusion list.

Description

Behaves like CloseAll, but applies to all groups.

CloseAllAndExcluded

public static void CloseAllAndExcluded(bool disableOnPreClose = false, bool forceDestroy = false, params string[] withoutAssetNames)
public static void CloseAllAndExcluded(int groupId, bool disableOnPreClose = false, bool forceDestroy = false, params string[] withoutAssetNames)

Parameters

Parameter	Type	Description
groupId	`int`	Group id. Default: `0` (overloads without it)
disableOnPreClose	`bool`	Whether to skip the `OnPreClose` callback. Default: `false`
forceDestroy	`bool`	Whether to destroy the instances forcibly. Default: `false`
withoutAssetNames	`params string[]`	Exclusion list (still effective).

Description

Behaves like CloseAll, but also closes SRs with Exclude From Close All (whenCloseAllToSkip) checked.

CloseAllAndExcludedForAllGroups

public static void CloseAllAndExcludedForAllGroups(bool disableOnPreClose = false, bool forceDestroy = false, params string[] withoutAssetNames)

Parameters

Parameter	Type	Description
disableOnPreClose	`bool`	Whether to skip the `OnPreClose` callback. Default: `false`
forceDestroy	`bool`	Whether to destroy the instances forcibly. Default: `false`
withoutAssetNames	`params string[]`	Exclusion list.

Description

Behaves like CloseAllAndExcluded, but applies to all groups.

Reveal

public static void Reveal(string assetName)

Parameters

Parameter	Type	Description
assetName	`string`	SR asset name.

Description

Re-displays an SR hidden via Hide, triggering OnReveal (not OnShow). Only works on hidden SRs (an SR closed via Close cannot be revealed); a warning is logged if the SR is already showing.

RevealAll

public static void RevealAll()
public static void RevealAll(int groupId)

Parameters

Parameter	Type	Description
groupId	`int`	Group id. Default: `0` (parameterless overload)

Description

Reveals all hidden SRs in the group.

RevealAllForAllGroups

public static void RevealAllForAllGroups()

Description

Behaves like RevealAll, but applies to all groups.

Hide

public static void Hide(string assetName)

Parameters

Parameter	Type	Description
assetName	`string`	SR asset name.

Description

Hides all instances of the given SR (only deactivating the objects and setting the isHidden flag, keeping instances and data state), triggering OnHide. The SR can then be restored via Reveal or Show.

Example

// Hide the scene resource temporarily (state preserved)
CoreFrames.SRFrame.Hide("BattleField");

// Reveal again
CoreFrames.SRFrame.Reveal("BattleField");

HideAll

public static void HideAll(params string[] withoutAssetNames)
public static void HideAll(int groupId, params string[] withoutAssetNames)

Parameters

Parameter	Type	Description
groupId	`int`	Group id. Default: `0` (overloads without it)
withoutAssetNames	`params string[]`	Exclusion list. SRs on the list are not hidden.

Description

Hides all SRs in the group.

Attention SRs with Exclude From Hide All (whenHideAllToSkip) checked are skipped — use HideAllAndExcluded instead.

HideAllForAllGroups

public static void HideAllForAllGroups(params string[] withoutAssetNames)

Parameters

Parameter	Type	Description
withoutAssetNames	`params string[]`	Exclusion list.

Description

Behaves like HideAll, but applies to all groups.

HideAllAndExcluded

public static void HideAllAndExcluded(params string[] withoutAssetNames)
public static void HideAllAndExcluded(int groupId, params string[] withoutAssetNames)

Parameters

Parameter	Type	Description
groupId	`int`	Group id. Default: `0` (overloads without it)
withoutAssetNames	`params string[]`	Exclusion list (still effective).

Description

Behaves like HideAll, but also hides SRs with Exclude From Hide All (whenHideAllToSkip) checked.

HideAllAndExcludedForAllGroups

public static void HideAllAndExcludedForAllGroups(params string[] withoutAssetNames)

Parameters

Parameter	Type	Description
withoutAssetNames	`params string[]`	Exclusion list.

Description

Behaves like HideAllAndExcluded, but applies to all groups.

CoreFrames.USFrame

The unified Unity Scene API. An enhanced scene management system that wraps Unity's native SceneManager and extends it with bundle scene support — Single / Additive multi-scene loading, combined main + sub scene loading, merged progress reporting, frame-sliced root-object activation, and scene unloading.

Reminder Scene names support the build# prefix: with the prefix, scenes load from Build Settings; without it, they load from the Asset Bundle (YooAsset) (see Name Prefix Resolution).

Method Overview

Initialization & Scene Queries

Method	Description
InitInstance	Initializes the `USManager` singleton instance.
SceneCount	Gets the number of currently loaded scenes.
GetActiveScene	Gets the current active scene.
GetSceneAt	Gets a loaded scene by index.
GetSceneByName	Gets a loaded scene by name.
GetSceneByBuildIndex	Gets a loaded scene by build index.
GetAllScenes	Gets all (or filtered) loaded scenes.

Scene Operations

Method	Description
CreateScene	Creates a new empty scene.
MergeScenes	Merges two scenes.
MoveGameObjectToScene	Moves a GameObject to the given scene.
MoveGameObjectToActiveScene	Moves a GameObject to the active scene.
SetActiveScene	Sets the active scene.
SetActiveSceneRootGameObjects	Sets the active state of a scene's root objects in batch.
SetActiveSceneRootGameObjectsAsync	Sets the active state of a scene's root objects in frame-sliced batches.

Scene Loading (Async)

Method	Description
LoadSingleSceneAsync	Loads a scene asynchronously in Single mode.
LoadAdditiveSceneAsync	Loads a scene asynchronously in Additive mode.
LoadMainAndSubScenesAsync	Loads one main scene plus multiple sub scenes at once (merged progress).
LoadSubScenesAsync	Loads multiple Additive sub scenes in batch (merged progress).
LoadSceneAsync	General-purpose async scene loading (explicit LoadSceneMode).

Scene Loading (Sync)

Method	Description
LoadSingleScene	Loads a scene synchronously in Single mode.
LoadAdditiveScene	Loads a scene synchronously in Additive mode.
LoadMainAndSubScenes	Loads one main scene plus multiple sub scenes at once (sync).
LoadSubScenes	Loads multiple Additive sub scenes in batch (sync).
LoadScene	General-purpose sync scene loading (explicit LoadSceneMode).

Unloading

Method	Description
Unload	Unloads scenes (by name or build index).

InitInstance

public static void InitInstance()

Description

Explicitly initializes the USManager singleton instance (a plain C# singleton, not a MonoBehaviour). It is recommended to call this once during game startup.

SceneCount

public static int SceneCount()

Returns

int — the number of currently loaded scenes (same as SceneManager.sceneCount).

Description

Gets the number of currently loaded scenes.

GetActiveScene

public static Scene GetActiveScene()

Returns

Scene — the current active scene (same as SceneManager.GetActiveScene()).

Description

Gets the current active scene.

GetSceneAt

public static Scene GetSceneAt(int index)

Parameters

Parameter	Type	Description
index	`int`	Index in the loaded-scene list (0 to SceneCount - 1).

Returns

Scene — the scene at the given index.

Description

Gets a loaded scene by index (same as SceneManager.GetSceneAt).

GetSceneByName

public static Scene GetSceneByName(string sceneName)

Parameters

Parameter	Type	Description
sceneName	`string`	Scene name.

Returns

Scene — the loaded scene matching the name; if not found, the returned Scene is invalid (IsValid() is false).

Description

Gets a loaded scene by name (same as SceneManager.GetSceneByName).

GetSceneByBuildIndex

public static Scene GetSceneByBuildIndex(int buildIndex)

Parameters

Parameter	Type	Description
buildIndex	`int`	Scene index in Build Settings.

Returns

Scene — the loaded scene with the given build index; if not loaded, the returned Scene is invalid.

Description

Gets a loaded scene by build index (same as SceneManager.GetSceneByBuildIndex).

GetAllScenes

public static Scene[] GetAllScenes(params string[] sceneNames)
public static Scene[] GetAllScenes(params int[] buildIndexes)

Parameters

Parameter	Type	Description
sceneNames	`params string[]`	Scene-name filter. When omitted, all loaded scenes are returned.
buildIndexes	`params int[]`	Build-index filter. When omitted, all loaded scenes are returned.

Returns

Scene[] — the loaded scenes matching the filter; an empty array if none matches.

Description

Gets all loaded scenes, optionally filtered by name or build index.

CreateScene

public static Scene CreateScene(string sceneName, CreateSceneParameters parameters)

Parameters

Parameter	Type	Description
sceneName	`string`	Name of the new scene.
parameters	`CreateSceneParameters`	Scene creation parameters (including `LocalPhysicsMode`).

Returns

Scene — the created empty scene.

Description

Creates a new empty scene at runtime (same as SceneManager.CreateScene).

MergeScenes

public static bool MergeScenes(Scene sourceScene, Scene targetScene)

Parameters

Parameter	Type	Description
sourceScene	`Scene`	Source scene (unloaded after the merge).
targetScene	`Scene`	Target scene (receives all objects of the source scene).

Returns

bool — true on success; false with an exception log when an exception occurs.

Description

Merges all GameObjects of the source scene into the target scene (same as SceneManager.MergeScenes).

MoveGameObjectToScene

public static bool MoveGameObjectToScene(GameObject go, Scene targetScene)

Parameters

Parameter	Type	Description
go	`GameObject`	Object to move (must be a scene root object).
targetScene	`Scene`	Target scene.

Returns

bool — true on success; false with an exception log when an exception occurs.

Description

Moves a GameObject to the given scene (same as SceneManager.MoveGameObjectToScene).

MoveGameObjectToActiveScene

public static bool MoveGameObjectToActiveScene(GameObject go)

Parameters

Parameter	Type	Description
go	`GameObject`	Object to move (must be a scene root object).

Returns

bool — true on success; false with an exception log when an exception occurs.

Description

Moves a GameObject to the current active scene.

SetActiveScene

public static bool SetActiveScene(int index)
public static bool SetActiveScene(string sceneName)
public static bool SetActiveScene(Scene scene)

Parameters

Parameter	Type	Description
index	`int`	Index in the loaded-scene list.
sceneName	`string`	Scene name.
scene	`Scene`	Scene handle.

Returns

bool — true on success (same as SceneManager.SetActiveScene).

Description

Sets the active scene. In a multi-scene Additive setup, newly spawned objects belong to the active scene.

Example

// After loading a sub scene, switch the active scene over
await CoreFrames.USFrame.LoadAdditiveSceneAsync("BattleScene");
CoreFrames.USFrame.SetActiveScene("BattleScene");

SetActiveSceneRootGameObjects

public static void SetActiveSceneRootGameObjects(string sceneName, bool active, params string[] withoutRootGameObjectNames)
public static void SetActiveSceneRootGameObjects(Scene scene, bool active, string[] withoutRootGameObjectNames = null)

Parameters

Parameter	Type	Description
sceneName	`string`	Scene name. When multiple scenes share the name, all of them are processed.
scene	`Scene`	Scene handle.
active	`bool`	The active state to set.
withoutRootGameObjectNames	`params string[]`	Exclusion list. Root objects on the list keep their state.

Description

Sets the active state of a scene's root objects in batch. Logs an error/warning and does nothing when the scene is invalid or not fully loaded. Commonly paired with scenes loaded with activeRootGameObjects: false, activating the content at the right moment.

SetActiveSceneRootGameObjectsAsync

public async static UniTask SetActiveSceneRootGameObjectsAsync(string sceneName, bool active, int framesInterval = 1, int activeObjectsPerInterval = 3, params string[] withoutRootGameObjectNames)
public async static UniTask SetActiveSceneRootGameObjectsAsync(Scene scene, bool active, int framesInterval = 1, int activeObjectsPerInterval = 3, params string[] withoutRootGameObjectNames)

Parameters

Parameter	Type	Description
sceneName	`string`	Scene name. When multiple scenes share the name, all of them are processed.
scene	`Scene`	Scene handle.
active	`bool`	The active state to set.
framesInterval	`int`	Number of frames to wait between batches. Default: `1`
activeObjectsPerInterval	`int`	Number of root objects processed per batch. Default: `3`
withoutRootGameObjectNames	`params string[]`	Exclusion list.

Returns

UniTask — an awaitable async operation.

Description

Sets the active state of a scene's root objects in frame-sliced batches (after every activeObjectsPerInterval objects, waits framesInterval frames), avoiding hitches caused by activating many objects in a single frame.

Example

// Activate 5 root objects every 2 frames for a smooth ramp-up
await CoreFrames.USFrame.SetActiveSceneRootGameObjectsAsync("BattleScene", true, 2, 5);

LoadSingleSceneAsync

public static async UniTask LoadSingleSceneAsync(string sceneName, Progression progression = null)
public static async UniTask<T> LoadSingleSceneAsync<T>(string sceneName, Progression progression = null) where T : class
public static async UniTask LoadSingleSceneAsync(string packageName, string sceneName, LocalPhysicsMode localPhysicsMode = LocalPhysicsMode.None, Progression progression = null)
public static async UniTask<T> LoadSingleSceneAsync<T>(string packageName, string sceneName, LocalPhysicsMode localPhysicsMode = LocalPhysicsMode.None, Progression progression = null) where T : class

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
sceneName	`string`	Scene name (supports the `build#` prefix).
localPhysicsMode	`LocalPhysicsMode`	Local physics mode for the scene. Default: `LocalPhysicsMode.None`
progression	`Progression`	Loading progress callback. Default: `null`

Returns

UniTask — an awaitable async operation. Generic overloads return UniTask<T>: an AsyncOperation for build scenes, a BundlePack for bundle scenes (cast via as T; null when the type does not match).

Description

Loads a scene asynchronously in Single mode (replacing the existing scenes).

Attention If a scene with the same name is already loaded, a warning is logged and it is not loaded again.

Example

// Load a bundle scene (by Address)
await CoreFrames.USFrame.LoadSingleSceneAsync("MainScene");

// Load a Build Settings scene and watch the progress
await CoreFrames.USFrame.LoadSingleSceneAsync("build#MainScene", (progress, current, total) =>
{
    Debug.Log($"Loading progress: {progress * 100}%");
});

LoadAdditiveSceneAsync

public static async UniTask LoadAdditiveSceneAsync(string sceneName, bool activateOnLoad = true, uint priority = 100, Progression progression = null)
public static async UniTask LoadAdditiveSceneAsync(string sceneName, LocalPhysicsMode localPhysicsMode = LocalPhysicsMode.None, bool activeRootGameObjects = true, bool activateOnLoad = true, uint priority = 100, Progression progression = null)
public static async UniTask<T> LoadAdditiveSceneAsync<T>(string sceneName, bool activateOnLoad = true, uint priority = 100, Progression progression = null) where T : class
public static async UniTask<T> LoadAdditiveSceneAsync<T>(string sceneName, LocalPhysicsMode localPhysicsMode = LocalPhysicsMode.None, bool activeRootGameObjects = true, bool activateOnLoad = true, uint priority = 100, Progression progression = null) where T : class
public static async UniTask LoadAdditiveSceneAsync(string packageName, string sceneName, bool activateOnLoad = true, uint priority = 100, Progression progression = null)
public static async UniTask LoadAdditiveSceneAsync(string packageName, string sceneName, LocalPhysicsMode localPhysicsMode = LocalPhysicsMode.None, bool activeRootGameObjects = true, bool activateOnLoad = true, uint priority = 100, Progression progression = null)
public static async UniTask<T> LoadAdditiveSceneAsync<T>(string packageName, string sceneName, bool activateOnLoad = true, uint priority = 100, Progression progression = null) where T : class
public static async UniTask<T> LoadAdditiveSceneAsync<T>(string packageName, string sceneName, LocalPhysicsMode localPhysicsMode = LocalPhysicsMode.None, bool activeRootGameObjects = true, bool activateOnLoad = true, uint priority = 100, Progression progression = null) where T : class

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
sceneName	`string`	Scene name (supports the `build#` prefix).
localPhysicsMode	`LocalPhysicsMode`	Local physics mode for the scene. Default: `LocalPhysicsMode.None`
activeRootGameObjects	`bool`	Whether to keep the scene's root objects active after loading. When `false`, all root objects are deactivated automatically after loading (they can be activated later via SetActiveSceneRootGameObjects). Default: `true`
activateOnLoad	`bool`	Whether the scene activates automatically when loaded (bundle scenes only). Default: `true`
priority	`uint`	Scene loading priority (bundle scenes only). Default: `100`
progression	`Progression`	Loading progress callback. Default: `null`

Returns

Description

Loads a scene asynchronously in Additive mode (without unloading existing scenes).

Example

// Load a sub scene additively
await CoreFrames.USFrame.LoadAdditiveSceneAsync("EnvironmentScene");

// Load without activating root objects, then activate them frame by frame later
await CoreFrames.USFrame.LoadAdditiveSceneAsync("HeavyScene", LocalPhysicsMode.None, false);
await CoreFrames.USFrame.SetActiveSceneRootGameObjectsAsync("HeavyScene", true);

LoadMainAndSubScenesAsync

public static async UniTask LoadMainAndSubScenesAsync(string singleSceneName, AdditiveSceneInfo[] additiveSceneInfos, uint priority = 100, Progression progression = null)
public static async UniTask LoadMainAndSubScenesAsync(string singleSceneName, LocalPhysicsMode localPhysicsMode, AdditiveSceneInfo[] additiveSceneInfos, uint priority = 100, Progression progression = null)
public static async UniTask LoadMainAndSubScenesAsync(string packageName, string singleSceneName, AdditiveSceneInfo[] additiveSceneInfos, uint priority = 100, Progression progression = null)
public static async UniTask LoadMainAndSubScenesAsync(string packageName, string singleSceneName, LocalPhysicsMode localPhysicsMode, AdditiveSceneInfo[] additiveSceneInfos, uint priority = 100, Progression progression = null)

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
singleSceneName	`string`	Main scene name (loaded in Single mode; supports the `build#` prefix).
localPhysicsMode	`LocalPhysicsMode`	Local physics mode for the main scene. Default: `LocalPhysicsMode.None` (overloads without it)
additiveSceneInfos	`AdditiveSceneInfo[]`	Sub-scene info array (loaded in Additive mode, in order).
priority	`uint`	Scene loading priority (incremented per sub scene; bundle scenes only). Default: `100`
progression	`Progression`	Loading progress callback (main + sub scenes merged into a single progress report). Default: `null`

AdditiveSceneInfo struct fields:

Field	Type	Description
sceneName	`string`	Sub-scene name (supports the `build#` prefix).
activeRootGameObjects	`bool`	Whether to keep the scene's root objects active after loading.
localPhysicsMode	`LocalPhysicsMode`	Local physics mode for the sub scene.

Returns

UniTask — an awaitable async operation.

Description

Loads one Single main scene plus multiple Additive sub scenes in one call, with progress merged into a single progression report (0 to 1).

Attention If the main scene is already loaded, a warning is logged and the whole flow is aborted (sub scenes are not loaded either).

Example

// Load the main scene + two sub scenes at once
await CoreFrames.USFrame.LoadMainAndSubScenesAsync(
    "BattleScene",
    new AdditiveSceneInfo[]
    {
        new AdditiveSceneInfo { sceneName = "EnvironmentScene", activeRootGameObjects = true },
        new AdditiveSceneInfo { sceneName = "LightingScene", activeRootGameObjects = true }
    },
    progression: (progress, current, total) => Debug.Log($"Total progress: {progress * 100}%")
);

LoadSubScenesAsync

public static async UniTask LoadSubScenesAsync(AdditiveSceneInfo[] additiveSceneInfos, uint priority = 100, Progression progression = null)
public static async UniTask LoadSubScenesAsync(string packageName, AdditiveSceneInfo[] additiveSceneInfos, uint priority = 100, Progression progression = null)

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
additiveSceneInfos	`AdditiveSceneInfo[]`	Sub-scene info array (see LoadMainAndSubScenesAsync for the fields).
priority	`uint`	Scene loading priority (incremented per sub scene; bundle scenes only). Default: `100`
progression	`Progression`	Loading progress callback (all sub scenes merged into a single progress report). Default: `null`

Returns

UniTask — an awaitable async operation.

Description

Loads multiple Additive sub scenes in batch (without a main scene), with merged progress reporting.

LoadSceneAsync

public static async UniTask LoadSceneAsync(string sceneName, LoadSceneMode loadSceneMode, bool activateOnLoad = true, uint priority = 100, Progression progression = null)
public static async UniTask LoadSceneAsync(string sceneName, LoadSceneMode loadSceneMode, LocalPhysicsMode localPhysicsMode = LocalPhysicsMode.None, bool activateOnLoad = true, uint priority = 100, Progression progression = null)
public static async UniTask<T> LoadSceneAsync<T>(string sceneName, LoadSceneMode loadSceneMode, bool activateOnLoad = true, uint priority = 100, Progression progression = null) where T : class
public static async UniTask<T> LoadSceneAsync<T>(string sceneName, LoadSceneMode loadSceneMode, LocalPhysicsMode localPhysicsMode = LocalPhysicsMode.None, bool activateOnLoad = true, uint priority = 100, Progression progression = null) where T : class
public static async UniTask LoadSceneAsync(string packageName, string sceneName, LoadSceneMode loadSceneMode, bool activateOnLoad = true, uint priority = 100, Progression progression = null)
public static async UniTask LoadSceneAsync(string packageName, string sceneName, LoadSceneMode loadSceneMode, LocalPhysicsMode localPhysicsMode = LocalPhysicsMode.None, bool activateOnLoad = true, uint priority = 100, Progression progression = null)
public static async UniTask<T> LoadSceneAsync<T>(string packageName, string sceneName, LoadSceneMode loadSceneMode, bool activateOnLoad = true, uint priority = 100, Progression progression = null) where T : class
public static async UniTask<T> LoadSceneAsync<T>(string packageName, string sceneName, LoadSceneMode loadSceneMode, LocalPhysicsMode localPhysicsMode = LocalPhysicsMode.None, bool activateOnLoad = true, uint priority = 100, Progression progression = null) where T : class
public static async UniTask<AsyncOperation> LoadSceneAsync(int buildIndex, LoadSceneMode loadSceneMode = LoadSceneMode.Single, Progression progression = null)
public static async UniTask<AsyncOperation> LoadSceneAsync(int buildIndex, 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.
sceneName	`string`	Scene name (supports the `build#` prefix).
buildIndex	`int`	Scene index in Build Settings (these overloads load from Build only).
loadSceneMode	`LoadSceneMode`	Load mode (`Single` / `Additive`). Default: `LoadSceneMode.Single` (buildIndex overloads)
localPhysicsMode	`LocalPhysicsMode`	Local physics mode for the scene. Default: `LocalPhysicsMode.None`
activateOnLoad	`bool`	Whether the scene activates automatically when loaded (bundle scenes only). Default: `true`
priority	`uint`	Scene loading priority (bundle scenes only). Default: `100`
progression	`Progression`	Loading progress callback. Default: `null`

Returns

UniTask — an awaitable async operation. Generic overloads return UniTask<T>: an AsyncOperation for build scenes, a BundlePack for bundle scenes; the buildIndex overloads return UniTask<AsyncOperation>.

Description

The general-purpose async scene loading method with an explicit LoadSceneMode — the generalized form of LoadSingleSceneAsync / LoadAdditiveSceneAsync.

Example

using UnityEngine.SceneManagement;

// Get the BundlePack of a bundle scene generically
var pack = await CoreFrames.USFrame.LoadSceneAsync<BundlePack>("BattleScene", LoadSceneMode.Additive);

// Load by build index
var op = await CoreFrames.USFrame.LoadSceneAsync(1, LoadSceneMode.Single);

LoadSingleScene

public static void LoadSingleScene(string sceneName, Progression progression = null)
public static void LoadSingleScene(string packageName, string sceneName, LocalPhysicsMode localPhysicsMode = LocalPhysicsMode.None, Progression progression = null)

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
sceneName	`string`	Scene name (supports the `build#` prefix).
localPhysicsMode	`LocalPhysicsMode`	Local physics mode for the scene. Default: `LocalPhysicsMode.None`
progression	`Progression`	Loading progress callback. Default: `null`

Description

Loads a scene synchronously in Single mode. Behaves like LoadSingleSceneAsync (a warning is logged and nothing happens if a scene with the same name is already loaded).

LoadAdditiveScene

public static void LoadAdditiveScene(string sceneName, Progression progression = null)
public static void LoadAdditiveScene(string sceneName, LocalPhysicsMode localPhysicsMode = LocalPhysicsMode.None, bool activeRootGameObjects = true, Progression progression = null)
public static void LoadAdditiveScene(string packageName, string sceneName, Progression progression = null)
public static void LoadAdditiveScene(string packageName, string sceneName, LocalPhysicsMode localPhysicsMode = LocalPhysicsMode.None, bool activeRootGameObjects = true, Progression progression = null)

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
sceneName	`string`	Scene name (supports the `build#` prefix).
localPhysicsMode	`LocalPhysicsMode`	Local physics mode for the scene. Default: `LocalPhysicsMode.None`
activeRootGameObjects	`bool`	Whether to keep the scene's root objects active after loading. Default: `true`
progression	`Progression`	Loading progress callback. Default: `null`

Description

Loads a scene synchronously in Additive mode. Behaves like LoadAdditiveSceneAsync.

LoadMainAndSubScenes

public static void LoadMainAndSubScenes(string singleSceneName, AdditiveSceneInfo[] additiveSceneInfos, Progression progression = null)
public static void LoadMainAndSubScenes(string singleSceneName, LocalPhysicsMode localPhysicsMode, AdditiveSceneInfo[] additiveSceneInfos, Progression progression = null)
public static void LoadMainAndSubScenes(string packageName, string singleSceneName, AdditiveSceneInfo[] additiveSceneInfos, Progression progression = null)
public static void LoadMainAndSubScenes(string packageName, string singleSceneName, LocalPhysicsMode localPhysicsMode, AdditiveSceneInfo[] additiveSceneInfos, Progression progression = null)

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
singleSceneName	`string`	Main scene name (loaded in Single mode; supports the `build#` prefix).
localPhysicsMode	`LocalPhysicsMode`	Local physics mode for the main scene. Default: `LocalPhysicsMode.None` (overloads without it)
additiveSceneInfos	`AdditiveSceneInfo[]`	Sub-scene info array (see LoadMainAndSubScenesAsync for the fields).
progression	`Progression`	Loading progress callback (merged report). Default: `null`

Description

The synchronous version of the combined main + sub scene loading. Behaves like LoadMainAndSubScenesAsync (a warning is logged and the flow aborts if the main scene is already loaded).

LoadSubScenes

public static void LoadSubScenes(AdditiveSceneInfo[] additiveSceneInfos, Progression progression = null)
public static void LoadSubScenes(string packageName, AdditiveSceneInfo[] additiveSceneInfos, Progression progression = null)

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
additiveSceneInfos	`AdditiveSceneInfo[]`	Sub-scene info array (see LoadMainAndSubScenesAsync for the fields).
progression	`Progression`	Loading progress callback (merged report). Default: `null`

Description

Loads multiple Additive sub scenes synchronously in batch. Behaves like LoadSubScenesAsync.

LoadScene

public static void LoadScene(string sceneName, LoadSceneMode loadSceneMode, Progression progression = null)
public static void LoadScene(string packageName, string sceneName, LoadSceneMode loadSceneMode, Progression progression = null)
public static void LoadScene(string packageName, string sceneName, LoadSceneMode loadSceneMode, LocalPhysicsMode localPhysicsMode = LocalPhysicsMode.None, Progression progression = null)
public static Scene LoadScene(int buildIndex, LoadSceneMode loadSceneMode = LoadSceneMode.Single, Progression progression = null)
public static Scene LoadScene(int buildIndex, 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.
sceneName	`string`	Scene name (supports the `build#` prefix).
buildIndex	`int`	Scene index in Build Settings (these overloads load from Build only).
loadSceneMode	`LoadSceneMode`	Load mode (`Single` / `Additive`). Default: `LoadSceneMode.Single` (buildIndex overloads)
localPhysicsMode	`LocalPhysicsMode`	Local physics mode for the scene. Default: `LocalPhysicsMode.None`
progression	`Progression`	Loading progress callback. Default: `null`

Returns

The name-based overloads return nothing; the buildIndex overloads return Scene — the loaded scene (default when a scene with the same name is already loaded in Single mode).

Description

The general-purpose synchronous scene loading method with an explicit LoadSceneMode.

Unload

public static void Unload(bool recursively, params string[] sceneNames)
public static void Unload(bool recursively, params int[] buildIndexes)

Parameters

Parameter	Type	Description
recursively	`bool`	When `true`, unloads all scenes with the same name; when `false`, only the most recently loaded one.
sceneNames	`params string[]`	Scene names (supports the `build#` prefix; without it, the unload targets bundle scenes).
buildIndexes	`params int[]`	Scene indexes in Build Settings (this overload unloads Build scenes only).

Description

Unloads the given scenes. Unloading bundle scenes goes through AssetLoader's reference counting; unloading build scenes uses SceneManager.UnloadSceneAsync.

Attention The last remaining scene cannot be unloaded (a warning is logged).

Example

// Unload the most recently loaded sub scene with this name
CoreFrames.USFrame.Unload(false, "EnvironmentScene");

// Unload all scenes with the same name (Build scenes)
CoreFrames.USFrame.Unload(true, "build#LightingScene");

CoreFrames.CPFrame

The unified Clone Prefab API. It is dedicated to managing small objects instantiated (cloned) from prefabs, such as drop items (first-aid kits, herbs, etc.), bullets, and UI template components (item icons, etc.). Their defining trait: when no longer needed, simply Destroy them — destroying an instance automatically unloads the asset through AssetLoader, keeping the reference count correct without any extra close call.

Method Overview

Initialization

Method	Description
InitInstance	Initializes the `CPManager` singleton instance.

Preloading

Method	Description
PreloadAsync	Preloads prefab assets into the cache asynchronously.
Preload	Preloads prefab assets into the cache synchronously.

Loading & Cloning

Method	Description
LoadWithCloneAsync<T>	Loads and clones a prefab asynchronously, returning a `T` instance.
LoadWithClone<T>	Loads and clones a prefab synchronously, returning a `T` instance.

InitInstance

public static void InitInstance()

Description

Explicitly initializes the CPManager singleton instance (a plain C# singleton, not a MonoBehaviour). It is recommended to call this once during game startup.

PreloadAsync

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

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Prefab asset name (bundle assets use their Address; supports the `res#` prefix).
assetNames	`string[]`	Array of prefab asset names (batch preloading).
priority	`uint`	Asset loading priority. Default: `0`
progression	`Progression`	Loading progress callback. Default: `null`

Returns

UniTask — an awaitable async operation.

Description

Loads prefab assets into the cache ahead of time (asset loading only — no instantiation), so a later LoadWithCloneAsync<T> call can use them immediately without a loading delay. The generic overloads let you specify the asset type to load (the non-generic overloads load as Object).

Example

// Preload the bullet prefab before entering battle
await CoreFrames.CPFrame.PreloadAsync("BulletCP");

// Preload in batch
await CoreFrames.CPFrame.PreloadAsync(new string[] { "BulletCP", "MedkitCP" });

Preload

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

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Prefab asset name (bundle assets use their Address; supports the `res#` prefix).
assetNames	`string[]`	Array of prefab asset names (batch preloading).
progression	`Progression`	Loading progress callback. Default: `null`

Description

The synchronous version of prefab preloading (without the priority parameter). Behaves like PreloadAsync.

LoadWithCloneAsync<T>

public static async UniTask<T> LoadWithCloneAsync<T>(string assetName, Transform parent = null, uint priority = 0, Progression progression = null) where T : CPBase, new()
public static async UniTask<T> LoadWithCloneAsync<T>(string packageName, string assetName, Transform parent = null, uint priority = 0, Progression progression = null) where T : CPBase, new()
public static async UniTask<T> LoadWithCloneAsync<T>(string assetName, Transform parent, bool worldPositionStays, uint priority = 0, Progression progression = null) where T : CPBase, new()
public static async UniTask<T> LoadWithCloneAsync<T>(string packageName, string assetName, Transform parent, bool worldPositionStays, uint priority = 0, Progression progression = null) where T : CPBase, new()
public static async UniTask<T> LoadWithCloneAsync<T>(string assetName, Vector3 position, Quaternion rotation, Transform parent = null, Vector3? scale = null, uint priority = 0, Progression progression = null) where T : CPBase, new()
public static async UniTask<T> LoadWithCloneAsync<T>(string packageName, string assetName, Vector3 position, Quaternion rotation, Transform parent = null, Vector3? scale = null, uint priority = 0, Progression progression = null) where T : CPBase, new()

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Prefab asset name (bundle assets use their Address; supports the `res#` prefix).
parent	`Transform`	Parent node to attach to. Default: `null`
worldPositionStays	`bool`	Whether to keep the world position when parenting (same semantics as Unity's `Instantiate`).
position	`Vector3`	Initial position of the instance.
rotation	`Quaternion`	Initial rotation of the instance.
scale	`Vector3?`	Initial scale of the instance. Default: `null` (keeps the prefab's original scale)
priority	`uint`	Asset loading priority. Default: `0`
progression	`Progression`	Loading progress callback. Default: `null`

Returns

UniTask<T> — the cloned instance component; null when loading fails (asset not found) or no T component exists on the instance.

Description

Loads a prefab and instantiates (clones) it asynchronously. T must be the CPBase component (or a subclass) attached to the prefab root. After instantiation, OnCreate → InitFirst (binding) → OnShow are triggered in order.

Attention

If the prefab root is active (true), OnShow is triggered automatically after cloning; if inactive, the instance stays deactivated and OnShow fires only after you call SetActive(true) yourself.
Every clone goes through the load counting, and the count is deducted automatically when the instance is destroyed.

Reminder When no longer needed, simply call Destroy(instance.gameObject) — the asset is unloaded automatically through AssetLoader.

Example

// Clone a bullet and attach it to the muzzle node
var bullet = await CoreFrames.CPFrame.LoadWithCloneAsync<BulletCP>("BulletCP", muzzle.transform);

// Clone a drop item at a specific position and rotation
var drop = await CoreFrames.CPFrame.LoadWithCloneAsync<DropItemCP>("MedkitCP", dropPos, Quaternion.identity);

// Done with it — just destroy (unloads automatically)
Object.Destroy(bullet.gameObject);

LoadWithClone<T>

public static T LoadWithClone<T>(string assetName, Transform parent = null, Progression progression = null) where T : CPBase, new()
public static T LoadWithClone<T>(string packageName, string assetName, Transform parent = null, Progression progression = null) where T : CPBase, new()
public static T LoadWithClone<T>(string assetName, Transform parent, bool worldPositionStays, Progression progression = null) where T : CPBase, new()
public static T LoadWithClone<T>(string packageName, string assetName, Transform parent, bool worldPositionStays, Progression progression = null) where T : CPBase, new()
public static T LoadWithClone<T>(string assetName, Vector3 position, Quaternion rotation, Transform parent = null, Vector3? scale = null, Progression progression = null) where T : CPBase, new()
public static T LoadWithClone<T>(string packageName, string assetName, Vector3 position, Quaternion rotation, Transform parent = null, Vector3? scale = null, Progression progression = null) where T : CPBase, new()

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Prefab asset name (bundle assets use their Address; supports the `res#` prefix).
parent	`Transform`	Parent node to attach to. Default: `null`
worldPositionStays	`bool`	Whether to keep the world position when parenting (same semantics as Unity's `Instantiate`).
position	`Vector3`	Initial position of the instance.
rotation	`Quaternion`	Initial rotation of the instance.
scale	`Vector3?`	Initial scale of the instance. Default: `null` (keeps the prefab's original scale)
progression	`Progression`	Loading progress callback. Default: `null`

Returns

T — the cloned instance component; null when loading fails (asset not found) or no T component exists on the instance.

Description

The synchronous version of load-and-clone (without the priority parameter). Behaves like LoadWithCloneAsync<T>. Consider calling Preload beforehand to avoid hitches from synchronous loading.

Example

// With the asset preloaded, clone an item icon synchronously
var icon = CoreFrames.CPFrame.LoadWithClone<ItemIconCP>("ItemIconCP", iconRoot);

Coding Style wiki​

Quick Start​

General Rules​

Name Prefix Resolution​

Package​

Group (groupId)​

Progression Callback​

Close, Hide & Destroy​

CoreFrames.UIFrame​

Properties​

Method Overview​

Initialization & Canvas Environment​

State Queries​

Component Access​

Data Refresh​

Preloading & Showing​

Closing​

Hiding & Revealing​

InitInstance​

SetupAndCheckUICanvas​

GetUICanvas​

CheckIsShowing​

CheckIsHiding​

CheckHasAnyHiding​

CheckHasAnyHidingForAllGroups​

GetStackByStackCount​

GetComponent<T>​

GetComponents<T>​

SendRefreshData​

SendRefreshDataToAll​

Preload​

Show​

Close​

CloseAll​

CloseAllForAllGroups​

CloseAllAndExcluded​

CloseAllAndExcludedForAllGroups​

CloseStackByStack​

Reveal​

RevealAll​

RevealAllForAllGroups​

Hide​

HideAll​

HideAllForAllGroups​

HideAllAndExcluded​

HideAllAndExcludedForAllGroups​

CoreFrames.SRFrame​

Properties​

Method Overview​

Initialization​

State Queries​

Component Access​

Data Refresh​

Preloading & Showing​

Closing​

Hiding & Revealing​

InitInstance​

CheckIsShowing​

CheckIsHiding​

CheckHasAnyHiding​

CheckHasAnyHidingForAllGroups​

GetComponent<T>​

GetComponents<T>​

SendRefreshData​

SendRefreshDataToAll​

Preload​

Show​

Close​

CloseAll​

CloseAllForAllGroups​

CloseAllAndExcluded​

CloseAllAndExcludedForAllGroups​

Reveal​

RevealAll​

RevealAllForAllGroups​

Hide​

HideAll​

HideAllForAllGroups​

HideAllAndExcluded​

HideAllAndExcludedForAllGroups​

Coding Style wiki

Quick Start

General Rules

Name Prefix Resolution

Package

Group (groupId)

Progression Callback

Close, Hide & Destroy

CoreFrames.UIFrame

Properties

Method Overview

Initialization & Canvas Environment

State Queries

Component Access

Data Refresh

Preloading & Showing

Closing

Hiding & Revealing

InitInstance

SetupAndCheckUICanvas

GetUICanvas

CheckIsShowing

CheckIsHiding

CheckHasAnyHiding

CheckHasAnyHidingForAllGroups

GetStackByStackCount

GetComponent<T>

GetComponents<T>

SendRefreshData

SendRefreshDataToAll

Preload

Show

Close

CloseAll

CloseAllForAllGroups

CloseAllAndExcluded

CloseAllAndExcludedForAllGroups

CloseStackByStack

Reveal

RevealAll

RevealAllForAllGroups

Hide

HideAll

HideAllForAllGroups

HideAllAndExcluded

HideAllAndExcludedForAllGroups

CoreFrames.SRFrame

Properties

Method Overview

Initialization

State Queries

Component Access

Data Refresh

Preloading & Showing

Closing

Hiding & Revealing

InitInstance

CheckIsShowing

CheckIsHiding

CheckHasAnyHiding

CheckHasAnyHidingForAllGroups

GetComponent<T>

GetComponents<T>

SendRefreshData

SendRefreshDataToAll

Preload

Show

Close

CloseAll

CloseAllForAllGroups

CloseAllAndExcluded

CloseAllAndExcludedForAllGroups

Reveal

RevealAll

RevealAllForAllGroups

Hide

HideAll

HideAllForAllGroups

HideAllAndExcluded

HideAllAndExcludedForAllGroups