bevy_turborand

CI License Cargo Documentation

A plugin to enable random number generation for the Bevy game engine, built upon turborand. Implements ideas from Bevy's Deterministic RNG RFC.

turborand's internal implementation uses Wyrand, a simple and fast generator but not cryptographically secure.

Example

```rust use bevy::prelude::; use bevy_turborand::;

[derive(Debug, Component)]

struct Player;

fn setupplayer(mut commands: Commands, mut globalrng: ResMut) { commands.spawn() .insert(Player) .insert(RngComponent::fromglobal(&mut globalrng)); }

fn dodamage(mut qplayer: Query<&mut RngComponent, With>) { let mut rng = qplayer.singlemut();

println!("Player attacked for {} damage!", rng.u32(10..=20));

}

fn main() { App::new() .addplugin(RngPlugin::default()) .addstartupsystem(setupplayer) .addsystem(dodamage) .run(); } ```

Deterministic RNG

In order to obtain determinism for your game/app, the Rng's must be seeded. GlobalRng and RngPlugin can given a seed which then sets the internal PRNG to behave deterministically. Instead of having to seed every RngComponent manually, as long as the GlobalRng is seeded, then RngComponent can be created directly from the global instance, cloning the internal Rng to itself, which gives it a random but deterministic seed. This allows for better randomised states among RngComponents while still having a deterministic app.

Systems also must be ordered correctly for determinism to occur. Systems however do not need to be strictly ordered against every one as if some linear path. Only related systems that access a given set of RngComponents need to be ordered. Ones that are unrelated can run in parallel and still yield a deterministic result. So systems selecting a Player entity with a RngComponent should all be ordered against each other, but systems selecting an Item entity with an RngComponent that never interacts with Player don't need to be ordered with Player systems, only between themselves.

To see an example of this, view the project's tests to see how to make use of determinism for testing random systems.

License

Licensed under either of

at your option.