Game phases
Every game instance knows its phase: Boot while it starts, Menu in menus, Loading while a level loads, InGame while the game is played. Every plugin reads the phase and hears every change with Pulse Foundation alone, so a plugin can pause its notifications while a level loads or update the status of a player when the game starts, without knowing the menus of the game.
The phase is a gameplay tag below Pulse.Phase:
| Phase | Tag | When |
|---|---|---|
| Boot | Pulse.Phase.Boot | The game instance starts, until its first world is ready |
| Menu | Pulse.Phase.Menu | Menus outside of a game (main menu, menu maps) |
| Splash, Title | Pulse.Phase.Menu.Splash, Pulse.Phase.Menu.Title | The splash screens and the title screen of PulseGameplay’s frontend |
| Loading | Pulse.Phase.Loading | A level loads; ends when no loading hold is left |
| InGame | Pulse.Phase.InGame | The game is played |
Games add phases of their own below these tags without C++ (Project Settings > Gameplay Tags), for example Pulse.Phase.InGame.Cutscene. A sub-phase counts as its parent: in Menu.Title the game is also in Menu.
Read the phase
UPulseGamePhaseSubsystem (game instance, Phase/PulseGamePhaseSubsystem.h) holds the phase:
- Get Phase, Get Previous Phase, Get Seconds In Phase (real seconds since the last change).
- Is In Phase (
Exactoff: a sub-phase counts), and in any Blueprint Get Game Phase and Is In Game Phase. - Wait For Game Phase: an async node that runs Reached once the game is in the phase, at once when it already is.
if (UPulseGamePhaseSubsystem* phases = UPulseGamePhaseSubsystem::Get(this))
{
if (phases->IsInPhase(Pulse::Foundation::Tags::Phase_InGame))
{
// The game is played
}
}
React to changes
Every change goes out three ways, each with the phase before (From), the phase now (To) and the seconds spent in the phase before (FPulseGamePhaseMessage):
- the native event
OnPhaseChangedNative, - the Blueprint event On Phase Changed,
- the channel
Pulse.Message.Phase.Changedof the message bus, with the new phase in the tags of the context.
phases->OnPhaseChangedNative.AddUObject(this, &UMyNotifications::HandlePhaseChanged);
void UMyNotifications::HandlePhaseChanged(const FPulseGamePhaseMessage& InMessage)
{
bPaused = Pulse::Phase::IsLoadingPhase(InMessage.To);
}
Who sets the phase
One phase source leads the main phases. It is a provider (UPulseGamePhaseSource), so a game exchanges it in C++ or Blueprint like any other Pulse backend:
| Source | When | How it sets the phase |
|---|---|---|
Default (UPulseGamePhaseSource) | Without PulseGameplay’s frontend | Boot at the start, Loading when a level change begins, then Menu for the maps in Menu Maps of the settings, else InGame |
| PulseGameplay frontend | While the frontend is on (it sets itself as the source) | Its own flow: Menu.Splash, Menu.Title, Menu, Loading, InGame |
| A source of the game | A game with a flow of its own | A class in Game Phase Source of the settings, or Set Phase Source at runtime |
A source of your own derives from UPulseGamePhaseSource and overrides On Level Travel Started (a map starts to load, or a seamless travel starts) and On World Ready (a world of the game instance begins play; the transition map of a seamless travel is left out). Leave them empty and call Set Phase where your flow changes. Set Phase Source, Set Phase Source Class and Reset Phase Source on the subsystem exchange the source at runtime; with no source the phase changes only through Set Phase.
Besides the source, a game may set sub-phases of the current phase itself with Set Phase on the subsystem (InGame.Cutscene while InGame) and set the main phase again when it ends. The next change of the source ends a sub-phase too.
Loading and loading holds
Boot and Loading last until no loading hold is left. A change that leaves them (to Menu or InGame) waits:
- at least one frame, so holds that are added when the new world begins play (a save that loads) count too,
- then until the last hold is removed (Get Waiting Phase names the phase that waits),
- at most Maximum Loading Wait of the settings (60 seconds by default, 0 waits forever); then the phase changes with a warning that names the holds.
A loading screen, the game’s own or the frontend’s, shows exactly as long as the phase is Loading. A later Set Phase replaces the waiting phase; Boot or Loading ends the wait. A hold outside of Boot and Loading (a reload while playing) does not change the phase. A source whose loading screen waits for the holds itself turns Wait For Loading Holds off (the frontend does, it has its own minimum and maximum time), and SetPhase(Phase, false) changes at once.
Network, split screen, Play in Editor
The phase belongs to the game instance of a machine and is not replicated: a client may still load while the others play.
- Split screen: one phase for all local players of a game instance.
- Play in Editor: every window has its own phase; the first world of a window begins play without a level change, so it goes from Boot straight to Menu or InGame. The editor itself has no phase.
- Dedicated server: Boot, then Loading and InGame; the default source never enters Menu there.
Match phases of a game mode (warm-up, round, end) are state of the server that replicates with the game state. They belong to the game, not to the game phase.
Settings
Project Settings > Pulse > Foundation, category Game Phases:
| Setting | Default | Description |
|---|---|---|
GamePhaseSource | UPulseGamePhaseSource | Leads the phases; the default follows the level changes and the Menu Maps. None: the phases change only through Set Phase. |
MenuMaps | empty | Maps of menus: the default source enters Menu in them instead of InGame. |
MaximumLoadingWait | 60 | Real seconds Boot and Loading wait for loading holds at most. 0: no limit. |
Debugging
The snapshot category Phase (Pulse Debugger, gameplay debugger, MCP) shows the phase, the phase before, the time in the phase, the source, a waiting phase with the holds it waits for, and the last 16 changes with their time. Every change is an event of the debug timeline (source Foundation, category Phase), and the log LogPulseFoundation writes one line per change.