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};