Skip to main content

Module save

Module save 

Source
Expand description

Versioned, checksummed containers for game-defined payloads.

The engine validates its container; the game owns serialization, schema versions, migration, and recovery policy. Filesystem writes are explicit and optional. See save for replacement and durability behavior.

Structs§

SaveData
Owned disk payload, allocated once after header/length admission.
SaveLimits
Bounds container payload allocation and admission; game codecs can allocate additional memory. The default limit is 64 MiB.
SaveOptions
File-write limits and persistence policy. Defaults to Linux durable writes.
SaveRef
Validated borrowed payload. The engine does not interpret the game schema.

Enums§

CodecError
Keeps game serialization/migration failures separate from engine failures.
CommitState
File replacement disposition when handling a save error.
Durability
Explicit storage policy. Neither mode creates parent directories.
SaveError
Container validation or filesystem failure. No recovery is performed implicitly.
SaveStage
Filesystem operation that failed.

Constants§

FORMAT_VERSION
Current engine container format, independent of a game’s schema version.
HEADER_LEN
Fixed header size: magic (8), format/schema (4 each), length (8), CRC32 (4).

Functions§

decode
Validates without allocation and borrows the opaque payload. Unknown engine formats, truncation, trailing data, oversized payloads and bad checksums fail before any game decoder runs.
encode
Encodes a container into a new vector. Use encode_into to reuse storage.
encode_into
Encodes using reusable output storage. Admission/allocation failures preserve its existing bytes. CRC covers the fixed prefix (including game schema and payload length) followed by the payload; integers are little-endian.
load
Reads only the named regular file. Limits and actual file length are checked before payload allocation; checksum validation precedes game decoding. Leftover temporary files are never discovered or promoted automatically.
load_with
Reads/validates, then calls the game decoder once with its schema and bytes. This is the migration hook: reject unsupported schemas or convert older payloads explicitly. Decoder errors never trigger a write or fallback.
save
Writes a validated container to a unique sibling, then replaces the name. The destination is never truncated. Parent directories must already exist. Linux durable writes sync the file before rename and the parent after it. Failures before rename preserve the destination; rename errors are reported as ambiguous, and a directory-sync error reports an already-installed save. Check SaveError::commit_state before deciding recovery. Concurrent saves use unique temporaries; last replacement wins, without game-state locking. Temporary cleanup is best effort on error/unwind; process crashes can leave uncommitted siblings. Unix files use mode 0600; old metadata is not copied.
save_with
Encodes the game’s payload before touching the filesystem, then writes it. The byte limit applies after serialization; the game’s encoder owns its allocation policy. Serialization errors preserve the existing destination.