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§
- Save
Data - Owned disk payload, allocated once after header/length admission.
- Save
Limits - Bounds container payload allocation and admission; game codecs can allocate additional memory. The default limit is 64 MiB.
- Save
Options - File-write limits and persistence policy. Defaults to Linux durable writes.
- SaveRef
- Validated borrowed payload. The engine does not interpret the game schema.
Enums§
- Codec
Error - Keeps game serialization/migration failures separate from engine failures.
- Commit
State - File replacement disposition when handling a save error.
- Durability
- Explicit storage policy. Neither mode creates parent directories.
- Save
Error - Container validation or filesystem failure. No recovery is performed implicitly.
- Save
Stage - 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_intoto 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_statebefore 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.