Skip to main content

Crate bevy_agent_snapshot

Crate bevy_agent_snapshot 

Source
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§

register_snapshot_components
register_snapshot_resources

Structs§

AgentSnapshotPlugin
ComponentRegistration
ComponentSnapshot
EntitySnapshot
FaultState
Marker inserted when a restore rollback itself fails.
ResourceRegistration
ResourceSnapshot
RestoreOptions
Options controlling post-restore checksum verification.
RollbackFailed
Distinct error returned when a restore apply/verification failure is followed by a rollback failure.
Snapshot
SnapshotCreateResult
SnapshotManifest
SnapshotMetadata
SnapshotPolicy
SnapshotRegistry
Live registration owner. Serializer tables cannot be modified externally.
SnapshotReplayState
SnapshotStore
Live payload owner and its checkpoint, label, and retention indices.

Enums§

SnapshotRole
Semantic role of a snapshot checkpoint.

Constants§

SNAPSHOT_SCHEMA_VERSION
Current snapshot contract: explicit stable type identities and versions.

Traits§

SnapshotAppExt
SnapshotType
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-Entity components.
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-Entity components (see crate::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§

SnapshotRegistrationResult
Registration result exposed so exported macros require no caller dependency.
StableIdRemapHook
Fix-up hook run after all restored entities and components are installed.