UGantryExperienceDefinition
One thing your game can be doing, such as a main menu or a game mode, switched on in stages.
It lists what it needs (game feature plugins, assets, data, settings, UI) and Gantry loads and switches it on in order, one stage at a time, and off again when the game moves on. Gantry does not decide what an experience contains; your game adds its own fields and reads them once the experience is ready.
The experience tree
Every experience has a place in one experience tree. Its root is the project's base experience, a UGantryBaseExperienceDefinition. When you activate an experience, Gantry activates its activation chain: the base first, then each parent in turn, then the experience you asked for. A game mode listed under the base runs the base's stages first, then its own.
Four properties place an experience in the tree:
- Children. A parent names the experiences that belong under it. Being listed is what makes a shipped experience playable. Each experience can be listed by one parent only.
- Attach To. Side-loaded content, such as a DLC pack, cannot edit the game's assets, so it names its required parent here instead. Shipped content that is listed leaves Attach To empty; the tree refuses an experience that is both listed and attached.
- Optional Dependencies. Experiences this one uses when they are present. A present one activates before this experience. A missing one is skipped, so check Is Experience Active and branch.
- Extends. Experiences this one adds to. Whenever one of them activates, this one activates too, right after it. This is how a DLC pack or live content changes a game mode without the game naming it.
An experience that no parent lists and that sets no Attach To is missing its parent. It still shows in menus, with Availability Missing Dependency, but it cannot activate.
In Blueprint
An experience is a data asset: Content Browser > Add > Gantry > Experience. You edit it in the Details panel, and nothing compiles.
- Add your own fields. Make a Blueprint class of Gantry Experience Definition and add variables. Then create experiences of that class (once one exists, the Add menu asks which class) and fill in each one's values. To read them, use Wait For Experience Ready, then cast the experience to your class.
- Add your own behaviour. Make a Blueprint class of Gantry Experience Stage, implement Begin Stage, call Finish Stage when done, and add the stage to Stages. Game feature actions can be written in Blueprint the same way.
- Build a menu. Get All Experience Info and Get Experience Info describe every experience, installed or not: its name, description, availability and place in the tree.
Set Experience Tag, Children and Attach To on each data asset, never on a Blueprint class's defaults. Every experience made from that class would share them, and data validation reports it.
In C++
Subclass UGantryExperienceDefinition, add your own UPROPERTYs, and create data assets of the subclass. Read them from UGantryExperienceSubsystem::GetCurrentExperience, or from the definition passed to CallOrRegister_OnExperienceReady, cast to your class. Data assets that come with an experience can go in Data instead, found with FindExperienceData.
Coming from Lyra
Lyra's experiences are Blueprint classes (B_ShooterGame_Elimination), so Lyra's asset manager rule for them has Has Blueprint Classes on. Gantry's experiences are data assets, and that rule must be off. With it on, the asset manager finds no experiences and a packaged game ships without them. Gantry logs an error at startup while the rule is on.
To bring a Lyra experience across:
- Its settings, such as its pawn data, become fields on a Blueprint class of Gantry Experience Definition, filled in on a data asset. Data assets it points at can also go in Data.
- Its actions, action sets and game features become stages: Activate Game Features, Load Assets, or your own Blueprint stages.
- Blueprint class inheritance between experiences becomes the tree. List the experience under the parent it extended, and the parent's stages run first.
Wait For Experience Ready replaces Lyra's CallOrRegister_OnExperienceLoaded, with the same high, normal and low priority tiers.
- Inherits
UPrimaryDataAsset
Properties
| Property | Type | Default | Description |
|---|---|---|---|
ExperienceTag read-only | FGameplayTag | () | The tag that names this experience, used to activate it and to ask whether it is active. |
ExperienceGuid read-only | FGuid | 00000000000000000000000000000000 | A permanent ID for this experience, assigned when the asset is created and never edited. Duplicating the asset gives the copy a new one. Use it where a name must survive renames and moves: a save game, a server's record of what it ran, a content database. The asset path changes when you move the asset, and the Experience Tag can be renamed; the guid stays the same. |
DisplayNameOverride read-only | FText | Name shown on loading screens and menus. Empty uses the asset name. | |
Description read-only | FText | One or two lines for a store or selection screen. Shown even while this content is absent. | |
Metadata read-only | FGantryContentMetadata | Build information and the game versions this experience supports, as shipped. | |
Stages read-only | TArray<TObjectPtr<UGantryExperienceStage> > | The steps that switch this experience on, run in order during activation and undone in reverse when it ends. Each experience configures its own copies. | |
Payload read-only | TObjectPtr<UObject> | None | One object of your own, of any class, configured right here on the experience. Use it to attach your game's data to an experience without making a subclass. Find Experience Data searches it after this experience's Data. |
Data read-only | TArray<TSoftObjectPtr<UObject> > | Data assets that come with this experience, of whatever classes your game defines: a round's rules, a pawn's setup, a colour palette. They load whenever the experience is in the activation chain, as a tracked load before its own stages. While it is active, Find Experience Data finds them. The search starts at the last experience in the activation chain (one that extends the experience you activated comes after it) and works back toward the base, so a child that brings data of the same class as its parent overrides the parent's. Neither has to name the other. | |
Children read-only | TArray<TSoftObjectPtr<UGantryExperienceDefinition> > | The experiences that belong under this one, such as the game modes under a base experience. Being listed here is what makes a shipped experience playable. List only the assets: each child's tag, name, description and metadata are set on the child itself. An experience can be listed by one parent only; listing it twice stops the experience tree from building. A listed child does not have to be installed. A menu can still show it, as Not Installed. | |
ChildSnapshots read-only | TArray<FGantryExperienceEntry> | Copies of each listed child's name, description and metadata, so a menu can show a child that is not installed. Gantry writes these when the content is cooked; you never edit them, and the Details panel does not show them. Read them through Get Experience Info rather than directly. | |
OptionalDependencies read-only | FGameplayTagContainer | () | Experiences this one uses when they are present but does not need. They never stop it activating. A present, available optional dependency joins the activation chain and activates before this experience. A missing one is skipped. Your experience must cope without it: check Is Experience Active ( |
AttachTo read-only | FGameplayTagContainer | () | The required parents of side-loaded content, such as a DLC pack, which no shipped asset lists. Shipped content leaves this empty: it gets its parent from the experience that lists it in Children. Side-loaded content may name more than one parent, for a patch that needs two experiences at once ("requires A and B"). Every parent named here must be present and available; otherwise this experience is missing its parent and cannot activate. |
Extends read-only | FGameplayTagContainer | () | Experiences this one adds to: whenever one of them is in an activation chain, this one joins the chain too, right after it. This is how added content, such as a DLC pack, changes a game without the game naming it. A crate restyle extends the game mode that has crates, and every time that mode activates, the restyle comes with it. The game provides the hooks, such as actors registered with the Game Framework Component Manager or data a component reads; the extending experience uses them. An extending experience that is unavailable (incompatible, or missing its parent) is skipped and never stops the chain. When it does join, its own required parents join with it. Extends is not a parent. Side-loaded content that extends something still needs a place in the tree: set Attach To as well, usually to the base experience's tag. |
bIsTreeRoot | bool | False | True on the base experience, so the editor hides Optional Dependencies, Attach To and Extends. The root cannot have dependencies. An optional dependency of the root would point at its own descendant (a cycle) or at side-loaded content, and an attachment contradicts being the root. Set by |
Functions
GetDisplayName
Name shown on loading screens and menus.
| Pin | Type | Direction | Description |
|---|---|---|---|
| Return Value | FText | out | DisplayNameOverride, or the asset name when that is empty. |
C++
Public C++ members that Blueprint does not see.
ExperienceTagRegistryKey
const FName Registry tag name under which ExperienceTag is mirrored, for scan-without-load.
ExperienceGuidRegistryKey
const FName Registry tag name under which ExperienceGuid is mirrored.
UGantryExperienceDefinition
Default construction.
A new asset's ExperienceGuid is assigned in PostInitProperties.
GetPrimaryAssetId
virtual FPrimaryAssetId Returns GetExperienceAssetType() plus the asset name; the class default object has none.
GetAssetRegistryTags
virtual void Writes Metadata, ExperienceTag and ExperienceGuid to registry tags for load-free reads.
PostInitProperties
virtual void In the editor, gives a new instance without an ExperienceGuid a fresh one.
PostDuplicate
virtual void Gives a duplicated asset a new ExperienceGuid; PIE duplication keeps the original.
PreSave
virtual void When cooking, stamps Metadata and rebuilds ChildSnapshots; other saves do neither.
IsDataValid
virtual EDataValidationResult Checks this asset alone: tag set, no empty stages or child entries, no self-references.
GetExperienceAssetType
virtual FPrimaryAssetType Primary asset type.
Override in a subclass family to group them separately.
AppendActiveStages
void Appends this definition's own enabled stages, in order.
Chain assembly lives in the tree.
FindChildSnapshot
const FGantryExperienceEntry * Snapshot row for a listed child, or null when none was cooked in.
RebuildChildSnapshots
void Regenerates ChildSnapshots by loading every listed child.
Runs during cook saves.
OwningPluginFromPath
static FString Game feature plugin a package path belongs to; empty for /Game/ content.