Skip to content
Tuxedo CatSTUDIO
Menu

Persistence format and compatibility

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

Distinct version fields

Section titled “Distinct version fields”
  • Container version: USaveGameDirectorSaveGame::ContainerVersion, current 1; exact supported wrapper version.
  • File format version: canonical document envelope, current 1. Little-endian bytes begin with SGDR (53 47 44 52), then format/envelope fields including payload byte count and CRC32. Unsupported future versions are rejected.
  • Record versions: Actor current 2; component, subobject, and property current 1. The serializer accepts/normalizes supported legacy Actor record v1 to current Actor shape. Unsupported other record versions fail.
  • Contributor schema version: owned by the contributor payload, stored per contributor. V1 requires exact saved/current equality. No migration callback/coercion exists.

These version concepts have separate owners. File format v1 does not require contributor schema v1.

Integrity and unknown contributors

Section titled “Integrity and unknown contributors”

Serializer checks magic, byte count, structural invariants, payload CRC32, and CRCs for encoded property/contributor values. Corrupt/truncated data fails; unsupported future container/file/record versions fail clearly. Deserialization is transactional and resets output on failure. Canonical serialization works on copies and does not mutate caller data.

CRC detects accidental corruption; it is not encryption/authentication. Contributors marked sensitive use the private SaveGame container field, not public Blueprint-readable bytes.

Unknown saved Optional contributor: warning and skip. Unknown saved Required contributor: restore failure. Registered Required with no record: restore failure. Registered Optional with no record: allowed. Known schema mismatch: failure before validation/restore. Contributor migration deferred to V1.1.

Identity and object graph boundaries

Section titled “Identity and object graph boundaries”

Actor records use the managed persistent GUID; name hints are diagnostic, not identity. Placed Actors restore in place. Eligible runtime-spawned Actors can be recreated under policy. Tombstones represent persisted absence and prevent older saved presence from respawning intentionally deleted Actors.

Capture is bounded, not arbitrary UObject graph traversal. Modes include SaveGame properties, explicit include paths, and all supported properties. Runtime filters unsupported/unsafe property types, transient/editor-only values, delegate-backed state, unsupported traversal and paths. Supported owned components and instanced subobjects are traversed within implementation limits. Explicit paths support top-level fields and supported nested struct fields; not array-index/pointer traversal. Review Restore lifecycle for practical behavior.