Interface IUnityStageRuntimeAsync
Optional capability on top of IUnityStageRuntime: builds a stage prefab off the main thread's critical path so the cost lands across several frames instead of one, then swaps it in when the game is ready for it.
Instantiating a whole level is the single most expensive thing a game does outside loading, and doing it synchronously shows up as a dropped frame wherever it happens. Splitting it into prepare-then-commit lets a caller start the build while a results screen, cutscene, or loading overlay is up, and commit only once the build has actually finished.
Namespace: Serenity.Stage.Infrastructure.Interfaces
Assembly: Serenity.UnityStage.Infrastructure.dll
Syntax
public interface IUnityStageRuntimeAsyncRemarks
Deliberately a separate interface rather than new members on
IUnityStageRuntime: Serenity is consumed by projects that implement these
interfaces themselves, and adding a member to an existing one breaks every implementer.
Callers probe with as IUnityStageRuntimeAsync and fall back to the synchronous
InstantiateStagePrefab(GameObject) when the runtime does not offer it.
Why two phases and not one. A stage runtime holds one slot per extracted authoring component. Extracting into those slots the moment the build finishes would overwrite the wiring of the stage that is still being played if the caller is interrupted in between. Extraction therefore happens in CommitPreparedStage(), which makes the swap atomic from the caller's point of view.
The prepared stage is inert. It is built inactive and parented outside the live hierarchy, so nothing about it renders, ticks, or collides until it is committed. A caller that prepares a stage and never commits it owes a CancelPreparedStage() — an abandoned preparation is a whole level's worth of leaked objects.
Properties
HasPreparedStage
True when a prepared stage is built and waiting for CommitPreparedStage().
Declaration
bool HasPreparedStage { get; }Property Value
| Type | Description |
|---|---|
| bool |
IsPreparingStage
True while a preparation started by BeginPrepareStagePrefab(GameObject) is still running.
Declaration
bool IsPreparingStage { get; }Property Value
| Type | Description |
|---|---|
| bool |
Methods
BeginPrepareStagePrefab(GameObject)
Starts building stagePrefab in the background. Replaces any previous
preparation, cancelling and discarding it first. A null prefab clears the preparation
and does nothing else.
Declaration
void BeginPrepareStagePrefab(GameObject stagePrefab)Parameters
| Type | Name | Description |
|---|---|---|
| GameObject | stagePrefab |
CancelPreparedStage()
Abandons any in-flight or completed preparation and destroys whatever it produced. Idempotent, and safe to call when nothing is prepared.
Declaration
void CancelPreparedStage()CommitPreparedStage()
Activates the prepared stage, moves it into the live hierarchy, extracts its authoring components and adopts it as the current stage.
Declaration
GameObject CommitPreparedStage()Returns
| Type | Description |
|---|---|
| GameObject | The committed stage GameObject, or null when nothing was prepared or the preparation is still running — callers should fall back to the synchronous path on null. |