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
| Goal | Runner operation |
|---|---|
| Return to a saved state | snapshot and restore |
| Reconstruct a recorded tick | restore_tick |
| Compare a different future | branch |
| Move recorded history to another process | Export 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§
- Action
Record - Agent
Replay Plugin - Branch
Checkpoint - Branch
Savepoint - Opaque rollback record for branch creation, independent of action count.
- Replay
Log - Portable recording data. Every history record belongs to one explicit branch; timeline topology defines ancestor visibility at fork boundaries.
- Replay
Manifest - Replay
Recorder - Timeline
- Timeline
Branch
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
branchup to the root (branch first, root last). - branch_
fork_ from_ ancestor - Fork tick at which the path from
descendantleavesancestor(thefork_tickof the child directly underancestor). ReturnsNonewhen both are equal orancestoris 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
ancestorequalsdescendantor 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.