Framework API

1 - GS_Core

GS_Core is the required foundation for every GS_Play project. All other GS gems depend on it. It provides game lifecycle management (startup, shutdown, standby), persistence (save/load), level loading, input handling, triggerable actions, and a shared utility library.

For usage guides and setup examples, see The Basics: GS_Core.

Contents

• GS_Managers
• GS_Save
• GS_StageManager
• GS_Options
• Systems
• Interfaces
• Utilities
• Installation
• See Also

GS_Managers

The lifecycle and startup management system. The Game Manager is a singleton placed in every level — it spawns all registered manager prefabs, coordinates their two-stage initialization, and provides global game navigation and standby mode.

All built-in GS_Play managers (Save, Stage, Options, UI, Unit, Camera, Audio) and any custom managers you create extend the Manager base class and plug into this system automatically.

GS_Managers API

GS_Save

The persistence system. The Save Manager orchestrates save and load operations across the project. Savers are per-entity components that serialize component state. The Record Keeper stores flat key-value progression records independently of the Saver system.

GS_Save API

GS_StageManager

The level loading and navigation system. The Stage Manager owns the ordered stage list for the project and handles all level transitions. Stage Data components are placed in each level as anchors and spin-up controllers for that level’s systems.

GS_StageManager API

GS_Options

Options and input profile management. The Options Manager persists player preferences. Input Profiles are data assets that hold input bindings, swappable at runtime.

GS_Options API

Systems

Core framework systems used across multiple gems: the GS_Motion track-based animation engine and the GS_Actions triggerable behavior system.

Systems API

Interfaces

The cross-gem contract layer. Feature gems depend on neutral contracts collected in GS_Core instead of on each other’s internals. Contracts come in three kinds, distinguished by their class/bus suffix.

Interfaces

Utilities

A general-purpose library of components and math helpers.

Utilities API

Installation

GS_Core is required by all GS_Play projects. Add it to your project before any other GS gem.

1. Follow the Simple Project Setup guide for full walkthrough.
2. Configure collision layers and physics per the Setup Environment guide.
3. Create a Game Manager prefab and place it in every level.
4. Add the managers you need to the Game Manager’s Startup Managers list.

See Also

For conceptual overviews and usage guides:

• The Basics: Core

For related resources:

• Templates
• Third Party Implementations

Get GS_Core

GS_Core — Explore this gem on the product page and add it to your project.

1.1 - GS_Managers

The Managers system is the backbone of every GS_Play project. It provides a controlled startup sequence that initializes game systems in the correct order, global access to those systems via EBus, and systemic navigation (New Game, Load Game, Quit) from a single point of control.

Every GS_Play gem that has a manager component (Save, Stage, UI, Unit, Camera, Audio, etc.) plugs into this system automatically.

For usage guides and setup examples, see The Basics: GS_Core.

Contents

• Architecture
• Components
• Quick Start
• See Also

Architecture

Breakdown

When the project starts, the Game Manager runs three stages before the game is considered ready:

Stage	Broadcast Event	What It Means
1 — Initialize	(internal)	Each manager is spawned. They activate, then report ready.
2 — Setup	OnSetupManagers	Setup stage. Now safe to query other managers.
3 — Complete	OnStartupComplete	Last stage. Everything is ready. Do any last minute things. Now safe to begin gameplay.

For most scripts, you only need OnStartupComplete. Wait for this event before doing anything that depends on managers to be completely setup.

E Indicates extensible classes and methods.

Patterns - Complete list of system patterns used in GS_Play.

Components

Quick Start

For step-by-step setup, see Game Manager — Setup and Manager — Setup.

For creating custom managers, see Manager — Extending the Manager Class.

See Also

For conceptual overviews and usage guides:

• The Basics: GS_Managers

For component references:

• Game Manager
• Manager

For related resources:

• Templates

Get GS_Core

GS_Core — Explore this gem on the product page and add it to your project.

1.1.1 - Game Manager

The Game Manager is the root component of every GS_Play project. It controls the game lifecycle from startup through shutdown: spawning and initializing all Manager components in the correct order, providing systemic navigation (New Game, Load Game, Return to Title, Quit), and coordinating standby mode for pausing gameplay during level transitions or other blocking operations.

Every level in your project should contain the same Game Manager prefab. In debug mode it stays in the current level on start; in release mode it navigates to your title stage.

For usage guides and setup examples, see The Basics: GS_Core.

The Game Manager component in the Entity Inspector, with added manager prefabs in the Startup Managers list.

Contents

• Design Intent
• Dependencies & Interactions
• Setup
• Core Concepts
• Inspector Properties
• API Reference
• SC ↔ C++ Quick Reference
• Usage Examples
• Extending the Game Manager
• See Also

Design Intent

Extend the Game Manager when you need project-wide changes to startup ordering, custom post-startup logic (analytics sessions, online service initialization), or additional global lifecycle events. For most projects, the built-in component is sufficient as-is. Do not move gameplay logic here — the Game Manager orchestrates systems, it does not run game rules.

Dependencies & Interactions

Setup

Game Manager Entity

The Game Manager wrapper entity set as Editor-Only inside Prefab Edit Mode.

1. Create an entity and attach the GS_GameManagerComponent (or your extended version).
2. Turn the entity into a prefab.
3. Enter prefab edit mode. Set the wrapper entity (the parent of your Game Manager entity) to Editor Only. Save the prefab.
4. Create Manager prefabs for the systems you need (Save, Stage, Options, or custom managers).
5. Add each Manager .spawnable to the Game Manager’s Startup Managers list in the Entity Inspector.
6. Push your overrides into the prefab to propagate across all levels.

Place your Game Manager prefab at the top of every level in the Entity Outliner.

The premade manager prefabs for each GS_Play gem are located in that gem’s Assets/Prefabs directory.

Core Concepts

Startup Sequence

When the project starts, the Game Manager executes a three-stage startup:

1. Spawn Managers — The Game Manager instantiates every prefab in its Startup Managers list. Each manager component runs its Activate() and reports back via OnRegisterManagerInit().
2. Startup Managers — Once all managers report initialized, the Game Manager broadcasts OnSetupManagers(). Managers now connect to each other and report back via OnRegisterManagerStartup().
3. Startup Complete — Once all managers report started up, the Game Manager broadcasts OnStartupComplete(). The game is fully initialized and ready to run.

At each stage, the Game Manager counts reports and only proceeds when every spawned manager has reported. This guarantees safe cross-referencing between managers in Stage 2.

Systemic Navigation

The Game Manager provides the high-level game flow methods that drive your project:

• NewGame / NewGame(saveName) — Starts a new game, optionally with a named save file.
• ContinueGame — Loads the most recent save and continues.
• LoadGame(saveName) — Loads a specific save file.
• ReturnToTitle — Returns to the title stage, tearing down the current game session.
• SaveAndExitGame / ExitGame — Saves and/or exits the application.

These methods coordinate with the Save Manager and Stage Manager automatically.

Standby Mode

Standby is a global pause mechanism. When the Game Manager enters standby, it broadcasts OnEnterStandby() to all managers, which propagate the signal to their subsystems. This halts timers, physics, gameplay ticks, and other simulation while a blocking operation (like a stage change) completes. Calling ExitStandby reverses the process.

Debug Mode

When Debug Mode is enabled in the Inspector, the Game Manager skips navigating to the title stage and remains in the current level. This allows rapid iteration — you can start the game from any level without going through the full title-to-gameplay flow. If save data and unit management are enabled, it loads default save data but overrides position data with the current level’s default spawn point.

Inspector Properties

API Reference

Request Bus: GameManagerRequestBus

Commands sent to the Game Manager. Singleton bus — single address, single handler.

Notification Bus: GameManagerNotificationBus

Events broadcast by the Game Manager. Multiple handler bus — any number of components can subscribe.

ScriptCanvas Nodes

These methods and events are available as ScriptCanvas nodes.

Request Nodes

Notification Nodes

Listen for these events on GameManagerNotificationBus.

Virtual Methods

Override these when extending the Game Manager. Always call the base implementation.

SC ↔ C++ Quick Reference

Usage Examples

ScriptCanvas: Title Screen Workflow

