The First-Save Characteristic

To ensure complete transparency and prevent mismatched expectations (FO-13, P4), this guide explains how the very first save into a slot operates, why it differs fundamentally from all subsequent autosaves, and how to structure your game's saving flow for a seamless player experience.

1. Initial Save vs. Incremental Autosaves

Aegis Save achieves its signature sub-millisecond, hitch-free performance through Verbatim Bundle Reuse:

[Save Slot: Fresh Slot]
  │
  ├─► First Save (Full Write)
  │     └─► Must serialize EVERY persistent actor from scratch.
  │         (No previous file exists in this slot to reuse unchanged data from).
  │
  └─► All Subsequent Saves (Incremental Autosaves)
        └─► Copies unchanged data bundles VERBATIM at disk speed.
        └─► Spreads capture across frames under the 1.0 ms budget.
        └─► Completely non-blocking during active gameplay!

Why Does the First Save Write Everything?

When you save into a brand new slot name (e.g., "SaveSlot_01" for the first time), there is no existing .aegis container file on disk. Every resident persistent actor, component, transform, and tombstone in the level must be captured and written out.

Because an entire world is being initialized from scratch, this initial save may take several seconds in massive worlds with thousands of persistent actors:

In a world with 5,400 resident actors, the initial unprimed write takes ~449 frames (~7.5 seconds at 60 fps).
In a massive world with 10,000 resident actors, the initial unprimed write takes ~962 frames (~16.0 seconds at 60 fps).

Mandatory Disclosure (FO-13)

The initial save into any new slot writes every persistent record in the world and may block the game thread. This is a deliberate architectural characteristic, not a defect. Once this baseline file is established, all subsequent autosaves into that slot are incremental and obey your configured per-frame budget.

2. Best Practices: When to Trigger the First Save

Because the first save writes the full world baseline, game designers should trigger it during natural pauses in gameplay rather than mid-combat:

1. The End of Character Creation / Tutorial Intro

When a player finishes customizing their character, choosing a class, or completing the introductory cutscene, trigger the first save while the screen fades to black or during the intro cutscene transition:

text

[Character Creation UI: "Begin Journey"]
       │
       ▼
[Fade Camera to Black (1.0s)]
       │
       ▼
[Save Game (Aegis): "SaveSlot01"] ──► [Wait for OnSuccess]
       │
       ▼
[Load Gameplay Map / Unfade Camera]

2. Level Transitions & Loading Screens

When traveling between maps, entering a dungeon, or crossing a World Partition level boundary, trigger the save before unhiding the player or while the loading screen / transition fade is actively displayed.

3. Checkpoint Gates with Controlled Delays

If you initialize a save slot during gameplay, pair it with a brief interactive sequence (e.g., resting at a campfire, opening a major vault door, or entering a safe zone) where a brief pause feels completely organic.

3. What Happens During Subsequent Saves?

Once a slot has been initialized:

Verbatim Bundle Reuse: The storage engine identifies which actors did not change state. Unchanged bundles are copied verbatim directly from the old container to the new container without re-serializing properties or re-compressing payloads.
Bounded Frame Execution: Capture advances incrementally across multiple frames under your configured FrameBudgetMilliseconds (default 1.0 ms).
Player Observability: The player experiences 0 frame drops, zero micro-stutter, and consistent 60+ FPS gameplay.

4. Measuring First-Save Cost in Your Project

Because every project has different actor populations and property payloads, you should measure your project's exact first-save wall using the shipped benchmark suite:

powershell

# Run benchmark against your map
UnrealEditor-Cmd.exe YourProject.uproject /Game/Maps/YourMap -game -nullrhi -nosound -unattended -AegisBenchmarkExit -ExecCmds="Aegis.Benchmark.Run 1000 0.02 1.0" -abslog="Saved/Logs/Bench.log"

The output log will report:

text

AEGIS_BENCHMARK_RESULT ... priming_wall_frames=XX ...

This tells you the exact number of frames required to prime a fresh save slot in your game.

Next Steps

Explore the Core Architecture to see how the subsystem, scheduler, and storage engine coordinate.
Learn about Making Saves Cheap to optimize subsequent incremental autosaves down to microseconds.

The First-Save Characteristic ​

1. Initial Save vs. Incremental Autosaves ​

Why Does the First Save Write Everything? ​

2. Best Practices: When to Trigger the First Save ​

1. The End of Character Creation / Tutorial Intro ​

2. Level Transitions & Loading Screens ​

3. Checkpoint Gates with Controlled Delays ​

3. What Happens During Subsequent Saves? ​

4. Measuring First-Save Cost in Your Project ​

Next Steps ​