Save And Restore Interaction State

Goal

This recipe persists interaction runtime state so targets can restore disabled commands, cooldowns, and variant overrides after loading.

Prepare Stable Ids

1. Assign target save ids to target components whose state should persist.
2. Keep point ids, command ids, and variant ids stable in target definitions.
3. Assign owner save ids when owner-scoped interactor state should persist.

Create Storage

Implement IInteractionRuntimeSaveSnapshotStorage on a project SaveGame-style object, or use UInteractionRuntimeSaveBlueprintLibrary helpers to move FInteractionRuntimeSaveSnapshot values into your own save data.

Export Flow

1. After an interaction state change, export from the world subsystem or save Blueprint library.
2. Store the snapshot in the project SaveGame.
3. Use debounced export when many interaction changes can happen close together.

Import Flow

1. Load project SaveGame data.
2. Wait until relevant target components have registered.
3. Import the interaction snapshot into the world subsystem.
4. Verify prompts reflect saved disables, cooldowns, and variants.

Failure Checks

• Stale target save id: imported state has no matching target.
• Renamed point or command id: state imports but cannot apply to the authored row.
• Import too early: targets have not registered yet.
• Client-only import: replicated shared state is not changed on authority.

Persistence Test Matrix

• Disable a command, export, reload, import, and confirm the command is still disabled.
• Apply a cooldown, export, reload, import, and confirm the remaining cooldown behavior is acceptable for the project.
• Set a variant override, export, reload, import, and confirm the prompt shows the saved variant.
• Rename a point in a test copy and confirm old save data no longer maps; this proves why ids must stay stable.
• Test import timing with streamed or spawned targets if the project uses them.

Debounced Save Flow

Use debounced export for rapid interaction changes such as several pickups, repeated toggles, or multi-step routes. Keep the auto-export handle alive while the binding should remain active, and flush or export directly before a critical save boundary if the project needs immediate persistence.

When To Export

Export after state changes that matter to persistence: disabling a target or command, applying a meaningful cooldown, changing a saved variant override, or importing external state that should become the new save baseline. Do not export every UI-only focus or projection change.

When To Import

Import after the world has the targets that should receive saved state. For a main level this can be part of load completion. For streamed content, import again after the streaming level finishes registering targets. For spawned actors, apply snapshot state after spawn and target registration.

Blueprint SaveGame Pattern

1. Create a project SaveGame Blueprint that implements IInteractionRuntimeSaveSnapshotStorage.
2. Store the interaction snapshot inside that SaveGame object.
3. On save, export from UInteractionRuntimeSaveBlueprintLibrary or the world subsystem into storage.
4. On load, restore the project SaveGame, then import the stored interaction snapshot after targets register.

State Review

Only persist state that should survive a load. Focus, projected screen position, visible page, and transient widget state should not be exported as permanent save state. Disabled target state, disabled command state, cooldowns, and variant overrides are persistence candidates when the design expects them to survive.

Migration Review

If content ids change, old saves need migration or they should be treated as incompatible. Keep a list of shipped target save ids, point ids, command ids, and variant ids so content updates do not silently orphan old snapshot entries.