Skip to main content

armillae_simulate_bevy/
lib.rs

1#![allow(clippy::result_large_err)]
2
3//! Bevy ECS simulation backend for Armillae.
4//!
5//! This crate adapts native Rust modules and clocks to the backend-neutral
6//! contracts owned by `armillae-simulate`. It intentionally exposes neither a
7//! main loop nor raw schedule ownership.
8//!
9//! Native panics are converted to structured simulation failures when the
10//! process uses unwind panics. A binary built with `panic = "abort"` cannot
11//! recover at these boundaries.
12//!
13//! World access is closure-scoped, so a borrow cannot escape the operation:
14//!
15//! ```compile_fail
16//! use armillae_simulate_bevy::BevySimulation;
17//! use bevy_ecs::world::World;
18//!
19//! fn leak_world(simulation: &BevySimulation) -> &World {
20//!     simulation
21//!         .inspect_world(|world| world)
22//!         .expect("inspection succeeds")
23//! }
24//! ```
25//!
26//! ```compile_fail
27//! use armillae_simulate_bevy::BevySimulation;
28//! use bevy_ecs::world::World;
29//!
30//! fn leak_world_mut(simulation: &mut BevySimulation) -> &mut World {
31//!     simulation
32//!         .write_world(|world| world)
33//!         .expect("write succeeds")
34//! }
35//! ```
36//!
37//! A World borrow also cannot be held across an async suspension point:
38//!
39//! ```compile_fail
40//! use armillae_simulate_bevy::BevySimulation;
41//!
42//! async fn hold_across_await(simulation: &BevySimulation) {
43//!     simulation
44//!         .inspect_world(|world| async move {
45//!             std::future::ready(()).await;
46//!             world.entities().len()
47//!         })
48//!         .expect("inspection succeeds")
49//!         .await;
50//! }
51//! ```
52
53mod builder;
54mod context;
55mod runtime;
56mod support;
57
58pub use builder::{BevyModule, BevyModuleRegistrar, BevySimulationBuilder};
59pub use context::{AdvanceContext, ClockComponent, ExecuteContext, ExecuteOutputError};
60pub use runtime::BevySimulation;
61pub use support::{BEVY_BACKEND_ID, BEVY_ENGINE_NAME};