Interaction Engine Documentation
Hotsite Docs Hub

Save and persistence

Saving and restoring interaction state.

Interaction Engine provides a built-in SaveGame class and Blueprint library for capturing interaction state. The recommended workflow is world-level: store all registered interactables, store all active foliage proxy state, write the SaveGame to disk, then restore both systems on the authority after the level has loaded.

How it works

The save system revolves around UInteractionEngineSaveGame, which extends Unreal's USaveGame. It stores interaction data in three maps:

SaveGame fieldUsed byNotes
InteractableSnapshots Normal interactable actors/components Keyed by stable actor path for the bulk workflow, or by your custom SaveKey for the individual workflow.
WorldFoliageProxySnapshots Recommended foliage save/load workflow Keyed by a stable world identity built from source mesh, source component path, instance index, and transform.
FoliageProxySnapshots Legacy / per-interactor foliage workflow Kept for compatibility. Prefer Store All Foliage Proxy Snapshots for multiplayer and most projects.

The plugin does not save automatically on gameplay events. You call the store functions when your project decides to save, and you call the restore functions after the relevant level actors, subsystems, and foliage components are initialized.

Recommended path: for new projects, use Store All Interactable Snapshots together with Store All Foliage Proxy Snapshots. Only use the older per-interactor foliage nodes when you intentionally want a player/interactor-specific foliage snapshot collection.

The interactable registry

UInteractableRegistrySubsystem is a world subsystem that automatically maintains a live list of every loaded UInteractableComponent that has bRegisterForSave enabled. Components self-register on BeginPlay and self-unregister on EndPlay.

This keeps bulk save/load compatible with Level Streaming and World Partition. Only currently loaded interactables are visited during a bulk store or restore call. Previously saved entries for unloaded cells remain in the SaveGame object.

Access the subsystem in Blueprint via Get World Subsystem with class InteractableRegistrySubsystem, then call Get All Interactables if you need a custom manual iteration flow.

bRegisterForSave

bRegisterForSave on UInteractableComponent controls whether the component participates in the automatic registry used by Store All Interactable Snapshots and Restore All Interactable Snapshots. Leave it enabled for placed gameplay interactables. Disable it for decorative objects, temporary runtime actors, or components that your own save system handles manually.

