Blueprint Node Reference

This document provides a comprehensive reference for every Blueprint node provided by Aegis Save. All nodes are categorized under Aegis|<Area> in the Blueprint context menu.

---

1. Saving & Loading Actions

These are asynchronous latent action nodes: they execute non-blocking passes and fire execution pins when finished.

Auto Save (Aegis)

• Category: Aegis|Slots
• Description: Spreads save capture across frames under FrameBudgetMilliseconds (default 1.0 ms). Recommended for all gameplay checkpoints and rolling autosaves.
• Inputs:
  • In Exec (Execution)
  • Slot Name (FString): Target save slot identifier.
  • Options (FAegisSaveOptions, Optional): Advanced options (DisplayName, PlaytimeSeconds, Budget override).
• Outputs:
  • OnSuccess (Execution): Fires when save completes successfully.
  • OnFailed (Execution): Fires on any error (read Status for details).
  • Status (FAegisStatus): Result code and human-readable context.

Save Game to Slot (Aegis)

• Category: Aegis|Slots
• Description: Saves world state to a slot. Defaults to Atomic mode (point-in-time synchronous snapshot). Recommended for manual save slots in pause menus.
• Inputs: Slot Name, Options.
• Outputs: OnSuccess, OnFailed, Status.

Load Game from Slot (Aegis)

• Category: Aegis|Slots
• Description: Loads the saved world state from a slot, restores actor properties, and destroys placed actors recorded as destroyed in that save.
• Inputs:
  • Slot Name (FString): Target slot to load.
  • Options (FAegisLoadOptions, Optional): Optional flags (e.g. bIgnoreBackup).
• Outputs: OnSuccess, OnFailed, Status.

---

2. Reading Operation Results (FAegisStatus)

Every save and load operation outputs an FAegisStatus struct:

• Result (EAegisResult): Enumeration representing the exact outcome.
• Context (FString): Descriptive string naming the exact object, property, or file at fault (A-7).

Common EAegisResult Codes

Result Code	Meaning	Recommended Handling
Success	Operation succeeded.	Proceed with game flow.
OperationInProgress	Another save or load is currently running.	Wait for running operation to complete; do not spam requests.
SlotNotFound	Target save slot does not exist on disk.	Verify slot exists using Does Slot Exist before loading.
InvalidSlotName	Slot name contains illegal characters or path traversal.	Validate slot name strings.
StorageReadFailed / StorageWriteFailed	Disk I/O error, full drive, or permission issue.	Display warning to player.
CorruptHeader / ChecksumMismatch	File failed CRC32 integrity check.	Check if .bak backup exists; offer backup restore to player.
MigrationFailed	Custom schema migration returned false.	Load was aborted atomically; original file is untouched.

---

3. Slot Management

Node	Kind	Returns	Description
Does Slot Exist	Pure	bool	Returns true if the .aegis file exists on disk.
Get Slot Info	Callable	FAegisStatus, FAegisSlotInfo	Reads metadata header of a single slot in sub-milliseconds.
Get All Slot Info	Callable	FAegisStatus, TArray<FAegisSlotInfo>	Reads metadata headers across all existing slots in the save directory.
Delete Slot	Callable	FAegisStatus	Deletes the .aegis container file and its companion .bak backup.

---

4. Actor Identity & Component Queries

Nodes available on UAegisPersistenceComponent:

Node	Kind	Returns	Description
Get Persistent Id	Pure	FGuid	Returns the actor's immutable 128-bit identity.
Has Valid Id	Pure	bool	True if the actor has a valid seeded GUID.
Get Scope	Pure	EAegisScope	Returns whether the actor is scoped to World, Player, or Global.
Should Persist Transform	Pure	bool	True if location, rotation, and scale are captured.
Get Change Detection	Pure	EAegisChangeDetection	Returns active detection mode (Automatic, Revision, Manual, Always).
Get Resolved Ancestor Count	Pure	int32	Number of parent Level Instances contributing to identity composition.

---

5. Non-Actor Persistence (UObjects)

Node	Category	Description
Make Persistent Id From Label	`Aegis	Identity`
Register Persistent Object	`Aegis	Identity`
Unregister Persistent Object	`Aegis	Identity`
Forget Record	`Aegis	Identity`

---

6. Spawning & Change Signaling

Spawn Persistent Actor (Aegis)

• Category: Aegis|Identity
• Description: Spawns an actor class dynamically with a persistent sequence identity stored in Global scope. Reconstructed automatically on save load.
• Inputs: Class, Transform, CollisionHandling.
• Outputs: Return Value (Actor reference).

Mark Changed (Aegis)

• Category: Aegis|Identity
• Description: Flags an actor or registered object as dirty, ensuring it will be captured on the next save pass.

---

7. Lifecycle & Diagnostics

Was Destroyed By Load (Aegis)

• Category: Aegis|Lifecycle
• Description: Pure. Call inside EndPlay to check if this actor was destroyed because a loaded save recorded it as dead. Use this to prevent duplicate death effects and loot drops!

Get Persistence Report (Aegis)

• Category: Aegis|Diagnostics
• Description: Inspects any actor or object and returns an array of FAegisPropertyReport entries, showing every variable marked SaveGame and whether it is actively captured (bIsCaptured).

Get Record Count / Get Live Actor Count

• Category: Aegis|Diagnostics
• Description: Pure. Get Record Count returns all records in memory (including streamed-out actors); Get Live Actor Count returns persistent actors currently resident in the world.

---

8. Subsystem Global Events

Bind to these events on UAegisSubsystem for game-wide notifications (e.g., autosave icons or audio chimes):

• On Save Started (SlotName)
• On Save Completed (SlotName, FAegisStatus)
• On Load Started (SlotName)
• On Load Completed (SlotName, FAegisStatus)