Add bevy_entropy default plugin

Author: LegNeato

Cargo.toml

@@ -87,7 +87,7 @@ bevy_internal = {path = "crates/bevy_internal", version = "0.5.0", default-featu
 
 [dev-dependencies]
 anyhow = "1.0.4"
-rand = "0.8.0"
+rand = { version = "0.8.0", features = ["small_rng"] }
 ron = "0.6.2"
 serde = {version = "1", features = ["derive"]}
 # Needed to poll Task examples
@@ -212,6 +212,10 @@ path = "examples/app/plugin.rs"
 name = "plugin_group"
 path = "examples/app/plugin_group.rs"
 
+[[example]]
+name = "random"
+path = "examples/app/random.rs"
+
 [[example]]
 name = "return_after_run"
 path = "examples/app/return_after_run.rs"

crates/bevy_ecs/Cargo.toml

@@ -32,7 +32,9 @@ rand = "0.8"
 serde = "1"
 
 [dev-dependencies]
+bevy_entropy = { path = "../bevy_entropy", version = "0.5.0" }
 parking_lot = "0.11"
+rand = { version = "0.8", features = ["small_rng"] }
 
 [[example]]
 name = "events"

crates/bevy_ecs/examples/change_detection.rs

@@ -1,9 +1,11 @@
 use bevy_ecs::prelude::*;
-use rand::Rng;
+use bevy_ecs::schedule::RunOnce;
+use bevy_entropy::Entropy;
+use rand::{rngs::SmallRng, Rng, SeedableRng};
 use std::ops::Deref;
 
 // In this example we will simulate a population of entities. In every tick we will:
-// 1. spawn a new entity with a certain possibility
+// 1. spawn a new entity with a certain deterministic probability
 // 2. age all entities
 // 3. despawn entities with age > 2
 //
@@ -13,17 +15,33 @@ fn main() {
     // Create a new empty World to hold our Entities, Components and Resources
     let mut world = World::new();
 
+    // Add the entropy resource for future random number generators to use.
+    // This makes execution deterministic.
+    let world_seed = [1; 32];
+    world.insert_resource(Entropy::from(world_seed));
+
     // Add the counter resource to remember how many entities where spawned
     world.insert_resource(EntityCounter { value: 0 });
 
-    // Create a new Schedule, which defines an execution strategy for Systems
+    // Create a new Schedule, which defines an execution strategy for Systems.
     let mut schedule = Schedule::default();
+
     // Create a Stage to add to our Schedule. Each Stage in a schedule runs all of its systems
-    // before moving on to the next Stage
-    let mut update = SystemStage::parallel();
+    // before moving on to the next Stage.
+    // Here, we are creating a "startup" Stage with a schedule that runs once.
+    let mut startup = SystemStage::parallel();
+    startup.add_system(create_rng.system());
+    schedule.add_stage(
+        "startup",
+        Schedule::default()
+            .with_run_criteria(RunOnce::default())
+            .with_stage("only_once", startup),
+    );
 
-    // Add systems to the Stage to execute our app logic
+    // Add systems to another Stage to execute our app logic.
     // We can label our systems to force a specific run-order between some of them
+    // within the Stage.
+    let mut update = SystemStage::parallel();
     update.add_system(spawn_entities.system().label(SimulationSystem::Spawn));
     update.add_system(
         print_counter_when_changed
@@ -62,11 +80,23 @@ enum SimulationSystem {
     Age,
 }
 
+// This system creates a random number generator resource from [`Entropy`].
+fn create_rng(mut commands: Commands, mut entropy: ResMut<Entropy>) {
+    let seed = entropy.get();
+    println!("    seeding rng from entropy: {:?}", seed);
+    let rng = SmallRng::from_seed(seed);
+    commands.insert_resource(rng);
+}
+
 // This system randomly spawns a new entity in 60% of all frames
 // The entity will start with an age of 0 frames
 // If an entity gets spawned, we increase the counter in the EntityCounter resource
-fn spawn_entities(mut commands: Commands, mut entity_counter: ResMut<EntityCounter>) {
-    if rand::thread_rng().gen_bool(0.6) {
+fn spawn_entities(
+    mut commands: Commands,
+    mut entity_counter: ResMut<EntityCounter>,
+    mut rng: ResMut<SmallRng>,
+) {
+    if rng.gen_bool(0.6) {
         let entity_id = commands.spawn().insert(Age::default()).id();
         println!("    spawning {:?}", entity_id);
         entity_counter.value += 1;

crates/bevy_ecs/examples/resources.rs

@@ -1,5 +1,6 @@
 use bevy_ecs::prelude::*;
-use rand::Rng;
+use bevy_entropy::Entropy;
+use rand::{prelude::SmallRng, Rng, SeedableRng};
 use std::ops::Deref;
 
 // In this example we add a counter resource and increase it's value in one system,
@@ -8,6 +9,10 @@ fn main() {
     // Create a world
     let mut world = World::new();
 
+    // Add the entropy resource
+    let world_seed = [1; 32];
+    world.insert_resource(Entropy::from(world_seed));
+
     // Add the counter resource
     world.insert_resource(Counter { value: 0 });
 
@@ -38,8 +43,11 @@ enum CounterSystem {
     Increase,
 }
 
-fn increase_counter(mut counter: ResMut<Counter>) {
-    if rand::thread_rng().gen_bool(0.5) {
+fn increase_counter(mut counter: ResMut<Counter>, mut entropy: ResMut<Entropy>) {
+    // Note that in a real system it would be better to create this once
+    // as a resource.
+    let mut rng = SmallRng::from_seed(entropy.get());
+    if rng.gen_bool(0.5) {
         counter.value += 1;
         println!("    Increased counter value");
     }

crates/bevy_entropy/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "bevy_entropy"
+version = "0.5.0"
+edition = "2018"
+authors = [
+    "Bevy Contributors <[email protected]>",
+    "Christian Legnitto <[email protected]>",
+]
+description = "Provides entropy functionality for Bevy Engine"
+homepage = "https://bevyengine.org"
+repository = "https://github.com/bevyengine/bevy"
+license = "MIT"
+keywords = ["bevy", "random", "entropy"]
+
+[dependencies]
+# bevy 
+bevy_app = { path = "../bevy_app", version = "0.5.0" }
+bevy_utils = { path = "../bevy_utils", version = "0.5.0" }
+# other
+rand = { version = "0.8", features = ["std_rng"] }

crates/bevy_entropy/src/lib.rs

@@ -0,0 +1,59 @@
+use bevy_app::{AppBuilder, Plugin};
+use bevy_utils::tracing::{debug, trace};
+use rand::{rngs::StdRng, RngCore, SeedableRng};
+
+pub mod prelude {
+    #[doc(hidden)]
+    pub use crate::Entropy;
+}
+
+/// Provides a source of entropy.
+/// This enables deterministic execution.
+#[derive(Default)]
+pub struct EntropyPlugin;
+
+impl Plugin for EntropyPlugin {
+    fn build(&self, app: &mut AppBuilder) {
+        let world = app.world();
+        if !world.contains_resource::<Entropy>() {
+            trace!("Creating entropy");
+            app.init_resource::<Entropy>();
+        }
+    }
+}
+
+/// A resource that provides entropy.
+pub struct Entropy(StdRng);
+
+impl Default for Entropy {
+    /// The default entropy source is non-deterministic and seeded from the operating system.
+    /// For a deterministic source, use [`Entropy::from`].
+    fn default() -> Self {
+        debug!("Entropy created via the operating system");
+        let rng = StdRng::from_entropy();
+        Entropy(rng)
+    }
+}
+
+impl Entropy {
+    /// Create a deterministic source of entropy. All random number generators
+    /// later seeded from an [`Entropy`] created this way will be deterministic.
+    /// If determinism is not required, use [`Entropy::default`].
+    pub fn from(seed: [u8; 32]) -> Self {
+        debug!("Entropy created via seed: {:?} ", seed);
+        let rng = StdRng::from_seed(seed);
+        Entropy(rng)
+    }
+
+    /// Fill `dest` with entropy data. For an allocating alternative, see [`Entropy::get`].
+    pub fn fill_bytes(&mut self, dest: &mut [u8]) {
+        self.0.fill_bytes(dest)
+    }
+
+    /// Allocate and return entropy data. For a non-allocating alternative, see [`Entropy::fill_bytes`].
+    pub fn get(&mut self) -> [u8; 32] {
+        let mut dest = [0; 32];
+        self.0.fill_bytes(&mut dest);
+        dest
+    }
+}

crates/bevy_internal/Cargo.toml

@@ -55,6 +55,7 @@ bevy_core = { path = "../bevy_core", version = "0.5.0" }
 bevy_derive = { path = "../bevy_derive", version = "0.5.0" }
 bevy_diagnostic = { path = "../bevy_diagnostic", version = "0.5.0" }
 bevy_ecs = { path = "../bevy_ecs", version = "0.5.0" }
+bevy_entropy = { path = "../bevy_entropy", version = "0.5.0" }
 bevy_input = { path = "../bevy_input", version = "0.5.0" }
 bevy_log = { path = "../bevy_log", version = "0.5.0" }
 bevy_math = { path = "../bevy_math", version = "0.5.0" }

crates/bevy_internal/src/default_plugins.rs

@@ -6,6 +6,7 @@ use bevy_asset::AssetPlugin;
 use bevy_audio::AudioPlugin;
 use bevy_core::CorePlugin;
 use bevy_diagnostic::DiagnosticsPlugin;
+use bevy_entropy::EntropyPlugin;
 #[cfg(feature = "bevy_gilrs")]
 use bevy_gilrs::GilrsPlugin;
 #[cfg(feature = "bevy_gltf")]
@@ -39,6 +40,7 @@ use bevy_winit::WinitPlugin;
 /// * [`WindowPlugin`]
 /// * [`AssetPlugin`]
 /// * [`ScenePlugin`]
+/// * [`EntropyPlugin`]
 /// * [`RenderPlugin`] - with feature `bevy_render`
 /// * [`SpritePlugin`] - with feature `bevy_sprite`
 /// * [`PbrPlugin`] - with feature `bevy_pbr`
@@ -61,6 +63,7 @@ impl PluginGroup for DefaultPlugins {
         group.add(WindowPlugin::default());
         group.add(AssetPlugin::default());
         group.add(ScenePlugin::default());
+        group.add(EntropyPlugin::default());
 
         #[cfg(feature = "bevy_render")]
         group.add(RenderPlugin::default());

crates/bevy_internal/src/lib.rs

@@ -29,6 +29,11 @@ pub mod ecs {
     pub use bevy_ecs::*;
 }
 
+pub mod entropy {
+    //! Resources for entropy.
+    pub use bevy_entropy::*;
+}
+
 pub mod input {
     //! Resources and events for inputs, e.g. mouse/keyboard, touch, gamepads, etc.
     pub use bevy_input::*;

crates/bevy_internal/src/prelude.rs

@@ -1,7 +1,7 @@
 #[doc(hidden)]
 pub use crate::{
-    app::prelude::*, asset::prelude::*, core::prelude::*, ecs::prelude::*, input::prelude::*,
-    log::prelude::*, math::prelude::*, reflect::prelude::*, scene::prelude::*,
+    app::prelude::*, asset::prelude::*, core::prelude::*, ecs::prelude::*, entropy::prelude::*,
+    input::prelude::*, log::prelude::*, math::prelude::*, reflect::prelude::*, scene::prelude::*,
     transform::prelude::*, window::prelude::*, DefaultPlugins, MinimalPlugins,
 };
 

examples/2d/contributors.rs

@@ -1,13 +1,16 @@
 use bevy::prelude::*;
-use rand::{prelude::SliceRandom, Rng};
+use rand::{prelude::SliceRandom, rngs::SmallRng, Rng, SeedableRng};
 use std::{
     collections::BTreeSet,
     io::{BufRead, BufReader},
     process::Stdio,
 };
 
 fn main() {
+    let world_seed = [1; 32];
+
     App::build()
+        .insert_resource(Entropy::from(world_seed))
         .add_plugins(DefaultPlugins)
         .add_startup_system(setup)
         .add_system(velocity_system)
@@ -52,6 +55,7 @@ fn setup(
     mut commands: Commands,
     asset_server: Res<AssetServer>,
     mut materials: ResMut<Assets<ColorMaterial>>,
+    mut entropy: ResMut<Entropy>,
 ) {
     let contribs = contributors();
 
@@ -65,7 +69,7 @@ fn setup(
         idx: 0,
     };
 
-    let mut rnd = rand::thread_rng();
+    let mut rnd = SmallRng::from_seed(entropy.get());
 
     for name in contribs {
         let pos = (rnd.gen_range(-400.0..400.0), rnd.gen_range(0.0..400.0));
@@ -246,8 +250,9 @@ fn velocity_system(time: Res<Time>, mut q: Query<&mut Velocity>) {
 fn collision_system(
     wins: Res<Windows>,
     mut q: Query<(&mut Velocity, &mut Transform), With<Contributor>>,
+    mut entropy: ResMut<Entropy>,
 ) {
-    let mut rnd = rand::thread_rng();
+    let mut rnd = SmallRng::from_seed(entropy.get());
 
     let win = wins.get_primary().unwrap();
 

examples/2d/many_sprites.rs

@@ -5,7 +5,7 @@ use bevy::{
     sprite::SpriteSettings,
 };
 
-use rand::Rng;
+use rand::{rngs::SmallRng, Rng, SeedableRng};
 
 const CAMERA_SPEED: f32 = 1000.0;
 
@@ -15,7 +15,10 @@ pub struct Position(Transform);
 /// This example is for performance testing purposes.
 /// See https://github.com/bevyengine/bevy/pull/1492
 fn main() {
+    let world_seed = [1; 32];
+
     App::build()
+        .insert_resource(Entropy::from(world_seed))
         .add_plugin(LogDiagnosticsPlugin::default())
         .add_plugin(FrameTimeDiagnosticsPlugin::default())
         .insert_resource(SpriteSettings {
@@ -33,8 +36,9 @@ fn setup(
     mut commands: Commands,
     assets: Res<AssetServer>,
     mut materials: ResMut<Assets<ColorMaterial>>,
+    mut entropy: ResMut<Entropy>,
 ) {
-    let mut rng = rand::thread_rng();
+    let mut rng = SmallRng::from_seed(entropy.get());
 
     let tile_size = Vec2::splat(64.0);
     let map_size = Vec2::splat(320.0);

examples/3d/spawner.rs

@@ -2,7 +2,7 @@ use bevy::{
     diagnostic::{FrameTimeDiagnosticsPlugin, LogDiagnosticsPlugin},
     prelude::*,
 };
-use rand::{rngs::StdRng, Rng, SeedableRng};
+use rand::{rngs::SmallRng, Rng, SeedableRng};
 
 /// This example spawns a large number of cubes, each with its own changing position and material
 /// This is intended to be a stress test of bevy's ability to render many objects with different
@@ -13,7 +13,10 @@ use rand::{rngs::StdRng, Rng, SeedableRng};
 /// NOTE: Bevy still has a number of optimizations to do in this area. Expect the
 /// performance here to go way up in the future
 fn main() {
+    let world_seed = [1; 32];
+
     App::build()
+        .insert_resource(Entropy::from(world_seed))
         .add_plugins(DefaultPlugins)
         .add_plugin(FrameTimeDiagnosticsPlugin::default())
         .add_plugin(LogDiagnosticsPlugin::default())
@@ -39,6 +42,7 @@ fn setup(
     mut commands: Commands,
     mut meshes: ResMut<Assets<Mesh>>,
     mut materials: ResMut<Assets<StandardMaterial>>,
+    mut entropy: ResMut<Entropy>,
 ) {
     // light
     commands.spawn_bundle(PointLightBundle {
@@ -51,7 +55,7 @@ fn setup(
         ..Default::default()
     });
 
-    let mut rng = StdRng::from_entropy();
+    let mut rng = SmallRng::from_seed(entropy.get());
     let cube_handle = meshes.add(Mesh::from(shape::Cube { size: 1.0 }));
     for _ in 0..10000 {
         commands.spawn_bundle(PbrBundle {