Calling new or load game proceedes to start the gameplay and systems. Begin Game event fires to start all systems across the game.

Debug Mode automatically begins the game.

ScriptCanvas: Standby Logic

C++: Reacting to Events

A gameplay component that listens to the full startup and standby lifecycle:

#include <GS_Core/GS_CoreBus.h>

class MyGameplayComponent
    : public AZ::Component
    , protected GS_Core::GameManagerNotificationBus::Handler
{
protected:
    void Activate() override
    {
        GS_Core::GameManagerNotificationBus::Handler::BusConnect();
    }

    void Deactivate() override
    {
        GS_Core::GameManagerNotificationBus::Handler::BusDisconnect();
    }

    void OnStartupComplete() override
    {
        // Safe to access all managers and begin gameplay logic
    }

    void OnEnterStandby() override
    {
        // Pause your gameplay systems
    }

    void OnExitStandby() override
    {
        // Resume your gameplay systems
    }
};

C++: Custom Manager Integration

A manager that receives the startup handshake from the Game Manager. Add this class’s prefab to the Game Manager’s Startup Managers list:

#include <GS_Core/GS_CoreBus.h>
#include <Source/Managers/GS_ManagerComponent.h>

class MySystemManager
    : public GS_Core::GS_ManagerComponent
    , protected GS_Core::GameManagerNotificationBus::Handler
{
public:
    AZ_COMPONENT_DECL(MySystemManager);
    static void Reflect(AZ::ReflectContext* context);

protected:
    void Activate() override
    {
        GS_Core::GS_ManagerComponent::Activate();                        // Required: registers with Game Manager
        GS_Core::GameManagerNotificationBus::Handler::BusConnect();
    }

    void Deactivate() override
    {
        GS_Core::GameManagerNotificationBus::Handler::BusDisconnect();
        GS_Core::GS_ManagerComponent::Deactivate();                      // Required: deregisters from Game Manager
    }

    // Called during Stage 2 — safe to reference other managers here
    void OnSetupManagers() override
    {
        // Connect to other managers, set up cross-system references
    }

    // Called when the full startup sequence completes — safe to begin gameplay
    void OnStartupComplete() override
    {
        // Initialize systems that depend on all managers being ready
    }

    void OnEnterStandby() override { /* pause your systems */ }
    void OnExitStandby()  override { /* resume your systems */ }
};

Extending the Game Manager

Extend the Game Manager to add custom startup logic, additional lifecycle events, or project-specific behavior. Extension is done in C++.

Header (.h)

#pragma once
#include <GS_Core/GS_CoreBus.h>
#include <Source/Managers/GS_GameManagerComponent.h>

namespace MyProject
{
    class MyGameManager : public GS_Core::GS_GameManagerComponent
    {
    public:
        AZ_COMPONENT_DECL(MyGameManager);

        static void Reflect(AZ::ReflectContext* context);

    protected:
        void InitializeManagers() override;
        void StartupManagers() override;
        void CompleteStartup() override;
        void BeginGame() override;
    };
}

Implementation (.cpp)

#include "MyGameManager.h"
#include <AzCore/Serialization/SerializeContext.h>

namespace MyProject
{
    AZ_COMPONENT_IMPL(MyGameManager, "MyGameManager", "{YOUR-UUID-HERE}");

    void MyGameManager::Reflect(AZ::ReflectContext* context)
    {
        if (auto serializeContext = azrtti_cast<AZ::SerializeContext*>(context))
        {
            serializeContext->Class<MyGameManager, GS_Core::GS_GameManagerComponent>()
                ->Version(0);

            if (AZ::EditContext* editContext = serializeContext->GetEditContext())
            {
                editContext->Class<MyGameManager>("My Game Manager", "Custom game manager for MyProject")
                    ->ClassElement(AZ::Edit::ClassElements::EditorData, "")
                        ->Attribute(AZ::Edit::Attributes::Category, "MyProject")
                        ->Attribute(AZ::Edit::Attributes::AppearsInAddComponentMenu, AZ_CRC_CE("Game"));
            }
        }
    }

    void MyGameManager::InitializeManagers()
    {
        // Call base to spawn the standard manager list
        GS_GameManagerComponent::InitializeManagers();
        // Custom initialization logic here
    }

    void MyGameManager::StartupManagers()
    {
        // Call base to handle standard startup
        GS_GameManagerComponent::StartupManagers();
    }

    void MyGameManager::CompleteStartup()
    {
        // Call base to broadcast OnStartupComplete
        GS_GameManagerComponent::CompleteStartup();
        // Post-startup logic here (e.g. connect to analytics, initialize online services)
    }

    void MyGameManager::BeginGame()
    {
        GS_GameManagerComponent::BeginGame();
        // Custom game start logic
    }
}

See Also

For scripting patterns and SC-first usage:

• The Basics: GS_Managers

For related components:

• Manager Base Class
• GS_Managers Overview
• Save Manager
• Stage Manager
• Templates

Get GS_Core

GS_Core — Explore this gem on the product page and add it to your project.

1.1.2 - Manager

For usage guides and setup examples, see The Basics: GS_Core.

A Manager prefab with the wrapper entity set as Editor-Only inside Prefab Edit Mode.

GS_GameManager
  └── (spawns) GS_ManagerComponent ◄ you are here — and all other managers extend this

The GS_ManagerComponent is the base class that all game system managers inherit from. It handles the two-stage initialization pattern with the Game Manager automatically, so you can focus on your system’s logic without worrying about startup ordering.

Every built-in GS_Play manager (Save, Stage, Options, UI, Unit, Camera, Audio, Performer) extends this class. When you need a custom game system manager, you extend it too.

Contents

• How It Works
• Setup
• Inspector Properties
• API Reference
• Usage Examples
• Extending the Manager Class
• See Also

How It Works

When the Game Manager spawns its list of manager prefabs, each Manager component goes through this lifecycle:

1. Activate — The component initializes itself (connects to buses, sets up internal state). When done, broadcasts OnRegisterManagerInit() to tell the Game Manager it is ready.

2. OnStartupManagers — Called by the Game Manager after all managers have reported initialized. Connect to other managers and set up cross-references here. When done, broadcasts OnRegisterManagerStartup().

3. OnStartupComplete — The Game Manager broadcasts this after all managers report started up. The game is fully ready.

4. OnEnterStandby / OnExitStandby — Called when the Game Manager enters or exits standby mode. Pause and resume your subsystem here.

5. OnShutdownManagers — Called when the game is shutting down. Clean up resources and disconnect buses.

The base class handles steps 1–2 automatically. Override them to add your logic, then call the base implementation to complete the handshake.

Setup

The Manager wrapper entity set as Editor-Only inside Prefab Edit Mode.

1. Create an entity. Attach your Manager component (built-in or custom) to it.
2. Configure any properties needed in the Entity Inspector.
3. Turn the entity into a prefab.
4. Enter prefab edit mode. Set the wrapper entity (parent of your Manager entity) to Editor Only. Save.
5. Delete the Manager entity from the level (it will be spawned by the Game Manager at runtime).
6. In the Game Manager prefab, add your Manager .spawnable to the Startup Managers list.

The premade manager prefabs for each GS_Play gem are located in that gem’s Assets/Prefabs directory.

Inspector Properties

The base GS_ManagerComponent exposes no inspector properties of its own. Properties are defined by each inheriting manager component (e.g., the Save Manager exposes a Save System Version Number, the Stage Manager exposes a Stages list).

API Reference

Lifecycle Events: GameManagerNotificationBus

The Manager base class automatically subscribes to these events from the Game Manager:

Registration Methods

Called internally by the Manager base class to report back to the Game Manager. Do not call these manually — call the base class method instead.

Usage Examples

C++ — Checking if the Game Manager Is Ready

#include <GS_Core/GS_CoreBus.h>

bool isStarted = false;
GS_Core::GameManagerRequestBus::BroadcastResult(
    isStarted,
    &GS_Core::GameManagerRequestBus::Events::IsStarted
);

if (isStarted)
{
    // Safe to access all managers
}

Extending the Manager Class

Create a custom manager whenever you need a singleton game system that initializes with the rest of the framework. Extension is done in C++.

Header (.h)

