V1 workflow examples

Review draft. This source page has not completed website editorial and release-specific verification.

The snippets below use the current public APIs and the frozen V1 contracts.

1. Blueprint save to slot

Get the subsystem with Get Game Instance Subsystem. Call Save Game to Slot (Checkpoint_01, user 0). Branch on bool; inspect OperationResult.

2. Blueprint load from slot

Call Load Game from Slot with the same name/index. Handle false for missing, invalid, or failed restore and show the result message.

3. C++ save to slot

FSaveGameDirectorSaveRequest Request;
Request.Slot = FSaveGameDirectorSlotIdentifier(TEXT("Checkpoint_01"), 0);
FSaveGameDirectorOperationResult Result;
const bool bSaved = Director->SaveToSlot(Request, Result);

4. C++ load from slot

FSaveGameDirectorLoadRequest Request;
Request.Slot = FSaveGameDirectorSlotIdentifier(TEXT("Checkpoint_01"), 0);
FSaveGameDirectorOperationResult Result;
const bool bLoaded = Director->LoadFromSlot(Request, Result);

5. Memory save/load

Call SaveToMemory(SaveRequest, MemoryData, Result), retain the USaveGameDirectorSaveGame, then LoadFromMemory(LoadRequest, MemoryData, Result). Blueprint equivalents are Save Game to Memory and Load Game from Memory.

6. Async save

Call SaveToSlotAsync(Request, Completion); completion receives final result on the game thread. Blueprint: Save Game to Slot Async, bind Completed and Failed.

7. Async load

Call LoadFromSlotAsync(Request, Completion) or Blueprint Load Game from Slot Async; inspect result in either terminal event.

8. Add Actor component

In Blueprint add Save Game Director Actor Component. In C++, use CreateDefaultSubobject<USaveGameDirectorComponent>(TEXT("SaveGameDirector")) in the Actor constructor.

9. Persist supported Actor state

Set capture mode to SaveGameProperties and mark eligible reflected fields with Unreal SaveGame. The component’s capture flags also control transform and supported owned components.

10. Runtime-spawned Actor restore

Ensure the saved Actor class and stable component ID are valid, and policy permits RespawnIfMissing/automatic runtime recreation. Load through the subsystem. Core does not reconstruct arbitrary UObject graphs.

11. Tombstone behavior

Select RecordTombstone when destruction should persist. Destroying the Actor records absence so an older present record will not respawn it.

12. Create a contributor

Implement ISaveGameDirectorContributor methods: IDs, provider, schema, requirement, phase/priority, CapturePayload, ValidateRestorePayload, RestorePayload. See the complete implementation in Contributor Guide.

13. Create a factory

Implement ISaveGameDirectorContributorFactory; CreateContributor(UGameInstance&) returns a new instance. Register/unregister the persistent factory object in module Startup/Shutdown.

14. Required contributor

Return Required from GetRequirement(). A missing corresponding record fails load before Actor restoration.

15. Optional contributor

Return Optional. An absent record is allowed and results in no callback with fake/empty data.

16. Capture payload

Serialize the contributor’s defined state into OutPayload; return false and set OutError when capture cannot produce a valid payload.

17. Validate payload

Implement ValidateRestorePayload(Payload, SchemaVersion, OutError) as a non-mutating parse/validation step. Core requires schema equality first.

18. Restore before Actors

Return BeforeActorRestore to establish global state that Actor restoration needs.

19. Restore in another phase

The API exposes AfterActorCreationBeforeProperties, AfterActorPropertyRestore, and FinalPostRestore. The first runs after eligible runtime Actors have been created and registered but before saved Actor properties are applied. Use AfterActorPropertyRestore for work that depends on restored Actor properties, and FinalPostRestore for final coordination. See Restore lifecycle.

20. Priority ordering

Return a deterministic integer from GetRestorePriority(); lower priorities run first within phase. Equal priorities use deterministic identity ordering.

21. Missing Required record

A currently registered Required contributor missing from the document yields status RequiredContributorMissing. The result identifies that contributor; no Actor restore is started.

22. Missing Optional record

A currently registered Optional contributor with no record is accepted silently; no payload is fabricated.

23. Schema mismatch

Saved/current version mismatch for a known contributor fails before validation/restore. Do not attempt coercion.

24. Unknown Optional record

A saved Optional record with no current factory/contributor is warned and skipped.

25. Unknown Required record

A saved Required record with no current contributor fails restore; enable the product that owns it.

26. Autosave

Configure interval/rotation, remove active blocker IDs when safe, then call StartAutosave(). Query IsAutosaveRunning(); submit one immediate operation with TriggerAutosaveNow().

27. Backup/overwrite

Set Request.bAllowOverwrite. With backup setting enabled, existing slot contents are first written to <Slot>.SaveGameDirectorBackup.<UserIndex>; backup failure fails the new save.

28. WorldState

For canonical WorldState persistence, provide the authoritative World State plugin in the host and enable the optional DirectorBridge integration, then confirm WorldState.SaveGame is Active. SaveGame Director does not bundle World State. Its core remains standalone; its contributor API, ContributorSchema policy, Required/Optional semantics, and restore lifecycle are unchanged. Payload migration remains future V1.1 work.

30. Result diagnostics

For sync calls check bool and result. For async check both terminal events. Inspect status/severity/messages/warnings/timing and subsystem diagnostics. SuccessWithWarnings is still success.

31. Corrupt/future data

Bad SGDR magic, truncated bytes, bad CRC, malformed records, or unsupported future versions are rejected with structured status/errors. Keep original bytes for diagnosis.

32. Schema evolution boundary

V1 accepts only exact contributor schema equality. General contributor migration is deferred to V1.1. Change payload schema only with a product compatibility plan.