Recipe 4: Procedural & Dynamic Runtime Spawning

This recipe demonstrates how to spawn actors dynamically during gameplay—such as dropped player weapons, constructed campfires, or dynamic vehicles—and have them survive save and load cycles seamlessly.

---

1. Standard SpawnActor vs. SpawnPersistentActor

Spawning Method	Persistence Behavior	On Save Load
GetWorld()->SpawnActor	Transient only.	Disappears completely! (Unreal Engine does not recreate spawned actors).
Aegis->SpawnPersistentActor	Fully Persistent.	Re-instantiated and restored! Aegis respawns the class, assigns its saved identity, and restores properties.

Never Use Standard SpawnActor for Persistent Entities

Attaching a UAegisPersistenceComponent to a dynamically spawned actor is not enough on its own if spawned via native SpawnActor. You must spawn it through Spawn Persistent Actor so Aegis knows how to reconstruct the instance on load.

---

2. Recipe: Droppable Weapon in the World

Let's build a droppable weapon actor (BP_DroppedWeapon) that a player can drop onto the ground. It persists its location, remaining ammo, and durability.

Step 1: The Dropped Item Blueprint

1. Create an Actor Blueprint named BP_DroppedWeapon.
2. Add a StaticMeshComponent (simulate physics enabled).
3. Add UAegisPersistenceComponent (Scope = World, bPersistTransform = True).
4. Add variables with SaveGame ticked:
   • WeaponID (Name, e.g. "AssaultRifle_Tier2")
   • CurrentAmmo (Integer)
   • Durability (Float)

---

3. Spawning the Actor in Blueprint

When the player drops an item from their inventory menu:

[Custom Event: OnDropItemFromInventory]
  ├── ItemClass: BP_DroppedWeapon
  ├── DropLocation: (PlayerLocation + ForwardVector * 100)
  └── DropRotation: (ActorRotation)
               │
               ▼
[Spawn Persistent Actor (Aegis)]
  ├── Class: BP_DroppedWeapon
  ├── Transform: (Location & Rotation)
  └── Return Value ──► [Set WeaponID = "AssaultRifle_Tier2"]
                   ──► [Set CurrentAmmo = 30]
                   ──► [Set Durability = 95.5]

That's it! When you save and reload the slot, Aegis automatically re-instantiates BP_DroppedWeapon at that exact spot with 30 ammo and 95.5 durability.

---

4. Spawning the Actor in C++

Here is how to spawn persistent actors using C++:

#include "Core/AegisSubsystem.h"
#include "Items/DroppedWeapon.h"

void AMyPlayerCharacter::DropEquippedWeapon()
{
    UAegisSubsystem* Aegis = UAegisSubsystem::Get(this);
    if (!Aegis)
    {
        return;
    }

    const FTransform DropTransform = GetActorTransform() + FTransform(FVector(100.0f, 0.0f, 0.0f));

    // Spawn through Aegis Subsystem:
    ADroppedWeapon* SpawnedWeapon = Aegis->SpawnPersistentActor<ADroppedWeapon>(
        ADroppedWeapon::StaticClass(),
        DropTransform
    );

    if (SpawnedWeapon)
    {
        SpawnedWeapon->WeaponID = CurrentEquippedID;
        SpawnedWeapon->CurrentAmmo = CurrentEquippedAmmo;
        SpawnedWeapon->Durability = CurrentEquippedDurability;
    }
}

---

5. Preventing Tombstone Leaks on Destruction (R-12)

When a player walks over to the dropped weapon and picks it back up, you call Destroy() on the dropped weapon actor.

How Aegis Prevents File Bloat

• In some naive save plugins, destroying any actor writes a tombstone into the save file. Over a 100-hour game where thousands of items are dropped and picked up, thousands of dead tombstones accumulate, ballooning save file size.
• Aegis Save handles this automatically (R-12): Because the actor was spawned via SpawnPersistentActor, its component is marked with bIsRuntimeSpawned = true.
• When destroyed, its record is completely erased from the save store instead of leaving a tombstone. Save files stay lean, lightweight, and fast!

---

Summary Checklist

• [x] Use Spawn Persistent Actor (Blueprint) or Aegis->SpawnPersistentActor (C++).
• [x] Tag all variables that represent item state with SaveGame.
• [x] Enable bPersistTransform so physical landing positions are captured.
• [x] Pick up / destroy normally via Destroy() — Aegis will clean up the record with 0 tombstone bloat!