How-To: Save Cross-Object References

Goal: persist a pointer from one saved actor to another (a switch to the door it opens, an AI to its patrol anchor) so the reference points at the correct live actor after load.

Prerequisites
Both actors implement ICrimsonSaveableActor. bResolveCrossObjectReferences is enabled (default). References resolve within the same level or the persistent level.

1. Mark the pointer property SaveGame

Use a strong AActor* (TObjectPtr) or a TWeakObjectPtr<AActor> to another saveable actor and tag it SaveGame. Nothing else is required - the value is stored as the target's stable GUID and re-resolved in a deferred pass after every actor in the level is restored.

Screenshot pendingImages/CrimsonSaveSystem/howto-crossref.png
An Actor-type variable (e.g. `LinkedDoor`) with its SaveGame flag ticked, set to another saveable actor in the level.
Verify
Save with the link set, reload, and confirm LinkedDoor is a valid pointer to the correct door - throwing the switch still opens the right door.

2. How it resolves on load

On load, each level's actors are restored (or re-spawned) first, then a deferred resolve pass rewrites every stored GUID back to the live instance. Because resolution runs after all actors in the level exist, references between actors in the same level round-trip reliably. See Concept: World State & Identity for the full flow.

Cross-level limit
A reference to an actor in a different streamed sublevel is not guaranteed to resolve (that sublevel may not be loaded at restore time). Keep linked actors in the same level or the persistent level. Unresolved references are left null and logged.

See also

  • Concept: World State & Identity - how GUIDs and the resolve pass work
  • How-To: Persist a Level Actor