Expand description
§bevy_agent_runner
Step, inspect, snapshot, restore, and branch a Bevy game through a Rust environment API.
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_core = "=0.0.4"
bevy_agent_runner = "=0.0.4"
bevy_agent_snapshot = "=0.0.4"§Control an integrated game
The app builder must install AgentControlPlugins, register gameplay state, and configure metadata, supported actions/modes, observations, and checksums. Construction validates this contract.
use bevy::prelude::App;
use bevy_agent_core::AgentAction;
use bevy_agent_runner::{AgentApp, AgentEnvironment, ResetOptions};
fn drive_game(build_game: impl FnOnce() -> App) -> anyhow::Result<()> {
let mut env = AgentApp::new(build_game)?;
env.reset(ResetOptions::default())?;
let snapshot = env.snapshot()?;
let first = env.step(AgentAction::Noop)?;
env.restore(snapshot.snapshot_id)?;
let repeated = env.step(AgentAction::Noop)?;
assert_eq!(first.checksum, repeated.checksum);
Ok(())
}The packaged counter example contains a complete, headless app and exercises reset, stepping, snapshots, and replay:
cargo run -p bevy_agent_runner --example counterRun that command from the repository or this crate’s unpacked source. Read the example to build your own environment.
§Features and guarantees
- Default features are headless;
visualenables Bevy render/window capture support. AgentControlPlugins::default()installs core, snapshots, and replay. Configure retention throughwith_snapshot_policy.step_manyand fast-forward stop at terminal state.- Mutation failures report the committed tick and recovery state. A faulted environment requires a successful reset.
- Snapshot and replay owners each default to a configurable 64 MiB retention budget.
- Checksums detect consistency errors; they do not authenticate artifacts or guarantee identical behavior across platforms.
§Verify your environment
The counter also includes two runnable tests:
cargo test -p bevy_agent_runner --example counter --lockedRun this from the repository or unpacked crate. It checks gameplay assertions, repeated seeded resets, snapshot restoration, and replay reconstruction. The testing guide explains how to adapt these checks to your game.
After each step, inspect done and truncated before continuing. Read observation to choose the next action, and use checksum to compare equivalent transitions. Snapshots contain registered authoritative state; they do not clone rendering or transport resources.
§Next steps
Licensed under MIT OR Apache-2.0, at your option.
Structs§
- Agent
App - Owns a validated Bevy app, controlled ticks, and coordinated history.
- Agent
Control Plugins - Installs the core control plugin, gameplay snapshots, and replay recording.
- Agent
Visual Capture Renderer - Mutation
Failure - Replay
Bundle - A portable replay artifact containing every snapshot referenced by its log.
- Reset
Options - Episode initialization policy. Defaults to seed zero, hybrid observations, and an initial snapshot suitable for replay reconstruction.
- Visual
Capture Options - Visual
Capture Result
Enums§
Constants§
- MAX_
IMPORT_ BRANCHES - Maximum number of branches accepted in a portable replay bundle.
- MAX_
LINEAGE_ DEPTH - Maximum branch ids visited during any parent-chain traversal.
Traits§
- Agent
Environment - A synchronous control loop for an integrated simulation.
- Visual
Capture AppExt
Functions§
- clear_
episode - queue_
excluded_ checksum - Computes a snapshot checksum that excludes the pending action queue.
- sanitized_
capture_ label - set_
episode_ done - visual_
capture_ path