#pragma once
#include <Source/Managers/GS_ManagerComponent.h>

// Define your EBus interface for other systems to call your manager
class MyManagerRequests
{
public:
    AZ_RTTI(MyManagerRequests, "{YOUR-UUID-HERE}");
    virtual ~MyManagerRequests() = default;

    virtual int GetSomeValue() = 0;
    virtual void DoSomething() = 0;
};

class MyManagerBusTraits : public AZ::EBusTraits
{
public:
    static constexpr AZ::EBusHandlerPolicy HandlerPolicy = AZ::EBusHandlerPolicy::Single;
    static constexpr AZ::EBusAddressPolicy AddressPolicy = AZ::EBusAddressPolicy::Single;
};

using MyManagerRequestBus = AZ::EBus<MyManagerRequests, MyManagerBusTraits>;

namespace MyProject
{
    class MyManagerComponent
        : public GS_Core::GS_ManagerComponent
        , protected MyManagerRequestBus::Handler
    {
    public:
        AZ_COMPONENT_DECL(MyManagerComponent);

        static void Reflect(AZ::ReflectContext* context);

    protected:
        // Manager lifecycle
        void Activate() override;
        void Deactivate() override;
        void OnStartupManagers() override;
        void OnEnterStandby() override;
        void OnExitStandby() override;

        // Your bus implementation
        int GetSomeValue() override;
        void DoSomething() override;

    private:
        int m_someValue = 0;
    };
}

Implementation (.cpp)

#include "MyManagerComponent.h"
#include <AzCore/Serialization/SerializeContext.h>

namespace MyProject
{
    AZ_COMPONENT_IMPL(MyManagerComponent, "MyManagerComponent", "{YOUR-UUID-HERE}");

    void MyManagerComponent::Reflect(AZ::ReflectContext* context)
    {
        if (auto serializeContext = azrtti_cast<AZ::SerializeContext*>(context))
        {
            serializeContext->Class<MyManagerComponent, GS_Core::GS_ManagerComponent>()
                ->Version(0)
                ->Field("SomeValue", &MyManagerComponent::m_someValue);

            if (AZ::EditContext* editContext = serializeContext->GetEditContext())
            {
                editContext->Class<MyManagerComponent>("My Manager", "A custom game system manager")
                    ->ClassElement(AZ::Edit::ClassElements::EditorData, "")
                        ->Attribute(AZ::Edit::Attributes::Category, "MyProject")
                        ->Attribute(AZ::Edit::Attributes::AppearsInAddComponentMenu, AZ_CRC_CE("Game"))
                    ->DataElement(AZ::Edit::UIHandlers::Default,
                        &MyManagerComponent::m_someValue, "Some Value", "Description of this property");
            }
        }
    }

    void MyManagerComponent::Activate()
    {
        MyManagerRequestBus::Handler::BusConnect();

        // IMPORTANT: Call base Activate last — it reports OnRegisterManagerInit()
        GS_ManagerComponent::Activate();
    }

    void MyManagerComponent::Deactivate()
    {
        MyManagerRequestBus::Handler::BusDisconnect();
        GS_ManagerComponent::Deactivate();
    }

    void MyManagerComponent::OnStartupManagers()
    {
        // Access other managers here — they are all initialized by now

        // IMPORTANT: Call base last — it reports OnRegisterManagerStartup()
        GS_ManagerComponent::OnStartupManagers();
    }

    void MyManagerComponent::OnEnterStandby()
    {
        // Pause your subsystem
    }

    void MyManagerComponent::OnExitStandby()
    {
        // Resume your subsystem
    }

    int MyManagerComponent::GetSomeValue()
    {
        return m_someValue;
    }

    void MyManagerComponent::DoSomething()
    {
        // Your game system logic
    }
}

Module Registration

m_descriptors.insert(m_descriptors.end(), {
    MyProject::MyManagerComponent::CreateDescriptor(),
});

Then create a prefab for your manager and add it to the Game Manager’s Startup Managers list.

See Also

For conceptual overviews and usage guides:

• The Basics: GS_Managers
• GS_Managers Overview

For component references:

• Game Manager
• Save Manager
• Stage Manager

For related resources:

• Templates

Get GS_Core

GS_Core — Explore this gem on the product page and add it to your project.

1.2 - GS_Save

The Save system is the universal means of storing, loading, and handling game data. It provides a centralized Save Manager for file operations, entity-level Saver components for automatic data capture, and a Record Keeper for lightweight progression tracking — all backed by JSON-formatted save files that work across PC, console, and mobile platforms.

Every component that needs to persist data plugs into this system through one of two patterns: extend the Saver base class for complex per-entity data, or use the Record Keeper for simple key-value records.

For usage guides and setup examples, see The Basics: GS_Core.

Contents

• Architecture
• Components
• Quick Start
• See Also

Architecture

Breakdown

When a save or load is triggered, the Save Manager broadcasts to every Saver in the scene. Each Saver independently handles its own entity’s state. The Record Keeper persists flat progression data alongside the save file.

Part	Broadcast Event	What It Means
Save Manager	OnSaveAll	Broadcasts to all Savers on save. Each serializes its entity state.
Save Manager	OnLoadAll	Broadcasts to all Savers on load. Each restores its entity state.
Record Keeper	RecordChanged	Fires when any progression flag is created, updated, or deleted.

Savers are per-entity components — extend GS_SaverComponent to persist any custom data. The Record Keeper is a global singleton that lives on the Save Manager prefab.

E Indicates extensible classes and methods.

Patterns - Complete list of system patterns used in GS_Play.

Components

Quick Start

1. Create a Save Manager prefab with the GS_SaveManagerComponent.
2. Optionally add a Record Keeper to the same prefab for progression tracking.
3. Add the Save Manager .spawnable to the Game Manager’s Startup Managers list.
4. Attach Saver components to any entities that need to persist data.
5. Call NewGame / LoadGame through the Game Manager — the Save Manager handles the rest.

See Also

For conceptual overviews and usage guides:

• The Basics: GS_Save

For component references:

• Save Manager
• Record Keeper
• Savers

For related resources:

• Game Manager
• Templates

Get GS_Core

GS_Core — Explore this gem on the product page and add it to your project.

1.2.1 - Save Manager

The Save Manager is the central controller of the save system. It manages save file creation, triggers global save/load events that all Saver components respond to, and provides data access methods for storing and retrieving serialized game state.

Save files use JSON formatting for easy human interpretation, and the system uses the O3DE SaveData gem to write to the target platform’s default user data directory — PC, console, or mobile with no additional configuration.

For usage guides and setup examples, see The Basics: GS_Core.

Contents

• How It Works
• Setup
• Inspector Properties
• API Reference
• Usage Examples
• Extending the Save Manager
• See Also

How It Works

Save File Structure

The Save Manager maintains a CoreSaveData file that acts as an index of all save files for the project. This file is identified by the combination of the Game Manager’s Project Prefix and the Save Manager’s Save System Version Number. Changing either value starts a fresh save data pass.

Each individual save file stores the full game state as a JSON document, including timestamped metadata for ordering.

Initialization

On startup, the Save Manager checks for existing save data using the Project Prefix + Version combination. It sets its internal IsContinuing flag to indicate whether previous save data is available to load. Other systems can query this to determine whether to show “Continue” or “Load Game” options.

New Game Flow

When the Game Manager calls NewGame:

1. The Save Manager creates a new save file — either defaultSaveData (no name given) or a custom name via NewGame(saveName).
2. The CoreSaveData index is updated with the new file entry.

Save Flow

1. Game systems call SaveData(uniqueName, data) on the SaveManagerRequestBus to store their data into the live save document.
2. When a full save is triggered (via method call, OnSaveAll broadcast, or save-on-exit logic), the Save Manager serializes the complete document to disk.

Load Flow

1. The Save Manager reads the target save file from disk into memory.
2. It broadcasts OnLoadAll via the SaveManagerNotificationBus.
3. Each Saver component responds by calling LoadData(uniqueName, outData) to retrieve its portion of the save data.

Setup

Image showing the Manager wrapper entity set as Editor-Only inside Prefab Edit Mode.

