How-To: Persist a Level Actor

Goal: go beyond the basics and control how a saveable level actor behaves when it is destroyed - stay gone, or respawn from the level - and understand the runtime-vs-placed distinction.

Prerequisites
You've done Quick Start: World Actors - the actor implements ICrimsonSaveableActor and its state is marked SaveGame. An active save slot exists. This page picks up from there.

Implementing ICrimsonSaveableActor and marking fields SaveGame is the whole opt-in - see Quick Start: World Actors for the images and code. Everything below is optional refinement on top of that.

1. Give the actor a stable identity

Add a Crimson Persistent Id component to the actor. It has no settings and nothing to wire: in the editor it copies the actor's engine-assigned ActorGuid into a normal property, so the identity your saved state is filed under still exists in a packaged build - the engine's own copy is editor-only and does not. ACrimsonPersistentActor already carries one.

  1. Open the actor Blueprint and press Add Component.
  2. Pick Crimson Persistent Id. There is nothing to configure - the Persistent Id field is read-only and fills itself in.
  3. Save the level. The id is written then, so an actor placed but not yet saved still shows an empty id.
Skip this and a reused object name can hand your state to the wrong actor
Without the component the actor is identified by its authored object path instead. That is stable against renaming the level, World Partition re-gridding and cooking - but not against object-name reuse, which Unreal allows in any level that is not One File Per Actor. Delete StaticMeshActor_3 there and the next actor to take that name inherits its saved state. World Partition levels are immune; classic sublevels are not.

2. Destruction is tracked automatically

The world subsystem listens for actor destruction on the server (including Destroy() and lifespan expiry), so a deleted saveable actor stays deleted with no manual call. A runtime-spawned actor simply has its save entry removed. A placed (level) actor reloads from the map every session, so a tiny GUID-only tombstone is written to keep it gone.

No manual call needed
You don't need to call anything when a saveable actor is destroyed - the automatic handler covers collected pickups, expired projectiles, and anything else that calls Destroy(). OnActorDestroyed(this) is an optional manual hook, for when you want the deletion recorded at a precise moment rather than whenever the actor is actually destroyed. See the full matrix in Concept: World State & Identity.

3. (Optional) Let a destroyed placed actor respawn

By default a destroyed placed actor never comes back. To make it respawn from the level after deletion instead, override ShouldRespawnAfterDestroyed to return true. (Runtime-spawned actors ignore this - once destroyed they simply stop being saved.)

In the actor Blueprint, open My Blueprint -> Interfaces and double-click Should Respawn After Destroyed - it is listed there as soon as Crimson Saveable Actor is implemented. That opens its function graph: tick the Return Node's Boolean output so the function returns true, then compile.

Nothing else is wired. The world subsystem reads the value at capture time to decide whether to leave a tombstone for the actor or let the level re-place it on the next load.

Verify
Default (false): destroy the actor, save, reload - it stays gone, and the save file does not grow for runtime actors. With the override returning true, a destroyed placed actor is back after reload.
Multiplayer: SaveGame is not Replicated
The value is restored on the server only; clients see it only if the property is also Replicated (or RepNotify). Full explanation: Concept: Multiplayer & Save Scopes.

See also

  • How-To: Save Cross-Object References - persist pointers between saved actors
  • How-To: Configure Auto-Saving - control when world state is captured and flushed
  • Concept: World State & Identity - the capture, identity, and deletion model