Skip to main content

Crate bevy_agent_replay

Crate bevy_agent_replay 

Source
Expand description

§bevy_agent_replay

Action logs, checkpoint indexes, and branching timelines for Bevy agent 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_replay = "=0.0.4"

§Replay ownership

AgentReplayPlugin records completed controlled ticks. ReplayRecorder owns logs; Timeline owns branch topology. Their checked APIs enforce history bounds and reference consistency.

This crate owns recording and topology. bevy_agent_runner coordinates world restoration, replay reconstruction, branches, and portable ReplayBundle export/import with snapshots. Use the runner’s restore_tick, branch, and load_replay_bundle APIs for complete environment operations.

Replay correctness depends on deterministic gameplay, a complete snapshot registry, and a checksum extractor that includes all authoritative state. Current replay manifests use format version 3; older artifacts are rejected.

§Choose the operation you need

GoalRunner operation
Return to a saved statesnapshot and restore
Reconstruct a recorded tickrestore_tick
Compare a different futurebranch
Move recorded history to another processExport a replay bundle, then load_replay_bundle

A portable bundle must carry its referenced checkpoints; an input list alone cannot reconstruct arbitrary world state. History is bounded by retention policy. See the worked history guide and testing guide.

§Next steps

Read the guide for an organized walkthrough, examples, and troubleshooting.

Licensed under MIT OR Apache-2.0, at your option.

Structs§

ActionRecord
AgentReplayPlugin
BranchCheckpoint
BranchSavepoint
Opaque rollback record for branch creation, independent of action count.
ReplayLog
Portable recording data. Every history record belongs to one explicit branch; timeline topology defines ancestor visibility at fork boundaries.
ReplayManifest
ReplayRecorder
Timeline
TimelineBranch

Constants§

MAX_LINEAGE_DEPTH
Maximum branch ids visited during any parent-chain traversal.
MAX_RECONSTRUCTION_TICKS
Maximum ticks allowed in a single reconstruction interval.
MAX_TIMELINE_BRANCHES
Maximum branches admitted into a live topology.
REPLAY_SCHEMA_VERSION
Current replay wire contract, paired with explicit snapshot type identities.

Functions§

ancestors_bounded
Bounded ancestry chain from branch up to the root (branch first, root last).
branch_fork_from_ancestor
Fork tick at which the path from descendant leaves ancestor (the fork_tick of the child directly under ancestor). Returns None when both are equal or ancestor is not an ancestor.
branch_record_visible
Fork-bounded visibility shared by action and checkpoint queries. Ancestors contribute (own_fork, child_fork]; the target branch contributes its own history. Unknown branch identities are rejected.
collect_replay_references
Every checkpoint needed by a portable recording or live retention policy.
lineage_contains
Returns true when ancestor equals descendant or appears in the descendant’s parent chain.
record_replay_step
start_recording
Replace recording owners only after the fresh history fits its byte budget.
stop_recording
Seal the current recording and return its action count. Repeated stops leave the sealed history untouched; payload retrieval is explicit.