Expand description
§bevy_agent_snapshot
Gameplay snapshots and checked restoration for agent-controlled Bevy simulations.
Part of bevy-agent. Requires Bevy 0.18.1 and Rust 1.91+. Version 0.0.4 is experimental; pin all companion crates to the same exact version.
[dependencies]
bevy_agent_snapshot = "=0.0.4"§Register authoritative state
Implement SnapshotType with a stable wire ID and a positive schema version for each serializable gameplay type. Register components and resources through SnapshotAppExt; mark required resources with register_required_snapshot_resource. Gameplay entities need both SnapshotEntity and StableEntityId.
Only registered state is captured. Include hidden state that affects future gameplay, such as cooldowns, RNG state, and pending input. Keep windows, GPU state, sockets, audio handles, and asset-server internals outside the snapshot registry.
SnapshotStore provides retention, pins, and validated imports. Snapshot format version 3 and per-type schema versions are separate from the Cargo package version. Older artifact formats are rejected; there is no migration layer in this release.
Use the coordinated AgentApp::snapshot and restore APIs in bevy_agent_runner when combining snapshots with replay and branches.
§A restore that preserves future behavior
Think of reset, snapshots, and checksums as one state inventory. Register a cooldown or last movement direction even if it is absent from the visible observation: the next action can depend on it. Use required resource registration for values your simulation always expects to exist.
Start with the complete counter, then use the restore regression test to check that save → step → restore → repeat produces the same transition. This is more useful than checking only that a snapshot can serialize.
§Next steps
Read the guide for an organized walkthrough, examples, and troubleshooting.
Licensed under MIT OR Apache-2.0, at your option.
Macros§
Structs§
- Agent
Snapshot Plugin - Component
Registration - Component
Snapshot - Entity
Snapshot - Fault
State - Marker inserted when a restore rollback itself fails.
- Resource
Registration - Resource
Snapshot - Restore
Options - Options controlling post-restore checksum verification.
- Rollback
Failed - Distinct error returned when a restore apply/verification failure is followed by a rollback failure.
- Snapshot
- Snapshot
Create Result - Snapshot
Manifest - Snapshot
Metadata - Snapshot
Policy - Snapshot
Registry - Live registration owner. Serializer tables cannot be modified externally.
- Snapshot
Replay State - Snapshot
Store - Live payload owner and its checkpoint, label, and retention indices.
Enums§
- Snapshot
Role - Semantic role of a snapshot checkpoint.
Constants§
- SNAPSHOT_
SCHEMA_ VERSION - Current snapshot contract: explicit stable type identities and versions.
Traits§
- Snapshot
AppExt - Snapshot
Type - Persisted identity of a registered component or resource.
Functions§
- can_
evict - replay-reference set; such snapshots must never be evicted.
- capture_
snapshot - checksum_
snapshot - checksum_
snapshot_ with_ remap_ exclusions - Stable-payload checksum excluding remapped raw-
Entitycomponents. - clear_
snapshot_ entities - create_
snapshot - create_
snapshot_ with_ role - Role-tagged snapshot creation (preferred).
- delete_
snapshot_ checked - Coordinated delete: rejects snapshots that are pinned or referenced.
- enforce_
retention - Explicit retention enforcement (owner-called).
- install_
snapshots - Atomically merge validated payloads into the live store.
- lookup_
snapshot_ by_ label - maybe_
take_ snapshot - Periodic auto-checkpoint.
- pin_
snapshot - Explicitly retain a snapshot across history replacement until unpinned.
- prune_
checkpoints_ with_ refs - Canonical retention over EVICTABLE checkpoints only.
- restore_
snapshot - restore_
snapshot_ backup - Restore a known-good transaction backup without capturing current state.
- restore_
snapshot_ value - Two-phase restore with atomicity guarantees.
- restore_
snapshot_ value_ with_ options - Canonical restore: two-phase apply plus configurable verification.
- restore_
snapshot_ value_ with_ remap - restore_
snapshot_ value_ with_ remap_ and_ exclusions - Restore with explicit checksum exclusions for remapped raw-
Entitycomponents (seecrate::RestoreOptions). - restore_
snapshot_ with_ remap - Restore with an explicit stable-id remapping hook (see
restore_snapshot_value_with_remap). - set_
snapshot_ episode - Set the episode id used to tag subsequently created checkpoints.
- unpin_
snapshot - Remove a pin previously added with
pin_snapshot. - validate_
snapshot_ full - Full offline validation of a snapshot payload (complete prepare without world mutation).
Type Aliases§
- Snapshot
Registration Result - Registration result exposed so exported macros require no caller dependency.
- Stable
IdRemap Hook - Fix-up hook run after all restored entities and components are installed.