Persistence Model
Interaction save state is based on stable ids. Target save ids identify targets. Owner save ids identify owner-scoped interactor state. Point ids, command ids, and variant ids identify the authored rows whose runtime state should persist. If these ids change, old snapshots can no longer map cleanly to current content.
What The Snapshot Stores
FInteractionRuntimeSaveSnapshot and related save structs carry saved target disables, saved point or command disables, cooldown end times, variant overrides, owner-scoped state, and revision information. The snapshot does not replace your project SaveGame; it is the interaction-framework portion that your SaveGame can store.
Storage Interfaces
UInteractionRuntimeSaveSnapshotStorage is the Unreal reflection side of the storage interface. IInteractionRuntimeSaveSnapshotStorage contains the C++ interface functions. Implement the interface on a project SaveGame-style object when the project wants the framework to read and write snapshots through Blueprint or C++ helper functions.
Blueprint Save Library
UInteractionRuntimeSaveBlueprintLibrary exposes Blueprint helpers for summaries, storage access, world import/export, and debounced auto-export. Use these helpers when designers or Blueprint gameplay systems own the save flow. Use the world subsystem directly when C++ gameplay code already owns world save orchestration.
Save Setup Order
- Pick target save ids for targets whose state should persist.
- Pick owner save ids if owner-scoped interaction state is needed.
- Decide whether project SaveGame storage will implement
IInteractionRuntimeSaveSnapshotStorage. - Export a snapshot after a runtime state change that should persist.
- Store the snapshot inside project save data.
- Import the snapshot after relevant targets have registered in the world.
Debounced Export
Debounced export helpers are useful when many interaction changes can happen close together. Instead of writing a SaveGame every time one command changes state, schedule an export and let repeated changes collapse into a later write. Keep the returned handle alive for as long as the debounced export behavior should remain bound.
Restore Timing
Import too early and targets may not exist yet. Import too late and players may briefly see default target state. For persistent levels, import after target components have registered. For streamed or spawned targets, call import again or apply relevant snapshot data when the target becomes available.
Debugging Stale Save Data
- Compare target save ids against the current target component values.
- Compare point ids, command ids, and variant ids against the current definition.
- Check whether saved cooldown time uses a time provider compatible with the current world/session.
- Verify imported state changes are made on authority when they affect replicated target state.
Save Ownership Patterns
Projects usually choose one of two patterns. In a Blueprint-owned save flow, a SaveGame object implements the storage interface and Blueprint helper nodes import/export snapshots. In a C++-owned save flow, gameplay code calls the world subsystem and stores the snapshot inside a larger project save record. Both patterns rely on the same stable ids.
Streaming And Spawned Targets
For persistent placed actors, import once after registration is usually enough. For streamed levels or spawned actors, targets may register after the first import. In those projects, import again after streaming completes or apply relevant snapshot data when the target becomes available.
Save Compatibility Discipline
Changing ids is a save migration. If content is already shipped, treat renamed target ids, point ids, command ids, and variant ids as compatibility work. Keep a migration plan in project save code if those ids must change.