Experiences

An experience is one thing your game can be doing: the main menu, a game mode, a training map, a DLC pack's new round. It is a data asset that lists what it needs: game feature plugins, assets, data, input, UI, settings. When the game asks for an experience, Gantry loads those things in order and switches them on. When the game moves on, Gantry switches them off again, keeping anything the next experience also needs.

Gantry does not decide what an experience contains. There is no pawn data, ability set or game mode built in. Your game adds its own fields, and reads them once the experience is ready.

Making one

An experience is a data asset: Content Browser > Add > Gantry > Experience. Everything is set in the Details panel, and nothing compiles.

Property	What it is
Experience Tag	Its name for code, menus and other experiences: `Experience.Arena.Deathmatch`.
Display Name Override, Description	What a selection screen shows.
Stages	The steps it runs when it activates. See Activation and stages.
Data	Data assets that come with it: rules, a pawn's setup, a palette. They load before its stages run.
Payload	One object of your own, set up in place, for data that needs no asset.
Children	The experiences that sit under it in the tree.
Optional Dependencies, Attach To, Extends	How it relates to experiences it does not list. See below.
Metadata	Which game versions it works with. An experience that needs another version is listed as incompatible and never activates.

Each experience also has a guid, set when the asset is created. A tag can be renamed; the guid never changes, which is what save games and servers should store.

Your own fields

To give experiences fields of your own (a round length, a team count, a music track):

Make a Blueprint class of Gantry Experience Definition and add variables to it.
Create experiences of that class. Once such a class exists, the Add menu asks which class to use.
Read the values once the experience is ready: Wait For Experience Ready, then cast the experience to your class.

Set an experience's tag and its place in the tree (Children, Attach To) on each data asset, never on a Blueprint class's defaults: every experience of the class would share them. Validation warns when this happens.

For data that belongs to a system rather than to the experience (rules, a loadout), put a data asset in Data instead, and find it with Find Experience Data. The search starts from the most specific experience in the chain, so a child's data of a class overrides its parent's, without either naming the other.

The experience tree

Experiences form a tree. Its root is the project's one base experience, made with Content Browser > Add > Gantry > Base Experience and named in Project Settings > Plugins > Gantry Experience > Base Experience.

An experience can only activate if the tree knows it. There are four ways experiences relate:

Children: a parent lists what belongs under it. This is how the game's own content is organized. The base lists the main menu and each game mode; a game mode might list its variants. Activating a child activates its parents first.
Optional Dependencies: an experience uses another when it is installed. A present optional dependency activates first; an absent one is skipped, and the experience copes (Is Experience Active tells it which).
Attach To: side-loaded content names its own parent. A DLC pack or a mod cannot edit the game's assets to add itself to a Children list, so its experience names the parent it belongs under. Shipped content leaves Attach To empty.
Extends: an experience joins others whenever they run. A DLC pack that changes a game mode extends it: every time that mode activates, the pack's experience activates right after it. The mode never names the pack. An experience that extends something still needs a place in the tree: set Attach To as well, usually to the base experience.

When you activate an experience, Gantry works out its activation chain: the base, each parent down to the experience you asked for, its optional dependencies that are installed, and any experiences that extend one of them. They activate in that order, from the base down, and deactivate in reverse.

Installed or not

The base experience ships with the game, so its Children list is always readable, even for content the player has not installed. Gantry keeps each listed child's name and description on the parent, so a selection screen can show "Arena: not installed" for content that is not there. Get All Experience Info returns every experience in the tree with its availability:

Availability	Meaning
Available	Installed, compatible, and everything it needs is too. It can activate.
Not Installed	Listed, but its content is not on this machine.
Incompatible	Made for another engine or game version. The reason is included.
Missing Dependency	Installed, but a parent it needs is missing or unavailable.

Choosing which experience runs

A world starts with an experience when one is set. The first of these that names one wins:

The URL option ?Experience=<tag>, as in open Arena?Experience=Experience.Arena.Deathmatch.
The command line: -Experience=<tag>.
The map's entry in Project Settings > Plugins > Gantry Experience > Map Experiences.
The base experience's Default Experience.

A guid works anywhere a tag does. A game mode that sets an experience while it initializes wins over all of them. The log says which one chose.

At any time after that, Set Experience By Tag switches to another experience. The current one stays running until the new one is ready, so anything both use stays loaded across the switch.

Coming from Lyra

Gantry's experiences are Lyra's idea, made into data assets and opened up to side-loaded content.

Lyra	Gantry
An experience is a Blueprint class (`B_ShooterGame_Elimination`).	An experience is a data asset of Gantry Experience Definition, or of your Blueprint class of it.
Experience settings are class defaults.	Your fields on a Blueprint class of Gantry Experience Definition, filled in on each data asset.
Game features to enable, and actions.	Stages: Activate Game Features, Load Assets, or your own Blueprint stages.
Action Sets, composed into several experiences for shared setup.	A parent experience: the child is listed under it in Children, and the parent's stages run first.
`CallOrRegister_OnExperienceLoaded`, with high, normal and low priority.	Wait For Experience Ready, with the same three priorities.

One setting must change when you bring a Lyra project across. Lyra's asset manager rule for experiences has Has Blueprint Classes on, because Lyra's experiences are classes. Gantry's are data assets, so the rule must have it off, or the asset manager finds no experiences and a packaged game ships without them. Gantry logs an error at startup when it sees the rule on. Getting Started has the right rule.