1. Create an entity. Attach the GS_SaveManagerComponent to it.
2. Set the Save System Version Number (increment this when your save format changes to avoid loading incompatible data).
3. Optionally add a RecordKeeperComponent to the same entity for progression tracking.
4. Turn the entity into a prefab.
5. Enter prefab edit mode. Set the wrapper entity (parent) to Editor Only. Save.
6. Delete the Save Manager entity from the level.
7. In the Game Manager prefab, add the Save Manager .spawnable to the Startup Managers list.

Inspector Properties

API Reference

Request Bus: SaveManagerRequestBus

The primary interface for all save/load operations. Singleton bus — call via Broadcast.

Notification Bus: SaveManagerNotificationBus

Broadcast to all Saver components. Connect to this bus to participate in global save/load events.

Local / Virtual Methods

These methods are available when extending the Save Manager. Override them to customize save file handling.

Usage Examples

Saving Data from a Component

#include <GS_Core/GS_CoreBus.h>

// Store your component's data into the live save document
rapidjson::Document::AllocatorType* allocator = nullptr;
GS_Core::SaveManagerRequestBus::BroadcastResult(
    allocator,
    &GS_Core::SaveManagerRequestBus::Events::GetAllocator
);

if (allocator)
{
    rapidjson::Value myData(rapidjson::kObjectType);
    myData.AddMember("health", m_health, *allocator);
    myData.AddMember("level", m_level, *allocator);

    GS_Core::SaveManagerRequestBus::Broadcast(
        &GS_Core::SaveManagerRequestBus::Events::SaveData,
        "MyComponent_PlayerStats",
        myData
    );
}

Loading Data into a Component

#include <GS_Core/GS_CoreBus.h>

rapidjson::Value outData;
bool found = false;
GS_Core::SaveManagerRequestBus::BroadcastResult(
    found,
    &GS_Core::SaveManagerRequestBus::Events::LoadData,
    "MyComponent_PlayerStats",
    outData
);

if (found)
{
    if (outData.HasMember("health")) m_health = outData["health"].GetInt();
    if (outData.HasMember("level"))  m_level = outData["level"].GetInt();
}

Checking if a Save Exists

#include <GS_Core/GS_CoreBus.h>

bool hasSave = false;
GS_Core::SaveManagerRequestBus::BroadcastResult(
    hasSave,
    &GS_Core::SaveManagerRequestBus::Events::IsContinuing
);

if (hasSave)
{
    // Show "Continue" / "Load Game" in the main menu
}

Getting the Save File List

#include <GS_Core/GS_CoreBus.h>

AZStd::vector<AZStd::pair<AZStd::string, AZ::u64>> saves;
GS_Core::SaveManagerRequestBus::BroadcastResult(
    saves,
    &GS_Core::SaveManagerRequestBus::Events::GetOrderedSaveList
);

for (const auto& [name, epoch] : saves)
{
    AZStd::string readable;
    GS_Core::SaveManagerRequestBus::BroadcastResult(
        readable,
        &GS_Core::SaveManagerRequestBus::Events::ConvertEpochToReadable,
        epoch
    );
    AZ_TracePrintf("Save", "Save: %s — %s", name.c_str(), readable.c_str());
}

Extending the Save Manager

Extend the Save Manager when you need custom save file formats, encryption, cloud save integration, or platform-specific serialization.

Header (.h)

#pragma once
#include <Source/SaveSystem/GS_SaveManagerComponent.h>

namespace MyProject
{
    class MySaveManagerComponent
        : public GS_Core::GS_SaveManagerComponent
    {
    public:
        AZ_COMPONENT_DECL(MySaveManagerComponent);

        static void Reflect(AZ::ReflectContext* context);

    protected:
        // Override save/load to add custom behavior (e.g., encryption, compression)
        void SaveToFile(AZStd::string fileName, rapidjson::Document& docFile) override;
        void LoadFromFile(AZStd::string fileName, rapidjson::Document& docFile) override;

        // Override to customize the full save sequence
        void FullSave() override;
    };
}

Implementation (.cpp)

#include "MySaveManagerComponent.h"
#include <AzCore/Serialization/SerializeContext.h>

namespace MyProject
{
    AZ_COMPONENT_IMPL(MySaveManagerComponent, "MySaveManagerComponent", "{YOUR-UUID-HERE}",
        GS_Core::GS_SaveManagerComponent);

    void MySaveManagerComponent::Reflect(AZ::ReflectContext* context)
    {
        if (auto serializeContext = azrtti_cast<AZ::SerializeContext*>(context))
        {
            serializeContext->Class<MySaveManagerComponent, GS_Core::GS_SaveManagerComponent>()
                ->Version(0);

            if (AZ::EditContext* editContext = serializeContext->GetEditContext())
            {
                editContext->Class<MySaveManagerComponent>(
                    "My Save Manager", "Custom save manager with encryption support")
                    ->ClassElement(AZ::Edit::ClassElements::EditorData, "")
                        ->Attribute(AZ::Edit::Attributes::Category, "MyProject")
                        ->Attribute(AZ::Edit::Attributes::AppearsInAddComponentMenu, AZ_CRC_CE("Game"));
            }
        }
    }

    void MySaveManagerComponent::SaveToFile(AZStd::string fileName, rapidjson::Document& docFile)
    {
        // Example: encrypt the JSON before writing
        // ... your encryption logic ...

        // Call base to perform the actual file write
        GS_SaveManagerComponent::SaveToFile(fileName, docFile);
    }

    void MySaveManagerComponent::LoadFromFile(AZStd::string fileName, rapidjson::Document& docFile)
    {
        // Call base to perform the actual file read
        GS_SaveManagerComponent::LoadFromFile(fileName, docFile);

        // Example: decrypt the JSON after reading
        // ... your decryption logic ...
    }

    void MySaveManagerComponent::FullSave()
    {
        // Example: add a timestamp or checksum before saving
        // ... your custom logic ...

        GS_SaveManagerComponent::FullSave();
    }
}

Module Registration

m_descriptors.insert(m_descriptors.end(), {
    MyProject::MySaveManagerComponent::CreateDescriptor(),
});

Then create a prefab for your custom Save Manager and add it to the Game Manager’s Startup Managers list (replacing the default Save Manager).

See Also

For component references:

• Savers
• Record Keeper
• Game Manager
• Manager

For related resources:

• Templates

Get GS_Core

GS_Core — Explore this gem on the product page and add it to your project.

1.2.2 - Savers

For usage guides and setup examples, see The Basics: GS_Core.

Image showing the Basic Physics Saver component, an example of a Saver-inherited class, as seen in the Entity Inspector.

The GS_SaverComponent is the base class for all entity-level save handlers. By extending it, you can create companion components that save and load data alongside your entities, or inherit directly into gameplay components for built-in persistence (as done by GS_Inventory).

Savers automatically participate in the global save/load cycle — when the Save Manager broadcasts OnSaveAll or OnLoadAll, every active Saver component responds by gathering or restoring its data.

Contents

• How It Works
• Setup
• Inspector Properties
• API Reference
• Components
• Usage Examples
• Extending the Saver Class
• See Also

How It Works

Save Cycle

When a save event fires (global OnSaveAll, local trigger, or saveOnDestroy):

1. BeginSave() — Primes the save data container.
2. BuildSaveData() — Your override. Gather your component’s data and write it into localData using the Save Manager’s JSON allocator.
3. CompleteSave() — Submits the data to the Save Manager via SaveData(uniqueName, localData).

Load Cycle

When a load event fires (global OnLoadAll or loadOnActivate):

1. LoadLocalData() — Retrieves this Saver’s data block from the Save Manager via LoadData(uniqueName, outData).
2. ProcessLoad() — Your override. Read the retrieved data and restore your component’s state.

Automatic Identity

Each Saver generates a unique save key from the entity name and GetSubComponentName(). This ensures multiple Savers on different entities (or multiple Saver types on the same entity) don’t collide.

Setup

1. Attach a Saver component (built-in or custom) to any entity that needs to persist data.
2. Configure the Saver properties:
   • Load On Activate — restore data automatically when the entity spawns.
   • Save On Destroy — save data automatically when the entity is destroyed.
3. Ensure the Save Manager is set up and running (it handles the file I/O).

Inspector Properties

