Skip to content

Activation and stages

When an experience activates, Gantry runs its stages: the steps that load and switch on what it needs. Stages run one at a time, in the order they are listed, and each one finishes before the next starts. A stage can take as long as it needs (a load, a fade, a countdown) without the others caring.

Across a whole activation chain, the base experience's stages run first and the requested experience's last. Each experience's Data assets load before its own stages run.

Stages Gantry ships

Stage What it does
Load Assets Loads a list of assets, as a tracked load a loading screen can show.
Activate Game Features Loads and switches on game feature plugins. A plugin two experiences share stays on when the game switches from one to the other.
Add Input Mappings Puts Enhanced Input mapping contexts on every local player while the experience is active.
Add UI Extensions Puts widgets or data in UI slots while the experience is active.
Add Settings Pages Gives every local player settings pages while the experience is active.

Every stage has Net Execution (which machines run it, see Multiplayer) and Disabled, which leaves it out without removing it from the list.

Writing a stage in Blueprint

  1. Create a Blueprint class of Gantry Experience Stage.
  2. Implement Begin Stage. Do the work, then call Finish Stage: at once, or after a Delay, an async load, anything.
  3. Implement End Stage to undo the work when the experience deactivates.
  4. Add the stage to an experience's Stages list.

Variables marked Instance Editable show up in the Stages list, so each experience configures its own copy. While it runs, a stage has a world, so world nodes (Spawn Actor, Delay, Get Game State) work without a context pin. Each activation runs a fresh copy of the stage, so it can keep state in its variables.

For something every local player should get, including players who join later in split screen, subclass Per Local Player Stage instead and implement On Local Player Added and On Local Player Removed.

In C++, override BeginStage (call StartStage first), call FinishStage when done, and override EndStage to undo, calling Super so a Blueprint subclass's End Stage still runs. Stages run on the game thread.

Knowing when it is ready

An experience is ready when every stage of its chain has finished. Game code that needs the experience should wait for that:

  • In Blueprint: Wait For Experience Ready. It fires once, as soon as the experience is ready, or at once if it already is. Binding to the subsystem's On Experience Ready event instead misses an experience that was ready before you bound.
  • In C++: CallOrRegister_OnExperienceReady, which behaves the same way.

Both take a priority: High fires before Normal, Normal before Low. Systems that others build on (a scoring system, a spawn manager) wait at High; ordinary gameplay at Normal; anything reacting to the finished world (an intro camera) at Low.

Priorities are not stages. A stage is part of loading, set per experience in its asset. A priority orders the code that runs after loading has finished.

Switching and failing

Set Experience By Tag switches to another experience. The outgoing experience keeps running until the incoming one is ready, and only then are its stages ended. So a game feature plugin both use stays on, and nothing is unloaded and loaded again in between.

While an activation is still loading, another request is ignored with a warning. A request that cannot resolve (an unknown tag, a missing dependency) is refused, and the running experience stays. On Experience Failed and Get Last Failure Reason say why. If nothing was running, the state becomes Failed.

For a loading screen, Get Current Stage Name and Get Stage Progress ("step 2 of 5") report where activation is. A stage that runs longer than Experience Stage Stall Warning Time (Project Settings > Plugins > Gantry Experience) gets a warning in the log naming it.