GS_Save

GS_SaveManagerComponent (singleton, spawned by Game Manager)
  │
  ├── Manages save files via O3DE SaveData gem
  │     CoreSaveData file tracks all saves + metadata
  │     Individual save files store game state as JSON
  │
  ├── SaveManagerOutgoingEventBus
  │     Broadcasts OnSaveAll / OnLoadAll to all Savers
  │
  ├── GS_SaverComponent (base class, on any entity)
  │     Listens for global save/load events
  │     Calls BuildSaveData() → SaveData() to persist
  │     Calls LoadLocalData() → ProcessLoad() to restore
  │     │
  │     ├── BasicEntitySaverComponent (saves Transform)
  │     ├── BasicPhysicsEntitySaverComponent (saves Transform + Rigidbody)
  │     └── Your custom savers...
  │
  └── RecordKeeperComponent (extends GS_SaverComponent)
        Simple key-value records (string → int)
        Lives on the Save Manager prefab entity

1 - Save Manager

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

Overview

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.

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 SaveManagerIncomingEventBus 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 SaveManagerOutgoingEventBus.
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: SaveManagerIncomingEventBus

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

Notification Bus: SaveManagerOutgoingEventBus

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::SaveManagerIncomingEventBus::BroadcastResult(
    allocator,
    &GS_Core::SaveManagerIncomingEventBus::Events::GetAllocator
);

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

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

Loading Data into a Component

#include <GS_Core/GS_CoreBus.h>

rapidjson::Value outData;
bool found = false;
GS_Core::SaveManagerIncomingEventBus::BroadcastResult(
    found,
    &GS_Core::SaveManagerIncomingEventBus::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::SaveManagerIncomingEventBus::BroadcastResult(
    hasSave,
    &GS_Core::SaveManagerIncomingEventBus::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::SaveManagerIncomingEventBus::BroadcastResult(
    saves,
    &GS_Core::SaveManagerIncomingEventBus::Events::GetOrderedSaveList
);

for (const auto& [name, epoch] : saves)
{
    AZStd::string readable;
    GS_Core::SaveManagerIncomingEventBus::BroadcastResult(
        readable,
        &GS_Core::SaveManagerIncomingEventBus::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

• Game Manager — Drives New Game / Load Game / Continue flows
• Savers — Entity-level save handlers that plug into global save/load events
• Record Keeper — Lightweight key-value records for progression
• Manager — Base class lifecycle pattern
• Templates — Starter files for custom save components

2 - Savers

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

Overview

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.

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 SaveManagerOutgoingEventBus:

#include <GS_Core/GS_CoreBus.h>

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

    void Deactivate() override
    {
        GS_Core::SaveManagerOutgoingEventBus::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

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::SaveManagerIncomingEventBus::BroadcastResult(
            allocator,
            &GS_Core::SaveManagerIncomingEventBus::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

• Save Manager — Central save/load controller
• Record Keeper — Lightweight key-value records (no custom class needed)
• List of Savers — Pre-built saver components
• Templates — Starter files for custom savers

2.1 - List of Savers

Overview

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

• Savers — Base class documentation and extension guide
• Save Manager — Central save/load controller
• Record Keeper — Lightweight key-value records for simple progression data

3 - Record Keeper

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

Overview

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.

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 RecordKeeperIncomingEventBus.
3. On each call to SetRecord, the Record Keeper broadcasts RecordChanged on the RecordKeeperOutgoingEventBus 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: RecordKeeperIncomingEventBus

The primary interface for reading and writing records.

Notification Bus: RecordKeeperOutgoingEventBus

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::RecordKeeperIncomingEventBus::Broadcast(
    &GS_Core::RecordKeeperIncomingEventBus::Events::SetRecord,
    "quest_village_rescue",
    2
);

Reading a Record

#include <GS_Core/GS_CoreBus.h>

AZ::s32 questStage = 0;
GS_Core::RecordKeeperIncomingEventBus::BroadcastResult(
    questStage,
    &GS_Core::RecordKeeperIncomingEventBus::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::RecordKeeperIncomingEventBus::BroadcastResult(
    exists,
    &GS_Core::RecordKeeperIncomingEventBus::Events::HasRecord,
    "switch_bridge_01"
);

if (!exists)
{
    // First time encountering this switch — initialize it
    GS_Core::RecordKeeperIncomingEventBus::Broadcast(
        &GS_Core::RecordKeeperIncomingEventBus::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::RecordKeeperOutgoingEventBus::Handler
{
protected:
    void Activate() override
    {
        GS_Core::RecordKeeperOutgoingEventBus::Handler::BusConnect();
    }

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

    // RecordKeeperOutgoingEventBus
    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

See Also

• Save Manager — Central save/load controller
• Savers — Entity-level save handlers for complex data
• List of Savers — Pre-built saver components