API Reference

Global Event Handlers

These are called automatically when the Save Manager broadcasts global save/load events. Override to customize behavior.

Save Methods

Override these to control how your component’s data is saved.

Load Methods

Override these to control how your component’s data is restored.

Utility Methods

Components

Pre-built Saver components included in GS_Core:

Usage Examples

Responding to Global Save/Load Events

If your component doesn’t extend GS_SaverComponent but still needs to react to save/load events, connect to the SaveManagerNotificationBus:

#include <GS_Core/GS_CoreBus.h>

class MyComponent
    : public AZ::Component
    , protected GS_Core::SaveManagerNotificationBus::Handler
{
protected:
    void Activate() override
    {
        GS_Core::SaveManagerNotificationBus::Handler::BusConnect();
    }

    void Deactivate() override
    {
        GS_Core::SaveManagerNotificationBus::Handler::BusDisconnect();
    }

    void OnSaveAll() override
    {
        // Gather and submit data to the Save Manager
    }

    void OnLoadAll() override
    {
        // Retrieve and restore data from the Save Manager
    }
};

Extending the Saver Class

Use the SaverComponent ClassWizard template to generate a new saver with boilerplate already in place — see GS_Core Templates.

Create a custom Saver whenever you need to persist component-specific data that the built-in savers don’t cover.

Header (.h)

#pragma once
#include <Source/SaveSystem/GS_SaverComponent.h>

namespace MyProject
{
    class MyEntitySaverComponent
        : public GS_Core::GS_SaverComponent
    {
    public:
        AZ_COMPONENT_DECL(MyEntitySaverComponent);

        static void Reflect(AZ::ReflectContext* context);

    protected:
        // Saver overrides
        void BuildSaveData() override;
        void ProcessLoad() override;
        AZStd::string GetSubComponentName() const override { return "MyEntitySaver"; }
    };
}

Implementation (.cpp)

#include "MyEntitySaverComponent.h"
#include <AzCore/Serialization/SerializeContext.h>
#include <GS_Core/GS_CoreBus.h>

namespace MyProject
{
    AZ_COMPONENT_IMPL(MyEntitySaverComponent, "MyEntitySaverComponent", "{YOUR-UUID-HERE}",
        GS_Core::GS_SaverComponent);

    void MyEntitySaverComponent::Reflect(AZ::ReflectContext* context)
    {
        if (auto serializeContext = azrtti_cast<AZ::SerializeContext*>(context))
        {
            serializeContext->Class<MyEntitySaverComponent, GS_Core::GS_SaverComponent>()
                ->Version(0);

            if (AZ::EditContext* editContext = serializeContext->GetEditContext())
            {
                editContext->Class<MyEntitySaverComponent>(
                    "My Entity Saver", "Saves custom entity data")
                    ->ClassElement(AZ::Edit::ClassElements::EditorData, "")
                        ->Attribute(AZ::Edit::Attributes::Category, "MyProject")
                        ->Attribute(AZ::Edit::Attributes::AppearsInAddComponentMenu, AZ_CRC_CE("Game"));
            }
        }
    }

    void MyEntitySaverComponent::BuildSaveData()
    {
        // Get the JSON allocator from the Save Manager
        rapidjson::Document::AllocatorType* allocator = nullptr;
        GS_Core::SaveManagerRequestBus::BroadcastResult(
            allocator,
            &GS_Core::SaveManagerRequestBus::Events::GetAllocator
        );

        if (!allocator) return;

        // Write your data into localData (inherited member)
        localData.SetObject();
        localData.AddMember("myValue", 42, *allocator);
        localData.AddMember("myFlag", true, *allocator);

        // Example: save a string
        rapidjson::Value nameVal;
        nameVal.SetString("hello", *allocator);
        localData.AddMember("myString", nameVal, *allocator);
    }

    void MyEntitySaverComponent::ProcessLoad()
    {
        // Read your data from localData (populated by LoadLocalData)
        if (localData.HasMember("myValue"))
        {
            int myValue = localData["myValue"].GetInt();
            // ... restore state ...
        }

        if (localData.HasMember("myFlag"))
        {
            bool myFlag = localData["myFlag"].GetBool();
            // ... restore state ...
        }
    }
}

Module Registration

m_descriptors.insert(m_descriptors.end(), {
    MyProject::MyEntitySaverComponent::CreateDescriptor(),
});

Attach your custom Saver to any entity that needs persistence. The save/load cycle handles the rest automatically.

See Also

For component references:

• Save Manager
• Record Keeper
• List of Savers

For related resources:

• Templates

Get GS_Core

GS_Core — Explore this gem on the product page and add it to your project.

1.2.2.1 - List of Savers

For usage guides and setup examples, see The Basics: GS_Core.

Contents

• Basic Entity Saver
• Basic Physics Entity Saver
• Creating Your Own Saver
• See Also

GS_Core includes pre-built Saver components that handle common persistence scenarios out of the box. Attach one to any entity that needs to remember its state between save/load cycles — no custom code required.

All built-in Savers inherit from GS_SaverComponent and participate in the global save/load cycle automatically.

Basic Entity Saver

A companion component that saves and loads an entity’s Transform data: position and rotation.

When to Use

Use the Basic Entity Saver for any entity that can be moved or rotated during gameplay and needs to retain its position across saves — collectibles, furniture, doors, NPCs with fixed patrol points, etc.

Inspector Properties

What It Saves

Setup

1. Attach the BasicEntitySaverComponent to any entity that needs Transform persistence.
2. Ensure the Save Manager is running.
3. That’s it — the component saves and loads automatically.

Basic Physics Entity Saver

Image showing the Basic Physics Saver component, as seen in the Entity Inspector.

A companion component that saves and loads an entity’s Transform and Rigidbody physics state.

When to Use

Use the Basic Physics Entity Saver for physics-driven entities that need to retain both their position and their motion state across saves — throwable objects, rolling boulders, physics puzzles, ragdolls, etc.

Inspector Properties

What It Saves

Setup

1. Attach the BasicPhysicsEntitySaverComponent to any entity with a Rigidbody component.
2. Ensure the Save Manager is running.
3. The component saves and loads automatically.

Creating Your Own Saver

Need to persist data that the built-in Savers don’t cover? See the Extending the Saver Class guide for a complete walkthrough with header, implementation, and module registration.

See Also

For component references:

• Savers
• Save Manager
• Record Keeper

Get GS_Core

GS_Core — Explore this gem on the product page and add it to your project.

1.2.3 - Record Keeper

For usage guides and setup examples, see The Basics: GS_Core.

Image showing the Record Keeper component with its unique variables and inherited Saver properties, as seen in the Entity Inspector.

The Record Keeper is a companion component that provides a simple key-value store for tracking progression, switch states, quest stages, or any other data that doesn’t require a complex Saver implementation. Each record is a SaveRecord — a name/value pair of recordName (string) and recordProgress (integer).

Because it extends GS_SaverComponent, the Record Keeper saves and loads automatically with the rest of the save system. No custom serialization code needed.

Contents

• How It Works
• Setup
• Inspector Properties
• API Reference
• Usage Examples
• Extending the Record Keeper
• See Also

How It Works

1. The Record Keeper lives on your Save Manager prefab entity (recommended) or any entity with save system access.
2. Game systems call SetRecord, GetRecord, HasRecord, and DeleteRecord via the RecordKeeperRequestBus.
3. On each call to SetRecord, the Record Keeper broadcasts RecordChanged on the RecordKeeperNotificationBus so listeners can react.
4. When a global save event fires (OnSaveAll), the Record Keeper serializes all its records into the save file automatically.
5. On load, it deserializes its records and makes them available immediately.

SaveRecord Data Structure

struct SaveRecord
{
    AZStd::string recordName;    // Unique key (e.g., "quest_village_rescue", "switch_bridge_01")
    AZ::s32       recordProgress; // Integer value (progression stage, state, count, etc.)
};

TypeId: {F6F4F258-819A-468A-B015-CAF51D8289BF}

Setup

