Level Designer & Artist Guide (Zero-Code Persistence)

This guide is written specifically for Level Designers, Environment Artists, Technical Artists, and Blueprint Scripters.

You do not need to write C++, pack binary buffers, or understand low-level serialization to make interactive world objects persist. With Aegis Save, making a placed door, a flickering streetlamp, a puzzle lever, or a loot chest remember its state takes less than 60 seconds directly in the Details panel.

---

1. Persisting a Placed Actor in 3 Steps

Suppose you placed an interactive door (BP_DungeonDoor), a torch, or a puzzle switch in your level:

[Select Actor in Viewport]
           │
           ▼
[Details Panel] ──► Click "+ Add Component" ──► Search "Aegis Persistence"
           │
           ▼
[Save Level Map (Ctrl + S)] ──► Aegis stamps a permanent 128-bit identity into the map!

Step 1: Add the Component

1. In the level viewport, click on the actor to select it.
2. In the Details panel on the right, click + Add.
3. Type Aegis Persistence and select it.

Step 2: Configure Details Panel Properties

Select the newly added Aegis Persistence component in the Details panel:

Property	Recommended Setting	Plain-English Explanation
Scope	World	Keeps this actor's state tied to this specific level map. (Always use World for placed map props).
Persist Transform	True (or False)	Set to True if the actor can move, rotate, open, or be knocked over by physics. If the actor never moves (e.g. a wall torch or a fixed switch), leave False to save memory.
Change Detection	Automatic	Leave on Automatic. Aegis will safely track changes without needing custom code.
Persistent ID	(Read-Only)	Do not touch. Aegis automatically generates and seeds this GUID when you save the level map.

Step 3: Save Your Level

Press Ctrl + S (or File $\rightarrow$ Save All).
Saving the map package establishes the actor's permanent identity in the world. That's it!

---

2. Making Variables Persist in Blueprint

If you created an Actor Blueprint with custom gameplay variables (e.g., bIsOpen, bIsLocked, RemainingFuel):

1. Open your Actor Blueprint.
2. In the My Blueprint panel on the left, select your variable.
3. In the Details panel on the right, look for the Advanced drop-down under Variable settings.
4. Check the SaveGame checkbox:

Variable Name:   bIsOpen
Variable Type:   Boolean
[x] Editable
[x] SaveGame  <-- CHECK THIS BOX!

5. Compile and Save the Blueprint.

Now, whenever an autosave or manual save occurs, Aegis automatically captures this variable and restores it when loading!

---

3. Ready-to-Use Prop Catalog (5 Common Props)

Here is how to set up the 5 most common interactive assets level designers place in worlds:

Prop 1: Interactive Sliding or Swinging Door

• Root Component Mobility: Set to Movable (under Transform in Details).
• Aegis Persistence Component:
  • Scope: World
  • Persist Transform: False (if door rotation is driven by a timeline or variable) OR True (if physics simulation).
• Variables to Tick SaveGame:
  • bIsOpen (Boolean)
  • bIsLocked (Boolean)
• On BeginPlay: If bIsOpen == true, set the door mesh rotation to open pose.

Prop 2: Torch, Streetlamp, or Campfire

• Root Component Mobility: Static or Stationary.
• Aegis Persistence Component:
  • Scope: World
  • Persist Transform: False (saving memory).
• Variables to Tick SaveGame:
  • bIsLit (Boolean)
  • LightIntensity (Float)
• On BeginPlay: If bIsLit == false, toggle light visibility and extinguish flame particle system.

Prop 3: Collectible Coin, Gem, or Secret Document

• Root Component Mobility: Movable or Static.
• Aegis Persistence Component:
  • Scope: World
  • Persist Transform: False.
• Variables to Tick SaveGame:
  • bIsCollected (Boolean)
• Collection Logic: When player overlaps:
  • Set bIsCollected = true.
  • Call SetActorHiddenInGame(true) and SetActorEnableCollision(false).
• On BeginPlay: If bIsCollected == true, call SetActorHiddenInGame(true) and SetActorEnableCollision(false) immediately.

