Skip to main content

Crate bevy_agent_runner

Crate bevy_agent_runner 

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

Run 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; visual enables Bevy render/window capture support.
  • AgentControlPlugins::default() installs core, snapshots, and replay. Configure retention through with_snapshot_policy.
  • step_many and 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 --locked

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

AgentApp
Owns a validated Bevy app, controlled ticks, and coordinated history.
AgentControlPlugins
Installs the core control plugin, gameplay snapshots, and replay recording.
AgentVisualCaptureRenderer
MutationFailure
ReplayBundle
A portable replay artifact containing every snapshot referenced by its log.
ResetOptions
Episode initialization policy. Defaults to seed zero, hybrid observations, and an initial snapshot suitable for replay reconstruction.
VisualCaptureOptions
VisualCaptureResult

Enums§

CaptureSource

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§

AgentEnvironment
A synchronous control loop for an integrated simulation.
VisualCaptureAppExt

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