1. Open your Save Manager prefab in prefab edit mode.
2. Add the RecordKeeperComponent to the Save Manager entity.
3. Set the Record Keeper Name — this drives unique save/load identification and allows multiple Record Keepers if needed.
4. Enable the Saver booleans as needed:
   • Load On Activate — automatically loads records when the component activates (recommended: on).
   • Save On Destroy — automatically saves records when the component is destroyed (recommended: on).

Inspector Properties

API Reference

Request Bus: RecordKeeperRequestBus

The primary interface for reading and writing records.

Notification Bus: RecordKeeperNotificationBus

Connect to this bus to react when records change.

Usage Examples

Setting a Progression Record

#include <GS_Core/GS_CoreBus.h>

// Mark quest stage 2 as complete
GS_Core::RecordKeeperRequestBus::Broadcast(
    &GS_Core::RecordKeeperRequestBus::Events::SetRecord,
    "quest_village_rescue",
    2
);

Reading a Record

#include <GS_Core/GS_CoreBus.h>

AZ::s32 questStage = 0;
GS_Core::RecordKeeperRequestBus::BroadcastResult(
    questStage,
    &GS_Core::RecordKeeperRequestBus::Events::GetRecord,
    "quest_village_rescue"
);

if (questStage >= 2)
{
    // The player has completed stage 2 — unlock the bridge
}

Checking if a Record Exists

#include <GS_Core/GS_CoreBus.h>

bool exists = false;
GS_Core::RecordKeeperRequestBus::BroadcastResult(
    exists,
    &GS_Core::RecordKeeperRequestBus::Events::HasRecord,
    "switch_bridge_01"
);

if (!exists)
{
    // First time encountering this switch — initialize it
    GS_Core::RecordKeeperRequestBus::Broadcast(
        &GS_Core::RecordKeeperRequestBus::Events::SetRecord,
        "switch_bridge_01",
        0
    );
}

Listening for Record Changes

#include <GS_Core/GS_CoreBus.h>

// In your component header:
class MyQuestTrackerComponent
    : public AZ::Component
    , protected GS_Core::RecordKeeperNotificationBus::Handler
{
protected:
    void Activate() override
    {
        GS_Core::RecordKeeperNotificationBus::Handler::BusConnect();
    }

    void Deactivate() override
    {
        GS_Core::RecordKeeperNotificationBus::Handler::BusDisconnect();
    }

    // RecordKeeperNotificationBus
    void RecordChanged(const AZStd::string& recordName, AZ::s32 recordValue) override
    {
        if (recordName == "quest_village_rescue" && recordValue >= 3)
        {
            // Quest complete — trigger reward
        }
    }
};

Extending the Record Keeper

For complex data needs beyond simple key-value records, create custom Saver components.

See Also

For component references:

• Save Manager
• Savers
• List of Savers

Get GS_Core

GS_Core — Explore this gem on the product page and add it to your project.

1.3 - GS_StageManager

The Stage Manager system handles the process of changing levels, loading and unloading their assets, and starting up levels in the correct sequence. It supports incremental loading so that complex levels with generative components can spin up reliably without massive frame-time spikes.

Each level contains a Stage Data component that acts as the level’s anchor — connecting the Stage Manager to level-specific references, startup sequences, and navigation data. Exit Points mark spawn positions for player placement when transitioning between stages.

For usage guides and setup examples, see The Basics: GS_Core.

Contents

• Architecture
• Components
• Quick Start
• See Also

Architecture

Breakdown

When a stage change is requested, the system follows a five-step sequence before gameplay resumes in the new level:

Step	Broadcast Event	What It Means
1 — Standby	OnEnterStandby	Game Manager enters standby, halting all gameplay systems.
2 — Unload	(internal)	The current stage’s entities are torn down.
3 — Spawn	(internal)	The target stage prefab is instantiated.
4 — Set Up	OnBeginSetUpStage	Stage Data runs its layered startup: SetUpStage → ActivateByPriority → Complete.
5 — Complete	LoadStageComplete	Stage Manager broadcasts completion. Standby exits. Gameplay resumes.

The Stage Data startup is layered so heavy levels can initialize incrementally without causing frame-time spikes.

E Indicates extensible classes and methods.

Patterns - Complete list of system patterns used in GS_Play.

Components

Quick Start

1. Create a Stage Manager prefab with the GS_StageManagerComponent.
2. Add stage entries to the Stages list (name + spawnable prefab for each level).
3. Set the Default Stage to your starting level.
4. Add the Stage Manager .spawnable to the Game Manager’s Startup Managers list.
5. In each level prefab, add a Stage Data component as the level’s anchor.
6. Optionally place Exit Points in each level for spawn positioning.

See Also

For conceptual overviews and usage guides:

• The Basics: GS_StageManager

For component references:

• Stage Manager
• Stage Data

For related resources:

• Game Manager
• Save Manager

Get GS_Core

GS_Core — Explore this gem on the product page and add it to your project.

1.3.1 - Stage Manager

The Stage Manager is the singleton that handles all the logistics of loading and unloading game levels. It maintains a list of stages (name-to-spawnable mappings) and processes change requests by unloading the current stage and spawning the target. Once loaded, it connects to the level’s Stage Data component to run the staged startup sequence.

The system operates as a “one in, one out” format — loading one level automatically unloads the previous one.

For usage guides and setup examples, see The Basics: GS_Core.

Contents

• How It Works
• Setup
• Inspector Properties
• API Reference
• Usage Examples
• Extending the Stage Manager
• See Also

How It Works

Startup

At game startup, the Stage Manager checks the Game Manager’s Debug Mode flag:

• Debug Mode OFF — The Stage Manager loads the Default Stage automatically. This is the normal game flow.
• Debug Mode ON — The Stage Manager stays connected to whatever level is already loaded in the editor. This lets developers iterate within a stage without waiting for a full level load cycle.

Change Stage Flow

When ChangeStageRequest(stageName, exitName) is called:

1. Unload — The current stage is destroyed (if one is loaded).
2. Spawn — The Stage Manager looks up stageName in the Stages list and spawns the matching prefab.
3. Connect — The Stage Manager queries the newly spawned level for its Stage Data component.
4. Startup — The Stage Data component runs the level’s staged activation sequence (priority layers, NavMesh generation, etc.).
5. Notify — The Stage Manager broadcasts LoadStageComplete when the level is fully ready.

Exit Points

Exit Points are simple components placed within a level that mark positions for entity placement after a stage loads. They support cross-stage traversal — when changing stages, you specify an exit point name, and entities can be repositioned to that point.

• Exit Points register themselves with the Stage Manager by name via RegisterExitPoint.
• One Exit Point can be flagged as Default — it serves as the fallback if no specific exit point is requested.
• Call GetExitPoint(exitName) to retrieve the entity at a named position.

Setup

Image showing the Manager wrapper entity set as Editor-Only inside Prefab Edit Mode.

1. Create an entity. Attach the GS_StageManagerComponent to it.
2. Configure the Stages list — add an entry for each level (stage name + spawnable prefab reference).
3. Set the Default Stage to your starting level. This name must also exist in the Stages list.
4. Turn the entity into a prefab.
5. Enter prefab edit mode. Set the wrapper entity (parent) to Editor Only. Save.
6. Delete the Stage Manager entity from the level.
7. In the Game Manager prefab, add the Stage Manager .spawnable to the Startup Managers list.

Inspector Properties

API Reference

Request Bus: StageManagerRequestBus

The primary interface for level navigation. Singleton bus — call via Broadcast.

Notification Bus: StageManagerNotificationBus

Connect to this bus to react to level loading events.

Local / Virtual Methods

These methods are available when extending the Stage Manager.

Usage Examples

Changing Stages

#include <GS_Core/GS_CoreBus.h>

// Load "ForestVillage" and place the player at the "main_entrance" exit point
GS_Core::StageManagerRequestBus::Broadcast(
    &GS_Core::StageManagerRequestBus::Events::ChangeStageRequest,
    AZStd::string("ForestVillage"),
    AZStd::string("main_entrance")
);

Getting an Exit Point Entity

#include <GS_Core/GS_CoreBus.h>

AZ::EntityId exitEntity;
GS_Core::StageManagerRequestBus::BroadcastResult(
    exitEntity,
    &GS_Core::StageManagerRequestBus::Events::GetExitPoint,
    AZStd::string("cave_exit")
);