Prop 4: Puzzle Switch, Lever, or Floor Pressure Plate

• Root Component Mobility: Movable.
• Aegis Persistence Component:
  • Scope: World
  • Persist Transform: False.
• Variables to Tick SaveGame:
  • bIsPressed (Boolean)
  • CurrentStepIndex (Integer)
• On BeginPlay: Update lever handle angle or plate height to match bIsPressed.

Prop 5: Destructible Crate or Exploding Barrel

• Root Component Mobility: Movable.
• Aegis Persistence Component:
  • Scope: World
  • Persist Transform: True.
• Variables to Tick SaveGame:
  • CurrentHealth (Float)
  • bIsDestroyed (Boolean)
• Destruction Logic: When destroyed by damage, call Destroy Actor. Aegis automatically records a Tombstone so this crate never respawns when loading!

---

4. How to Test Your Actor in 5 Seconds

You don't need to build custom menus or read raw log files to verify that your actor is saving correctly.

Method 1: Console Commands in PIE

1. Press Play in Editor (PIE).
2. Walk up to your door or switch and activate it (e.g. open the door).
3. Open the console (~ key) and type:

   Aegis.Save Slot1

4. Stop PIE (Esc).
5. Press Play again.
6. Open the console (~ key) and type:

   Aegis.Load Slot1

7. Observe your actor: The door will instantly adopt its opened state!

---

Method 2: The Get Persistence Report Node

Drop the Get Persistence Report node into your Blueprint (e.g. on a debug keypress like P):

[Keyboard: 'P'] ──► [Get Persistence Report (Target: Self)]
                          │
                          ▼
                    [Print String: "Is Captured = " + Entry.bIsCaptured]

It outputs a clean list showing:

• Every variable marked SaveGame.
• Whether each variable is actively being captured.
• Whether the actor's Transform and Attachment are being persisted.

---

5. Top 5 Artist Pitfalls (And How to Avoid Them)

1. The Mobility Trap (Static vs. Movable)

If you check Persist Transform = True on an actor that moves at runtime (e.g. a swinging door, a rolling boulder, or a floating platform), ensure that the actor's Root Component mobility is set to Movable!

• In Unreal Engine, Static meshes are baked into the level and cannot move at runtime.
• Set mobility to Movable in the Details panel under Transform.

2. The Transient Flag Trap

In the Blueprint variable settings, never check Transient on variables you want to save. In Unreal Engine, Transient strictly overrides SaveGame and discards the variable during saving!

3. Level Instances (Sub-Levels)

If you group multiple modular actors into a Level Instance (ALevelInstance):

• Add an Aegis Persistence component to the Level Instance actor itself in the main level.
• This allows Aegis to compose deterministic seed identities for all sub-actors inside the instance (C-83).

4. Spawning Actors at Runtime

• If you place an actor in the level editor, standard placement is persistent.
• If you spawn an actor dynamically using Blueprint nodes, do not use standard SpawnActor. Use Spawn Persistent Actor (Aegis) instead, or the spawned actor will vanish when you reload.

5. Never Copy-Paste Persistent ID Values

Never attempt to copy, paste, or hardcode the Persistent ID GUID string between different actors in the Details panel. Each actor must possess a unique identity, which Aegis assigns automatically when saving the map.

---

The 60-Second Level Designer Checklist

Before submitting your level map to version control, verify:

• [ ] Interactive props have UAegisPersistenceComponent attached.
• [ ] Props that move or rotate have root component set to Movable.
• [ ] Variables controlling visual pose (bIsOpen, bIsLit) have SaveGame ticked.
• [ ] The level was saved with Ctrl + S so Aegis generated valid GUID identities.
• [ ] Verified state persistence in PIE using Aegis.Save Slot1 and Aegis.Load Slot1.

---

Next Steps

• Learn how saving fits into the full game loop in Complete Game Flow & Level Transitions.
• See how to build an interactive chest in Recipe 1: Interactive Loot Chest.
• Learn about streaming safety in Recipe 3: World Partition Open World.