Skip to main content

Crate bevy_agent_core

Crate bevy_agent_core 

Source
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

  • AgentControlPlugin and the reset, decision, tick, and finalization schedules.
  • AgentAction, AgentActionQueue, and CurrentInputFrame for explicit input.
  • SimClock and DeterministicRng for simulation timing and seeded randomness.
  • Observation, reward, terminal-state, stable-identity, and checksum types.
  • AgentControlAppExt for 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§

AgentActionCatalog
AgentActionQueue
AgentChecksumExtractor
AgentControlPlugin
Installs the deterministic simulation schedules at the configured tick rate.
AgentControlState
AgentDecision
Runs once immediately before each controlled simulation tick.
AgentFinalize
Collects the completed tick’s observation, replay record, and checkpoint after all gameplay hooks have finished.
AgentObservationCatalog
AgentObservationExtractor
AgentPostTick
AgentPreTick
AgentReset
AgentTick
AgentTickFailure
The failure from scheduled observation collection. It is transient and is cleared by reset or a subsequent successful collection.
BranchId
CurrentInputFrame
CustomActionSchema
DeterministicRng
EntityObservation
EnvironmentChecksum
EnvironmentMetadata
EpisodeState
ItemObservation
LastStepResponse
ObjectiveObservation
ObservationConfig
PixelObservation
PlayerObservation
ResetResponse
RewardState
ScheduledAction
SimClock
SnapshotChecksum
Checksum of the serialized, registered snapshot representation.
SnapshotEntity
SnapshotId
StableEntityId
StableHasher
StableIdAllocator
StateDelta
StepInfo
StepManyResponse
StepResponse
SymbolicObservation
TimelineId

Enums§

ActionSource
AgentAction
AgentActionKind
AgentControlError
AgentResetSet
AgentSet
ControlMode
ExecutionContext
Execution context for the simulation.
Observation
ObservationMode

Constants§

CHECKSUM_VERSION
Version for the canonical checksum serialization.
LOOK_PITCH_DELTA_LIMIT_RADIANS
LOOK_YAW_DELTA_LIMIT_RADIANS

Traits§

AgentControlAppExt

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

Type Aliases§

ControlResult