if (exitEntity.IsValid())
{
    // Reposition the player entity to the exit point's transform
}

Listening for Stage Load Events

#include <GS_Core/GS_CoreBus.h>

class MyLoadScreenComponent
    : public AZ::Component
    , protected GS_Core::StageManagerNotificationBus::Handler
{
protected:
    void Activate() override
    {
        GS_Core::StageManagerNotificationBus::Handler::BusConnect();
    }

    void Deactivate() override
    {
        GS_Core::StageManagerNotificationBus::Handler::BusDisconnect();
    }

    void BeginLoadStage() override
    {
        // Show loading screen, disable player input
    }

    void LoadStageComplete() override
    {
        // Hide loading screen, enable player input
    }

    void StageLoadProgress(float progress) override
    {
        // Update loading bar: progress is 0.0 to 1.0
    }
};

Script Canvas

Changing stages:

Getting an exit point:

Extending the Stage Manager

Extend the Stage Manager when you need custom stage transition logic, procedural level generation, or multi-stage loading.

Header (.h)

#pragma once
#include <Source/StageManager/GS_StageManagerComponent.h>

namespace MyProject
{
    class MyStageManagerComponent
        : public GS_Core::GS_StageManagerComponent
    {
    public:
        AZ_COMPONENT_DECL(MyStageManagerComponent);

        static void Reflect(AZ::ReflectContext* context);

    protected:
        // Override stage change behavior
        void ChangeStage(AZStd::string stageName, AZStd::string exitName) override;
        void ContinueLoadStage() override;
    };
}

Implementation (.cpp)

#include "MyStageManagerComponent.h"
#include <AzCore/Serialization/SerializeContext.h>

namespace MyProject
{
    AZ_COMPONENT_IMPL(MyStageManagerComponent, "MyStageManagerComponent", "{YOUR-UUID-HERE}",
        GS_Core::GS_StageManagerComponent);

    void MyStageManagerComponent::Reflect(AZ::ReflectContext* context)
    {
        if (auto serializeContext = azrtti_cast<AZ::SerializeContext*>(context))
        {
            serializeContext->Class<MyStageManagerComponent, GS_Core::GS_StageManagerComponent>()
                ->Version(0);

            if (AZ::EditContext* editContext = serializeContext->GetEditContext())
            {
                editContext->Class<MyStageManagerComponent>(
                    "My Stage Manager", "Custom stage manager with transition effects")
                    ->ClassElement(AZ::Edit::ClassElements::EditorData, "")
                        ->Attribute(AZ::Edit::Attributes::Category, "MyProject")
                        ->Attribute(AZ::Edit::Attributes::AppearsInAddComponentMenu, AZ_CRC_CE("Game"));
            }
        }
    }

    void MyStageManagerComponent::ChangeStage(AZStd::string stageName, AZStd::string exitName)
    {
        // Example: trigger a fade-out transition before changing stages
        // ... your transition logic ...

        // Call base to perform the actual stage change
        GS_StageManagerComponent::ChangeStage(stageName, exitName);
    }

    void MyStageManagerComponent::ContinueLoadStage()
    {
        // Call base to connect to Stage Data and start level activation
        GS_StageManagerComponent::ContinueLoadStage();

        // Example: trigger a fade-in transition after loading
        // ... your transition logic ...
    }
}

Module Registration

m_descriptors.insert(m_descriptors.end(), {
    MyProject::MyStageManagerComponent::CreateDescriptor(),
});

Then create a prefab for your custom Stage Manager and add it to the Game Manager’s Startup Managers list (replacing the default).

See Also

For component references:

• Stage Data
• Game Manager
• Save Manager
• Manager

For related resources:

• Templates

Get GS_Core

GS_Core — Explore this gem on the product page and add it to your project.

1.3.2 - Stage Data

The Stage Data component is the anchor that connects the Stage Manager to a loaded level. It holds level-specific configuration — stage name, NavMesh reference, priority layers — and runs the staged activation sequence that brings the level online incrementally rather than all at once.

Every level that loads through the Stage Manager should have exactly one Stage Data component at the root of its prefab hierarchy.

For usage guides and setup examples, see The Basics: GS_Core.

Contents

• How It Works
• Setup
• Inspector Properties
• API Reference
• Usage Examples
• Extending the Stage Data Component
• See Also

How It Works

Connection

When the Stage Manager spawns a stage prefab, it queries the level for the Stage Data component via StageDataRequestBus. The Stage Data returns its reference, and the Stage Manager hands off the startup process.

Staged Activation

Rather than activating every entity in the level at once (which would cause a massive frame spike), the Stage Data component supports priority-based activation:

1. SetUpStage() — Initial stage configuration. Sets up references, connects internal systems.
2. ActivateByPriority — Entities tagged with priority layers activate in sequence, spreading heavy initialization across multiple frames. This allows NavMesh generation, procedural content, and complex entity hierarchies to spin up without blocking the main thread.
3. LoadStageComplete — The Stage Manager broadcasts this once all priority layers have finished and the level is fully ready.

NavMesh Integration

The Stage Data component holds a reference to the level’s Recast NavMesh entity. This allows the Stage Manager to trigger NavMesh generation at the appropriate point during the startup sequence — after the level geometry is loaded but before AI systems begin pathfinding.

Setup

1. In your level prefab, create an entity at the root level.
2. Attach the GS_StageDataComponent to it.
3. Set the Stage Name to match the name used in the Stage Manager’s Stages list.
4. Assign the NavMesh entity reference if your level uses Recast Navigation.
5. Configure priority layers for incremental entity activation if needed.

Inspector Properties

API Reference

Request Bus: StageDataRequestBus

Used by the Stage Manager to connect to and control the level’s startup.

Notification Bus: StageDataNotificationBus

Connect to this bus for level-specific lifecycle events.

Local / Virtual Methods

These methods are available when extending the Stage Data component.

Usage Examples

Listening for Stage Events in a Level Component

#include <GS_Core/GS_CoreBus.h>

class MyLevelController
    : public AZ::Component
    , protected GS_Core::StageDataNotificationBus::Handler
{
protected:
    void Activate() override
    {
        GS_Core::StageDataNotificationBus::Handler::BusConnect();
    }

    void Deactivate() override
    {
        GS_Core::StageDataNotificationBus::Handler::BusDisconnect();
    }

    void OnBeginSetUpStage() override
    {
        // Level setup is starting — initialize level-specific systems
    }

    void OnLoadStageComplete() override
    {
        // Level is fully ready — spawn enemies, start ambient audio, etc.
    }

    void OnTearDownStage() override
    {
        // Level is being unloaded — clean up level-specific resources
    }
};

Priority-Based Activation

#include <GS_Core/GS_CoreBus.h>

class MyPriorityActivator
    : public AZ::Component
    , protected GS_Core::StageDataNotificationBus::Handler
{
    int m_myPriority = 2; // Activate during priority layer 2

protected:
    void Activate() override
    {
        GS_Core::StageDataNotificationBus::Handler::BusConnect();
    }

    void Deactivate() override
    {
        GS_Core::StageDataNotificationBus::Handler::BusDisconnect();
    }

    void ActivateByPriority(int priority) override
    {
        if (priority == m_myPriority)
        {
            // This is our turn — initialize heavy resources
            // (procedural generation, AI setup, physics volumes, etc.)
        }
    }
};

Script Canvas

Getting stage name and NavMesh reference:

Extending the Stage Data Component

Extend Stage Data when you need custom level startup sequences, procedural generation hooks, or level-specific configuration.

Header (.h)

#pragma once
#include <Source/StageManager/GS_StageDataComponent.h>

namespace MyProject
{
    class MyStageDataComponent
        : public GS_Core::GS_StageDataComponent
    {
    public:
        AZ_COMPONENT_DECL(MyStageDataComponent);

        static void Reflect(AZ::ReflectContext* context);

    protected:
        // Override to add custom stage setup
        bool SetUpStage() override;
        void LoadStageComplete() override;

    private:
        bool m_enableProceduralContent = false;
    };
}

Implementation (.cpp)

#include "MyStageDataComponent.h"
#include <AzCore/Serialization/SerializeContext.h>

