UGantryExperienceSubsystem

#include "Experience/GantryExperienceSubsystem.h"

Runs one experience per world: works out its chain, runs its stages, and announces when it is ready.

Every game and Play In Editor world has one. Use it to switch experiences (Set Experience By Tag), to wait for the current one (Wait For Experience Ready), to ask what is running (Is Experience Active, Find Experience Data), and to list experiences for a menu (Get All Experience Info). Call it on the game thread only.

An experience belongs to its world. Travel to a new map and the old experience is gone, so anything that must outlive a map belongs on a game instance subsystem instead.

Choosing the startup experience

When a world begins play and nothing has set an experience, the first of these that names one wins:

• the URL option ?Experience=<tag>;
• the command line -Experience=<tag>;
• in Play In Editor, the developer setting Play In Editor Experience;
• the map's entry in Map Experiences, under Project Settings > Plugins > Gantry Experience;
• the base experience's Default Experience.

A guid works anywhere a tag does. A game mode that sets an experience during initialisation wins over all of them. The log names which source chose.

Multiplayer

Only the server chooses: a dedicated server, a listen server, or a standalone game. Clients never pick a startup experience, and they refuse Set Experience calls. Each client receives the server's choice through a UGantryExperienceStateComponent on the GameState (added for you), builds the same activation chain from its own content, and runs the stages itself. A client whose chain differs from the server's, or whose copy of a mod in the chain differs from the server's (another content id), refuses the experience with a reason.

Each stage's Net Execution says which machines run it. Every machine reaches Ready on its own; the server does not wait for clients.

Using your own subclass (C++)

Subclass UGantryExperienceSubsystem and name the subclass in Project Settings > Plugins > Gantry Experience > Experience Subsystem Class, or in DefaultGame.ini:

[/Script/GantryExperience.GantryExperienceSettings]
ExperienceSubsystemClass=/Script/MyGame.MyGameExperienceSubsystem

Gantry then creates only your class.

The experience this world would start with, and which source chose it (see Choosing the startup experience).

Activates nothing. Builds the experience tree if needed.

Ends the current experience, undoing its stages in reverse, and returns to state None.

During a switch, the incoming experience is undone before the outgoing one. Does nothing when no experience is set. Server only; on a server, clients clear too.

Every data object of a class the active chain brings, nearest first (see Find Experience Data).

Finds the data object of a class that the active experiences bring, preferring the most specific: a game mode's rules over the base's.

Gantry searches each experience's Data, then its Payload, starting from the last experience in activation order and working back to the base. Experiences that extend the requested one come after it, so their data wins over its data, and its data wins over its parents'.

An experience's Data loads just before its stages run. Asked earlier, data that is not in memory yet is passed over.

Identity tag of the experience with a given guid, building the tree if needed.

Typed accessor from any object with a world.

The definitions in the current activation chain, in activation order: the base first, then each parent, the requested experience, then whatever extends it.

Tags of every experience in the current activation chain: the base, each parent, the requested experience, and whichever optional dependencies and extending experiences joined.

Use it, or Is Experience Active, to branch on an optional dependency. For example, a game mode can show a DLC pack's extra button only while that pack's experience is active, without referencing content that may not be installed.

Every experience in the tree, for a selection screen, installed or not.

Sorted base first, then by depth and tag, so the order is the same on every machine. Builds the tree if needed.

The experience that was asked for, while it activates or once it is running.

Name of the stage currently running, for a loading screen.

Availability of one experience, building the tree if needed.

Everything known about one experience: names, guid, metadata, availability, place in the tree.

Works for experiences whose content is not installed. Builds the tree if needed.

Lifecycle state of this world's experience.

Every experience the tree knows about, installed or not.

Builds the tree if needed.

Why the most recent activation failed, for a screen that appears after the fact.

Stage index and total, for "step 2 of 5" reporting.

Whether this machine chooses experiences: standalone, listen server or dedicated server.

Throws away the experience tree, so the next activation or query builds it again.

Call it after adding or removing content while the game runs, such as mounting a DLC pack. The running experience is not changed. New content takes part from the next activation onward, never by joining an experience that is already running.

Whether the tagged experience is part of the current activation chain.

Whether every stage of the current experience has completed.

Runs the stage at CurrentStageIndex, skipping a null entry.

Split out from AdvanceStage so the Gantry.Experience.StageDelay development aid has something to schedule; without the split there is no seam to insert a timer into.

Activates this experience asset, like Set Experience By Tag, for callers holding a reference.

Activates the experience with this Experience Guid, for save games and servers that store guids.

An unknown guid fails like an unknown tag. Server only, like Set Experience By Tag.

