bevy_gym/lib.rs
1//! Bevy ECS plugin for parallelised RL environment simulation.
2//!
3//! `bevy-gym` bridges `rl-traits` environments into Bevy's ECS, giving you:
4//!
5//! - **Free parallelism**: N environment instances as separate Bevy entities,
6//! stepped in parallel via `par_iter_mut()` each `FixedUpdate` tick.
7//!
8//! - **Decoupled tick rate**: RL simulation runs in `FixedUpdate` at a
9//! configurable Hz. Rendering (if enabled) runs in `Update` at frame rate.
10//! The two are completely independent.
11//!
12//! - **Headless training mode**: disable rendering entirely and run at maximum
13//! CPU throughput via `ScheduleRunnerPlugin`.
14//!
15//! - **Event-driven policy integration**: `ActionRequestEvent` tells your
16//! policy system when to provide the next action. `ExperienceEvent` delivers
17//! the full `(s, a, r, s', status)` transition back to ember-rl (or any
18//! other consumer) without coupling to Bevy internals.
19//!
20//! # Quick start
21//!
22//! ```rust
23//! use bevy::prelude::*;
24//! use bevy_gym::{BevyGymPlugin, ActionRequestEvent, ExperienceEvent};
25//! use bevy_gym::components::{CurrentObservation, PendingAction};
26//!
27//! // Headless training with 16 parallel environments
28//! App::new()
29//! .add_plugins(MinimalPlugins)
30//! .add_plugins(
31//! BevyGymPlugin::new(|i| CartPoleEnv::new(i as u64), 16)
32//! .headless()
33//! )
34//! .add_systems(FixedUpdate, random_policy_system)
35//! .run();
36//!
37//! // Random policy: write a random action whenever one is requested
38//! fn random_policy_system(
39//! mut requests: EventReader<ActionRequestEvent>,
40//! mut query: Query<(&EnvId, &mut PendingAction<CartPoleEnv>)>,
41//! ) {
42//! for req in requests.read() {
43//! if let Some((_, mut pending)) = query.iter_mut()
44//! .find(|(id, _)| id.0 == req.env_id)
45//! {
46//! pending.action = Some(rand::random::<usize>() % 2);
47//! }
48//! }
49//! }
50//! ```
51
52pub mod components;
53pub mod events;
54pub mod plugin;
55#[cfg(feature = "render")]
56pub mod render;
57pub mod systems;
58
59pub use components::{
60 CurrentObservation, EnvId, EnvStats, EnvironmentComponent, PendingAction,
61};
62pub use events::{ActionRequestEvent, EpisodeEndEvent, ExperienceEvent};
63pub use plugin::{spawn_environments, BevyGymPlugin, GymConfig, GymSet};
64pub use systems::reset::ResetRequested;