Architecture

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

SaveGame Director separates the runtime persistence service from its Editor tools. The SaveGameDirectorRuntime module owns the Game Instance subsystem, operation coordination, storage, serialization, participant registration, and autosave scheduling. SaveGameDirectorEditor supplies the read-only Inspector and the separate Runtime Controls surface.

Runtime lifetime and requests

Unreal creates one USaveGameDirectorSubsystem per UGameInstance. Each instance owns its operation coordinator, autosave scheduler, participant registrations, and retained diagnostic history. Requests are scoped to that Game Instance. The coordinator accepts, queues, coalesces, or rejects work according to its current lifecycle and capacity; asynchronous storage completion returns to the game thread.

Slot identity is the exact slot name plus nonnegative user index. SaveGame Director does not normalize slot names or derive identity from a world, session, or Actor.

Participants and serialization

Actors opt in through USaveGameDirectorComponent, which controls eligibility and the supported Actor/component/subobject capture policy. The serializer records only supported reflected state and the component’s managed persistent Actor identity. SaveGame Director does not serialize arbitrary UObject graphs.

Additional systems can register contributors through the public contributor/factory contract. Contributors provide stable IDs, schema versions, opaque payload bytes, validation, and restore callbacks. Their payload is separate from Actor property serialization.

The canonical document envelope validates format versions, structure, byte counts, and checksums before restore. Wrapper, file, record, and contributor schema versions have distinct owners. See Persistence Format and Migration.

Save and restore flow

A save captures eligible Actor state and registered contributor payloads, creates the canonical document, then writes through Unreal’s SaveGame slot abstraction or returns a memory container. Operation results report success, warnings, failure status, timing, and bounded diagnostic detail.

A load reads and validates the container, checks map policy and contributor compatibility, then performs the documented restore phases. Eligible missing runtime Actors may be recreated under policy; placed Actors are reconciled by persistent identity. Required contributor or schema failures occur during preflight. A later failure can roll back tracked provisional spawns, but already applied state on pre-existing Actors or external services is not generally reversed. SaveGame Director does not promise whole-world transaction rollback. The complete order and limits are in Restore Lifecycle.

Autosave and diagnostics

Autosave is owned by the Game Instance subsystem. Project settings provide enablement, interval limits, rotation, asynchronous defaults, and diagnostic retention limits. Blocker IDs can prevent scheduling during unsafe transitions. Starting the scheduler and triggering an immediate autosave may write persistent state; stopping it prevents future scheduling but does not cancel an active operation. See Slots and Autosave.

Diagnostic events and warning records are retained per Game Instance according to settings. The Runtime Inspector copies and displays their public metadata. Runtime Controls can clear retained diagnostic events or warning history without clearing save slots.

Optional integrations

Director-to-Director communication uses DirectorBridge adapters over public runtime contracts. The canonical Inventory persistence adapter is DirectorBridgeInventorySaveGame, with IntegrationId Inventory.SaveGame and ContractVersion 1. SaveGame Director core does not depend on Inventory Director. See Integrations.