Activates the experience with this tag, replacing the current one: for example, moving from the main menu to a game mode.

Gantry activates the whole activation chain: the base, each parent, the experience itself, its present optional dependencies, and whatever extends them. The experience must be in the experience tree, either listed by a parent or side-loaded with a parent that is present. Activation takes time; use Wait For Experience Ready to run code once it is done.

The old experience's stages are undone only once the new one is ready, so anything both use, such as a shared game feature plugin, stays active across the switch.

What happens when it cannot activate:

• While another activation is still Resolving or Loading, the call is ignored with a warning.
• When the tag cannot be activated and an experience is running, the running one stays. On Experience Failed and Get Last Failure Reason report why, and the state does not change.
• When the tag cannot be activated and nothing is running, the state becomes Failed.

Server only. On a client the call is refused with a warning; the server's choice reaches every client on its own.

FGantryOnExperienceReadyNative UGantryExperienceSubsystem::OnExperienceReadyNative_HighPriority

High tier of the native ready event, broadcast first, before OnExperienceReady.

FGantryOnExperienceReadyNative UGantryExperienceSubsystem::OnExperienceReadyNative

Normal tier of the native ready event, broadcast right after OnExperienceReady.

FGantryOnExperienceReadyNative UGantryExperienceSubsystem::OnExperienceReadyNative_LowPriority

Low tier of the native ready event, broadcast last, once every other listener has run.

static void UGantryExperienceSubsystem::AddReferencedObjects(UObject *InThis, FReferenceCollector &Collector)

Keeps the crawled tree's definitions alive for as long as the tree is in use.

static FOnAnyExperienceFailed & UGantryExperienceSubsystem::OnAnyExperienceFailed()

Signature of OnAnyExperienceFailed: the world, the experience (invalid for the tree), why.

Every world's experience failures in one place, for tools: whenever any world's OnExperienceFailed fires, and when a world's experience tree cannot be built. Native only; the editor shows them in its Gantry message log.

virtual bool UGantryExperienceSubsystem::ShouldCreateSubsystem(UObject *Outer) const override

Declines for every class except the one selected in UGantryExperienceSettings (Gantry's own when unset).

virtual void UGantryExperienceSubsystem::Initialize(FSubsystemCollectionBase &Collection) override

Logs which subsystem class is running this world.

virtual void UGantryExperienceSubsystem::Deinitialize() override

Clears any current experience, unwinding its stages, before the world goes away.

virtual bool UGantryExperienceSubsystem::DoesSupportWorldType(const EWorldType::Type WorldType) const override

Limits the subsystem to game and PIE worlds; editor and preview worlds get none.

virtual void UGantryExperienceSubsystem::OnWorldBeginPlay(UWorld &InWorld) override

On the authority, activates the startup experience (see ChooseStartupExperience) if nothing has asked for an experience yet.

Clients wait for the server's choice instead. The choice is made once the world's actors have had BeginPlay, so actors that register as component receivers there (the only place a Blueprint can) are already receivers when the experience's game features add components.

void UGantryExperienceSubsystem::ApplyReplicatedExperience(const FGantryReplicatedExperience &Decision)

Client side: applies the server's choice of experience, as received through the GameState component.

Builds the chain from this machine's own content and refuses, with a reason, when it differs from the server's (the reason names both chains) or when a mod in it has another content id than the server's (the reason names the mod). A decision that arrives while an activation is still running is held and applied once that one settles; one already applied is ignored.

const FGantryExperienceTree * UGantryExperienceSubsystem::GetExperienceTree() const

Read access to the crawled tree for advanced callers.

Null until first built.

void UGantryExperienceSubsystem::CallOrRegister_OnExperienceReady_HighPriority(FGantryOnExperienceReadyNative::FDelegate &&Delegate)

C++: runs a callback once the experience is ready, or immediately if it already is.

This one registers on the high priority tier, which fires first.

This is the call game code should use; in Blueprint, use Wait For Experience Ready. Binding OnExperienceReady directly can miss it: if the experience was ready before you bound, your callback never fires. A callback registered here runs once. To hear every activation, bind the OnExperienceReadyNative delegates instead.

void UGantryExperienceSubsystem::CallOrRegister_OnExperienceReady(FGantryOnExperienceReadyNative::FDelegate &&Delegate)

Normal tier.

See CallOrRegister_OnExperienceReady_HighPriority.

void UGantryExperienceSubsystem::CallOrRegister_OnExperienceReady_LowPriority(FGantryOnExperienceReadyNative::FDelegate &&Delegate)

Low tier, fired last.

See CallOrRegister_OnExperienceReady_HighPriority.