Recommended save workflow

  • 1. Create or load the SaveGame object Create an InteractionEngineSaveGame object, or load an existing one from disk if you are updating an existing save slot.
  • 2. Store all interactables Call Store All Interactable Snapshots, passing any world-context object and the SaveGame. This saves every loaded interactable with bRegisterForSave = true.
  • 3. Store all foliage proxy snapshots If your project uses foliage interactions, call Store All Foliage Proxy Snapshots. This captures all live AFoliageProxyActor state into WorldFoliageProxySnapshots and also preserves runtime world-state foliage snapshots.
  • 4. Save to disk Call Unreal's Save Game To Slot or an async equivalent, passing the SaveGame object, slot name, and user index.
    • Authority requirement: run the store flow on the authority in multiplayer. Clients may request a save through your own game code, but the actual snapshot capture should happen on the server so replicated interaction state and foliage proxy state are authoritative.

    Recommended load workflow

  • 1. Load from disk Call Unreal's Load Game From Slot and cast the result to InteractionEngineSaveGame. If no save exists, skip restore and let the world initialize from defaults.
  • 2. Wait until the level is ready Restore after gameplay actors, interactable components, foliage components, and world subsystems are initialized. Game Mode, Game State, or a dedicated save manager is usually safer than a loading screen widget.
  • 3. Restore all interactables Call Restore All Interactable Snapshots. Each currently loaded interactable checks for a matching saved entry. Components with no saved entry remain at their default state.
  • 4. Restore all foliage proxy snapshots Call Restore All Foliage Proxy Snapshots. Live proxies are updated immediately, missing proxies are materialized when possible, and unresolved snapshots are queued for later streaming/World Partition cases.
    • Do not restore from the client: Apply State Snapshot is authority-only. In multiplayer, the server should restore interaction state and let replication update clients.

    World-level foliage snapshots

    Store All Foliage Proxy Snapshots is the recommended foliage persistence node. It captures foliage proxy state into WorldFoliageProxySnapshots, not into a player/interactor-specific collection. This is the correct model for multiplayer sessions, shared worlds, and ordinary singleplayer saves.

    During restore, the system handles several cases:

  • Already-live proxies Matching live AFoliageProxyActor instances receive their saved state immediately.
  • Missing but loaded source foliage If the source foliage component is loaded, the system can materialize the proxy from the saved snapshot.
  • Completed foliage without a live proxy Tombstone/source-only snapshots can suppress or restore the source instance directly without spawning a new proxy only to represent a destroyed state.
  • Unloaded streaming cells Unresolved snapshots are queued in the world-state / proxy registry path and consumed when the relevant foliage source becomes available.

    • Legacy per-interactor foliage workflow

    Store Foliage Snapshots and Restore Foliage Snapshots still exist for compatibility. They save a collection of active foliage proxy snapshots associated with one InteractorComponent under a manual SaveKey.

    Use this only when your game intentionally needs per-player or per-interactor foliage state. For normal world persistence, especially in multiplayer, prefer the world-level Store All Foliage Proxy Snapshots and Restore All Foliage Proxy Snapshots nodes.

    Individual interactable workflow

    The individual Store Interactable Snapshot and Restore Interactable Snapshot nodes are useful when you need custom save keys or when an interactable is spawned by your own gameplay systems. The SaveKey must be stable and unique. If two interactables use the same key, the later store call overwrites the earlier one.

    Placed actors: the bulk workflow derives stable keys automatically from actor paths. For placed level actors, you usually do not need to manage keys manually.

    Blueprint node reference

    NodeInputsOutputNotes
    Store All Interactable Snapshots World Context, SaveGame — Saves every loaded interactable with bRegisterForSave = true. Recommended for normal interactable actors.
    Restore All Interactable Snapshots World Context, SaveGame — Restores every currently loaded interactable that has a matching saved entry. Authority-only through the component apply path.
    Store All Foliage Proxy Snapshots World Context, SaveGame — Recommended foliage persistence path. Captures live foliage proxy state into WorldFoliageProxySnapshots.
    Restore All Foliage Proxy Snapshots World Context, SaveGame — Restores foliage proxy state from the world-level snapshot map. Updates live proxies, materializes missing proxies when possible, and queues unresolved snapshots.
    Store Interactable Snapshot SaveGame, SaveKey, Interactable — Captures one interactable component under a custom key. Useful for runtime-spawned actors with your own stable IDs.
    Restore Interactable Snapshot SaveGame, SaveKey, Interactable Boolean Applies one saved interactable snapshot. Returns false when the key is not present.
    Store Foliage Snapshots SaveGame, SaveKey, Interactor — Legacy / per-interactor foliage path. Prefer Store All Foliage Proxy Snapshots for shared world persistence.
    Restore Foliage Snapshots SaveGame, SaveKey, Interactor Boolean Legacy / per-interactor foliage restore. Returns whether at least one proxy snapshot was restored.

    Component-level snapshot methods

    These methods are available directly on components when you need lower-level control than the SaveGame library nodes provide.

    MethodComponentNotes
    Capture State Snapshot InteractableComponent Returns an FInteractableComponentStateSnapshot with current interactable and slot state.
    Apply State Snapshot InteractableComponent Applies a previously captured snapshot. Resets slots to defaults first, then applies saved values. Authority-only.
    Capture Active Foliage Proxy Snapshots InteractorComponent Returns foliage proxy snapshots for active proxies tracked by that interactor. Mostly useful for custom/legacy workflows.
    Restore Foliage Proxy Snapshots InteractorComponent Restores an array of foliage proxy snapshots through the interactor. Mostly useful for custom/legacy workflows.
    Restore Foliage Proxy Snapshot InteractorComponent Attempts to restore a single foliage proxy snapshot and returns whether it succeeded.

    What gets saved for interactables

    FInteractableComponentStateSnapshot captures the component-level and slot-level state that Interaction Engine owns.

    Saved dataNotes
    Save versionSnapshot schema version used for compatibility.
    Persistent interactable GUIDStored as part of the snapshot identity/state data.
    Master interactable stateWhether the interactable component is enabled as a whole.
    Respawn stateWhether a respawn is pending and the remaining respawn time.
    Slot enabled/blocked statePer-slot enabled flag, blocked flag, and blocked reason.
    Hold progressCurrent normalized hold progress.
    Hit count and healthCurrent hit count and remaining health for hit/damage-based interactions.
    Toggle active stateWhether a toggle slot is currently active.
    Cooldown stateWhether each slot is on cooldown and how much time remains.
    Custom dataThe component's custom data map is serialized into key/value entries and restored automatically.

    What gets saved for foliage proxies

    FFoliageProxyStateSnapshot stores both the source foliage identity and the proxy interactable state.

    Saved dataNotes
    Stable instance IDIdentifies the foliage instance across save/load when possible.
    Source meshSoft reference to the foliage source mesh.
    Source instance transformWorld transform used to match or reconstruct the proxy/source relationship.
    Source instance indexOriginal instance index when available.
    Source component pathStable path for the source foliage component, normalized for PIE where needed.
    Source/proxy visibilityWhether the original foliage instance and spawned proxy actor were hidden at save time.
    Live proxy flagbHadLiveProxy distinguishes live proxy state from source-only/tombstone state.
    Deferred regrowth stateWhether regrowth was pending and the remaining timer value.
    Interactable stateThe proxy's internal InteractableComponent snapshot, including slot health/progress/cooldowns/custom data.

    What does not get saved

    Limitations and practical rules

  • Restore after initialization Call restore after actors, components, and foliage sources are ready. Restoring too early can leave entries unresolved until streaming catches up.
  • Authority owns restore In multiplayer, restore on the server. Clients should receive the resulting replicated state.
  • Loaded-world scope Bulk interactable store/restore visits currently loaded interactables. Unloaded World Partition cells keep their existing saved entries.
  • Foliage layout changes can invalidate matches If the source foliage mesh, component path, instance index, or transform changes significantly between builds/saves, old foliage snapshots may not match perfectly.
  • Slots reset before apply Apply State Snapshot resets slot runtime state to defaults before applying saved data. Runtime data outside the snapshot is not preserved.

    • Debugging save/load

    Use these console variables when validating persistence flows:

    CVarUse
    ie.Debug.SaveLoad 1Logs snapshot store/restore behavior.
    ie.Debug.Foliage.EventTrace 1Useful when validating foliage proxy lifecycle around save/load.
    ie.Debug.FoliageProxy 1Logs foliage proxy creation, restoration, visibility, and lifecycle details.
    ie.Debug.Net 1Useful in multiplayer when checking whether save/restore was triggered on the correct machine.

    Related pages

  • Foliage See Foliage for the foliage proxy lifecycle, source/proxy visibility, and manual lifecycle control.
  • Multiplayer See Multiplayer for authority, prediction, and replication rules that affect save/load timing.
  • Slot and Settings Reference See Slot and Settings Reference for the slot fields that feed into interactable runtime state.