The Per-Frame Budget

Aegis Save guarantees that background autosaves never hitch your gameplay by enforcing a strict, configurable execution time ceiling per frame (FrameBudgetMilliseconds, default 1.0 ms).

This guide details how the scheduler slices capture passes across frames, the architectural trade-off of incremental consistency (P-21), and the one documented scenario where a frame may exceed the budget (FO-16).

---

1. How the Incremental Scheduler Works

When an Incremental save is triggered (such as via the Auto Save node):

Frame 1 (Tick): [Gameplay: 14.5 ms] ──► [Aegis: 0.95 ms (Capture Batch A)] ──► Total: 15.45 ms (< 16.6 ms @ 60 FPS)
Frame 2 (Tick): [Gameplay: 14.2 ms] ──► [Aegis: 0.88 ms (Capture Batch B)] ──► Total: 15.08 ms (< 16.6 ms @ 60 FPS)
Frame 3 (Tick): [Gameplay: 14.6 ms] ──► [Aegis: 0.92 ms (Capture Batch C)] ──► Total: 15.52 ms (< 16.6 ms @ 60 FPS)
Frame 4:        All actors captured! Offload compression & disk write to background worker thread.

1. During each engine frame tick, the Aegis scheduler wakes up and reads resident persistent actors.
2. It tracks high-resolution wall-clock microseconds.
3. Once the accumulated time reaches FrameBudgetMilliseconds (1.0 ms), the scheduler immediately yields execution back to the engine until the next frame.
4. Heavy payload compression (Oodle Kraken) and file writing run entirely on background worker threads, never touching the Game Thread.

---

2. The Incremental Consistency Contract (P-21)

Spreading a save across multiple frames introduces an important engineering consideration:

The Consistency Trade-off (P-21)

Because records are read over multiple frames, an Incremental save represents a spread capture across that time window rather than a single frozen instant. If Actor A mutates on Frame 1 after it was read, and Actor B mutates on Frame 3 before it was read, the save will contain Actor A's pre-mutation state alongside Actor B's post-mutation state.

When to Use Incremental vs. Atomic

• Use Incremental for Autosaves: For background checkpoints, autosaves, and periodic world updates, this trade-off is ideal: player immersion is completely preserved with zero frame drops.
• Use Atomic for Manual Player Saves: When a player explicitly opens the pause menu and clicks "Save Game", use Atomic mode. Atomic mode captures the entire world in a single call, guaranteeing a 100% frozen point-in-time snapshot.

---

3. The Mass-Mutation Exception (FO-16)

While scheduled background capture strictly adheres to the 1.0 ms ceiling, there is one documented exception:

Mandatory Disclosure (FO-16)

If an actor mutates during an active capture pass, Aegis performs Immediate Capture-on-Write on that actor to prevent torn world state. A single frame that mutates dozens or hundreds of actors simultaneously (e.g. demolishing a huge building, chain explosions, or mass teleports) can temporarily exceed FrameBudgetMilliseconds.

How to Handle Mass Mutations

If your game has events that mutate hundreds of persistent actors at once:

1. Spread the Mutations: Stagger demolition debris or explosion chains across 2 to 3 frames rather than triggering all actor destructions in a single tick.
2. Trigger First: If an event like a major cutscene or level boss defeat mutates dozens of actors, let the event finish before triggering an autosave.

---

4. Configuring the Budget

You can tune the budget globally in Edit → Project Settings → Plugins → Aegis Save:

[/Script/AegisSave.AegisSettings]
; Per-frame capture budget in milliseconds (default 1.0)
FrameBudgetMilliseconds=1.000000

; Default mode for SaveGame calls (Atomic or Incremental)
DefaultSnapshotMode=Atomic

You can also override the budget dynamically per save call by passing an FAegisSaveOptions struct to the Auto Save or Save Game nodes.

---

Next Steps

• Inspect measured performance proof in Benchmarks & Reproduction.
• Review all configuration options in Configuration & CVars.