Expand description
§bevy_agent_core
Deterministic simulation primitives for agent-controlled Bevy games.
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"§What this crate provides
AgentControlPluginand the reset, decision, tick, and finalization schedules.AgentAction,AgentActionQueue, andCurrentInputFramefor explicit input.SimClockandDeterministicRngfor simulation timing and seeded randomness.- Observation, reward, terminal-state, stable-identity, and checksum types.
AgentControlAppExtfor metadata, action catalogs, schemas, and extractors.
Run authoritative gameplay in AgentTick, consume domain actions, and read SimClock instead of frame time. A game must declare its supported actions and observation modes and install both observation and checksum extractors. Determinism depends on the game’s state coverage and system ordering.
For a complete environment, start with bevy_agent_runner::AgentControlPlugins and AgentApp; the runner composes core, snapshots, and replay.
§How to use it
Most games start with the runner’s composed plugins and use this crate’s types directly. Put authoritative systems in AgentTick, consume CurrentInputFrame<AgentAction>, and use SimClock for simulation time. A Noop action still advances the simulation; its gameplay effect belongs to your systems.
The complete counter shows metadata, a supported action catalog, observation schema, and both extractors in one app. Move on to actions and observations for domain-specific commands.
§Next steps
Read the guide for an organized walkthrough, examples, and troubleshooting.
Licensed under MIT OR Apache-2.0, at your option.
Structs§
- Agent
Action Catalog - Agent
Action Queue - Agent
Checksum Extractor - Agent
Control Plugin - Installs the deterministic simulation schedules at the configured tick rate.
- Agent
Control State - Agent
Decision - Runs once immediately before each controlled simulation tick.
- Agent
Finalize - Collects the completed tick’s observation, replay record, and checkpoint after all gameplay hooks have finished.
- Agent
Observation Catalog - Agent
Observation Extractor - Agent
Post Tick - Agent
PreTick - Agent
Reset - Agent
Tick - Agent
Tick Failure - The failure from scheduled observation collection. It is transient and is cleared by reset or a subsequent successful collection.
- Branch
Id - Current
Input Frame - Custom
Action Schema - Deterministic
Rng - Entity
Observation - Environment
Checksum - Environment
Metadata - Episode
State - Item
Observation - Last
Step Response - Objective
Observation - Observation
Config - Pixel
Observation - Player
Observation - Reset
Response - Reward
State - Scheduled
Action - SimClock
- Snapshot
Checksum - Checksum of the serialized, registered snapshot representation.
- Snapshot
Entity - Snapshot
Id - Stable
Entity Id - Stable
Hasher - Stable
IdAllocator - State
Delta - Step
Info - Step
Many Response - Step
Response - Symbolic
Observation - Timeline
Id
Enums§
- Action
Source - Agent
Action - Agent
Action Kind - Agent
Control Error - Agent
Reset Set - Agent
Set - Control
Mode - Execution
Context - Execution context for the simulation.
- Observation
- Observation
Mode
Constants§
- CHECKSUM_
VERSION - Version for the canonical checksum serialization.
- LOOK_
PITCH_ DELTA_ LIMIT_ RADIANS - LOOK_
YAW_ DELTA_ LIMIT_ RADIANS
Traits§
Functions§
- begin_
tick - collect_
observation - collect_
observation_ with_ mode - Collects an observation in a request-local mode without changing the default mode. Games supply both extractors; there is no fallback state.
- default_
checksum - drain_
agent_ actions - json_
heap_ bytes - Charges array capacity, strings, and map nodes rather than wire bytes alone. Allocator bookkeeping is conservatively included for each map entry.
- merge_
pending_ actions - Merge only missing occurrences, preserving source, multiplicity and order within each tick. Validation completes before the queue changes.
- reset_
agent_ core - run_
agent_ tick - Runs exactly one agent-controlled simulation tick. Invalid integration or pending actions are rejected before gameplay advances; observation failure is returned and cannot reuse the previous tick’s response.
- schedule_
action - Schedule against the world’s actual catalog, cursor, source policy and execution context, without mutating the queue on rejection.
- stable_
hash_ json - validate_
action_ against_ catalog - Pure validation shared by direct, scheduled, remote, and replay actions.
- validate_
clock_ tick - Upper bound guard for imported tick values. Real episodes are thousands of ticks; anything above u32::MAX almost certainly indicates corrupt or adversarial snapshot/replay data.
- validate_
future_ action - validate_
integration - Checks resources, schedules, extractors, catalogs, metadata and imported future actions before constructing a controllable environment.
- validate_
next_ tick - validate_
scheduled_ action