namespace MyProject
{
    AZ_COMPONENT_IMPL(MyStageDataComponent, "MyStageDataComponent", "{YOUR-UUID-HERE}",
        GS_Core::GS_StageDataComponent);

    void MyStageDataComponent::Reflect(AZ::ReflectContext* context)
    {
        if (auto serializeContext = azrtti_cast<AZ::SerializeContext*>(context))
        {
            serializeContext->Class<MyStageDataComponent, GS_Core::GS_StageDataComponent>()
                ->Version(0)
                ->Field("EnableProceduralContent", &MyStageDataComponent::m_enableProceduralContent);

            if (AZ::EditContext* editContext = serializeContext->GetEditContext())
            {
                editContext->Class<MyStageDataComponent>(
                    "My Stage Data", "Custom stage data with procedural generation support")
                    ->ClassElement(AZ::Edit::ClassElements::EditorData, "")
                        ->Attribute(AZ::Edit::Attributes::Category, "MyProject")
                        ->Attribute(AZ::Edit::Attributes::AppearsInAddComponentMenu, AZ_CRC_CE("Game"))
                    ->DataElement(AZ::Edit::UIHandlers::Default,
                        &MyStageDataComponent::m_enableProceduralContent,
                        "Enable Procedural Content",
                        "Generate procedural content during stage setup");
            }
        }
    }

    bool MyStageDataComponent::SetUpStage()
    {
        if (m_enableProceduralContent)
        {
            // Run procedural generation for this level
            // ... your generation logic ...
        }

        // Call base to continue the standard setup sequence
        return GS_StageDataComponent::SetUpStage();
    }

    void MyStageDataComponent::LoadStageComplete()
    {
        // Custom post-load behavior
        // ... your logic ...

        GS_StageDataComponent::LoadStageComplete();
    }
}

Module Registration

m_descriptors.insert(m_descriptors.end(), {
    MyProject::MyStageDataComponent::CreateDescriptor(),
});

Use your custom Stage Data component in level prefabs instead of the default GS_StageDataComponent.

See Also

For component references:

• Stage Manager
• Game Manager

For related resources:

• Templates

Get GS_Core

GS_Core — Explore this gem on the product page and add it to your project.

1.4 - GS_Options

The Options system is the central pillar for handling background systemic configuration. At its simplest, it lets you set up user-facing options like volume, graphics settings, subtitles, and other standard configurable settings. Beyond that, it manages development-side functionality — language settings, current input device type, and other runtime-aware systems — providing that data to hook components throughout the game.

Currently, the Options system’s primary feature is the Input Profile system, which replaces O3DE’s raw input binding files with a more flexible, group-based approach that supports runtime rebinding and per-group enable/disable toggling.

For usage guides and setup examples, see The Basics: GS_Core.

Contents

• Components
• Quick Start
• See Also

Components

Quick Start

1. Create an Options Manager prefab with the GS_OptionsManagerComponent.
2. Create a GS_InputProfile data asset in the Asset Editor.
3. Add input groups and event mappings to the profile.
4. Assign the Input Profile to the Options Manager.
5. Add the Options Manager .spawnable to the Game Manager’s Startup Managers list.
6. Attach GS_InputReaderComponents to entities that need to process input.

See Also

For conceptual overviews and usage guides:

• The Basics: GS_Options

For component references:

• Options Manager
• Input Profiles

For related resources:

• Game Manager

Get GS_Core

GS_Core — Explore this gem on the product page and add it to your project.

1.4.1 - Options Manager

For usage guides and setup examples, see The Basics: GS_Core.

Image showing the Options Manager component, as seen in the Entity Inspector.

The Options Manager is the central anchor of the Options system. It holds the active Input Profile data asset and provides it to Input Readers and other game systems that need runtime configuration data.

As a Manager, it is spawned by the Game Manager and participates in the standard two-stage initialization lifecycle.

Contents

• How It Works
• Setup
• Inspector Properties
• API Reference
• Usage Examples
• Extending the Options Manager
• See Also

How It Works

1. The Options Manager initializes during the Game Manager’s startup sequence.
2. It loads the configured Input Profile data asset.
3. Input Readers across the game query the Options Manager for the active profile via OptionsManagerRequestBus.
4. The Options Manager responds to standby events — pausing and resuming input processing when the game enters or exits standby mode.

Setup

Image showing the Manager wrapper entity set as Editor-Only inside Prefab Edit Mode.

1. Create an entity. Attach the GS_OptionsManagerComponent to it.
2. Assign your Input Profile data asset.
3. Turn the entity into a prefab.
4. Enter prefab edit mode. Set the wrapper entity (parent) to Editor Only. Save.
5. Delete the Options Manager entity from the level.
6. In the Game Manager prefab, add the Options Manager .spawnable to the Startup Managers list.

Inspector Properties

API Reference

Request Bus: OptionsManagerRequestBus

Singleton bus — call via Broadcast.

Lifecycle Events (from GameManagerNotificationBus)

Usage Examples

Getting the Active Input Profile

#include <GS_Core/GS_CoreBus.h>

AZ::Data::Asset<GS_Core::GS_InputProfile> profile;
GS_Core::OptionsManagerRequestBus::BroadcastResult(
    profile,
    &GS_Core::OptionsManagerRequestBus::Events::GetActiveInputProfile
);

if (profile.IsReady())
{
    // Use the profile to look up bindings, check group states, etc.
}

Extending the Options Manager

Extend the Options Manager when you need additional runtime settings (graphics quality, audio levels, accessibility), custom options persistence, or platform-specific configuration.

Header (.h)

#pragma once
#include <Source/OptionsSystem/GS_OptionsManagerComponent.h>

namespace MyProject
{
    class MyOptionsManagerComponent
        : public GS_Core::GS_OptionsManagerComponent
    {
    public:
        AZ_COMPONENT_DECL(MyOptionsManagerComponent);

        static void Reflect(AZ::ReflectContext* context);

    protected:
        void OnStartupComplete() override;

    private:
        float m_masterVolume = 1.0f;
        int m_graphicsQuality = 2; // 0=Low, 1=Med, 2=High
    };
}

Implementation (.cpp)

#include "MyOptionsManagerComponent.h"
#include <AzCore/Serialization/SerializeContext.h>

namespace MyProject
{
    AZ_COMPONENT_IMPL(MyOptionsManagerComponent, "MyOptionsManagerComponent", "{YOUR-UUID-HERE}",
        GS_Core::GS_OptionsManagerComponent);

    void MyOptionsManagerComponent::Reflect(AZ::ReflectContext* context)
    {
        if (auto serializeContext = azrtti_cast<AZ::SerializeContext*>(context))
        {
            serializeContext->Class<MyOptionsManagerComponent, GS_Core::GS_OptionsManagerComponent>()
                ->Version(0)
                ->Field("MasterVolume", &MyOptionsManagerComponent::m_masterVolume)
                ->Field("GraphicsQuality", &MyOptionsManagerComponent::m_graphicsQuality);

            if (AZ::EditContext* editContext = serializeContext->GetEditContext())
            {
                editContext->Class<MyOptionsManagerComponent>(
                    "My Options Manager", "Extended options with audio and graphics settings")
                    ->ClassElement(AZ::Edit::ClassElements::EditorData, "")
                        ->Attribute(AZ::Edit::Attributes::Category, "MyProject")
                        ->Attribute(AZ::Edit::Attributes::AppearsInAddComponentMenu, AZ_CRC_CE("Game"))
                    ->DataElement(AZ::Edit::UIHandlers::Slider,
                        &MyOptionsManagerComponent::m_masterVolume, "Master Volume", "Global audio volume")
                        ->Attribute(AZ::Edit::Attributes::Min, 0.0f)
                        ->Attribute(AZ::Edit::Attributes::Max, 1.0f)
                    ->DataElement(AZ::Edit::UIHandlers::ComboBox,
                        &MyOptionsManagerComponent::m_graphicsQuality, "Graphics Quality", "Rendering quality preset");
            }
        }
    }

    void MyOptionsManagerComponent::OnStartupComplete()
    {
        // Apply saved options on startup
        // ... load from save system and apply settings ...

        GS_OptionsManagerComponent::OnStartupComplete();
    }
}