From fc958578241058eef4e7973d3aedad4933471969 Mon Sep 17 00:00:00 2001
From: Michael Bradley <michaelmbrad@gmail.com>
Date: Mon, 19 May 2025 21:23:58 -0400
Subject: [PATCH 1/2] Make more random

At least, make the stuff that doesn't need to be deterministic non-deterministic
---
 Cargo.toml        |  2 +-
 src/game/mod.rs   |  3 ++-
 src/game/rng.rs   |  7 +++++++
 src/game/setup.rs | 18 ++++++++----------
 4 files changed, 18 insertions(+), 12 deletions(-)
 create mode 100644 src/game/rng.rs

diff --git a/Cargo.toml b/Cargo.toml
index 3b6ee1c..22b0721 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -37,5 +37,5 @@ log = { version = "*", features = [
 	"max_level_debug",
 	"release_max_level_warn",
 ] }
-rand = { version = "0.9.1", default-features = false, features = ["std"] }
+rand = { version = "0.9.1", default-features = false, features = ["std", "thread_rng"] }
 wyrand = "0.3.2"
diff --git a/src/game/mod.rs b/src/game/mod.rs
index 370d386..cd239ce 100644
--- a/src/game/mod.rs
+++ b/src/game/mod.rs
@@ -1,4 +1,5 @@
-pub mod objects;
+mod objects;
+mod rng;
 pub mod runtime;
 pub mod seed;
 pub mod setup;
diff --git a/src/game/rng.rs b/src/game/rng.rs
new file mode 100644
index 0000000..a9c40ad
--- /dev/null
+++ b/src/game/rng.rs
@@ -0,0 +1,7 @@
+use rand::random;
+use wyrand::WyRand;
+
+/// Initialize a `WyRand` using `rand`'s thread-local rng
+pub fn thread_rng() -> WyRand {
+    WyRand::new(random())
+}
diff --git a/src/game/setup.rs b/src/game/setup.rs
index f1f0770..2551b06 100644
--- a/src/game/setup.rs
+++ b/src/game/setup.rs
@@ -9,10 +9,12 @@ use bevy::{
     prelude::*,
 };
 use bevy_rand::prelude::{GlobalEntropy, WyRand};
-use rand::Rng;
-use wyrand::WyRand as LocalRng;
+use rand::Rng as _;
 
-use super::objects::{Ball, Player, Wall};
+use super::{
+    objects::{Ball, Player, Wall},
+    rng::thread_rng,
+};
 
 const BALL_COUNT: u8 = 32;
 const BALL_SIZES: Range<f32> = 10.0..25.0;
@@ -57,7 +59,7 @@ pub fn setup_balls(
     mut meshes: ResMut<Assets<Mesh>>,
     region: Res<PlayableArea>,
 ) {
-    let mut random = LocalRng::new(Default::default());
+    let mut random = thread_rng();
     for _ in 0..BALL_COUNT {
         let circle = Circle::new(random.random_range(BALL_SIZES));
         commands.spawn((
@@ -66,12 +68,8 @@ pub fn setup_balls(
             Mesh2d(meshes.add(circle)),
             MeshMaterial2d(materials.add(Color::from(RED_400))),
             Transform::from_xyz(
-                random.random_range(
-                    (-region.0 / 2.0 + circle.radius)..(region.0 / 2.0 - circle.radius),
-                ),
-                random.random_range(
-                    (-region.1 / 2.0 + circle.radius)..(region.1 / 2.0 - circle.radius),
-                ),
+                random.random::<f32>() * (region.0 - 2.0 * circle.radius) + circle.radius,
+                random.random::<f32>() * (region.1 - 2.0 * circle.radius) + circle.radius,
                 0.0,
             ),
         ));

From 6a151397de4bad83bc398e705c7e39758aa1d795 Mon Sep 17 00:00:00 2001
From: Michael Bradley <michaelmbrad@gmail.com>
Date: Mon, 19 May 2025 22:19:04 -0400
Subject: [PATCH 2/2] Add function documentation

---
 .vscode/settings.json | 1 +
 src/game/objects.rs   | 4 ++++
 src/game/rng.rs       | 2 +-
 src/game/runtime.rs   | 4 ++++
 src/game/seed.rs      | 3 +++
 src/game/setup.rs     | 6 ++++++
 src/lib.rs            | 2 ++
 7 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/.vscode/settings.json b/.vscode/settings.json
index fe117a2..bc89a82 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -10,6 +10,7 @@
     "despawn",
     "Despawns",
     "lerp",
+    "PRNG",
     "recip",
     "respawns",
     "timestep",
diff --git a/src/game/objects.rs b/src/game/objects.rs
index 2ba8d60..2fbe122 100644
--- a/src/game/objects.rs
+++ b/src/game/objects.rs
@@ -1,18 +1,22 @@
 use avian2d::prelude::*;
 use bevy::prelude::*;
 
+/// Basic implementation of a physics object
 #[derive(Component, Default)]
 #[require(Collider, Mesh2d, MeshMaterial2d<ColorMaterial>, Restitution = Restitution::new(1.0), RigidBody, TransformInterpolation, Transform)]
 struct GameObject;
 
+/// A basic ball with which to interact
 #[derive(Component, Default)]
 #[require(GameObject, RigidBody = RigidBody::Dynamic)]
 pub struct Ball;
 
+/// The controllable ball
 #[derive(Component, Default)]
 #[require(Ball)]
 pub struct Player;
 
+/// The static objects bounding the playable area
 #[derive(Component, Default)]
 #[require(GameObject, RigidBody = RigidBody::Static)]
 pub struct Wall;
diff --git a/src/game/rng.rs b/src/game/rng.rs
index a9c40ad..b80a739 100644
--- a/src/game/rng.rs
+++ b/src/game/rng.rs
@@ -1,7 +1,7 @@
 use rand::random;
 use wyrand::WyRand;
 
-/// Initialize a `WyRand` using `rand`'s thread-local rng
+/// Initialize a `WyRand` using `rand`'s thread-local random number generator
 pub fn thread_rng() -> WyRand {
     WyRand::new(random())
 }
diff --git a/src/game/runtime.rs b/src/game/runtime.rs
index a0ab185..664dc49 100644
--- a/src/game/runtime.rs
+++ b/src/game/runtime.rs
@@ -6,6 +6,7 @@ use bevy::{
 
 use super::objects::Player;
 
+/// Move the player character based on the keyboard input
 pub fn move_player(
     time: Res<Time>,
     keyboard_input: Res<ButtonInput<KeyCode>>,
@@ -31,10 +32,12 @@ pub fn move_player(
     Ok(())
 }
 
+/// Neatly exit game
 pub fn quit(mut exit: EventWriter<AppExit>) {
     exit.write(AppExit::Success);
 }
 
+/// Follow the player character with the camera
 pub fn move_camera(
     mut camera: Single<&mut Transform, (Without<Player>, With<IsDefaultUiCamera>)>,
     player: Single<&Transform, (With<Player>, Without<IsDefaultUiCamera>)>,
@@ -42,6 +45,7 @@ pub fn move_camera(
     camera.translation = camera.translation.lerp(player.translation, 0.05);
 }
 
+/// Adjust the camera zoom based on the scroll wheel input
 pub fn zoom_camera(
     mut camera: Single<&mut Projection, With<IsDefaultUiCamera>>,
     scroll: Res<AccumulatedMouseScroll>,
diff --git a/src/game/seed.rs b/src/game/seed.rs
index 1467ee9..0119b8b 100644
--- a/src/game/seed.rs
+++ b/src/game/seed.rs
@@ -2,10 +2,12 @@ use std::hash::{DefaultHasher, Hash, Hasher};
 
 use bevy::prelude::*;
 
+/// Value with which to initialize the PRNG
 #[derive(Clone, Resource)]
 pub struct Seed(u64);
 
 impl From<String> for Seed {
+    /// Attempt to parse as an integer, fall back to hashing string
     fn from(value: String) -> Self {
         Self(value.parse::<u64>().unwrap_or_else(|_| {
             let mut state = DefaultHasher::new();
@@ -16,6 +18,7 @@ impl From<String> for Seed {
 }
 
 impl From<Seed> for [u8; 8] {
+    /// Convert to a u8 array for ingestion by random number generator
     fn from(value: Seed) -> Self {
         value.0.to_le_bytes()
     }
diff --git a/src/game/setup.rs b/src/game/setup.rs
index 2551b06..71b339c 100644
--- a/src/game/setup.rs
+++ b/src/game/setup.rs
@@ -20,12 +20,15 @@ const BALL_COUNT: u8 = 32;
 const BALL_SIZES: Range<f32> = 10.0..25.0;
 const DIMENSION_SIZES: Range<f32> = 500.0..2000.0;
 
+/// The size of the playable area (x, y)
 #[derive(Resource)]
 pub struct PlayableArea(f32, f32);
 
+/// The size of the player character
 #[derive(Resource)]
 pub struct PlayerSize(f32);
 
+/// Initialize deterministic values
 pub fn setup_pseudo_random(mut commands: Commands, mut rng: GlobalEntropy<WyRand>) {
     commands.insert_resource(PlayerSize(rng.random_range(BALL_SIZES)));
     commands.insert_resource(PlayableArea(
@@ -38,6 +41,7 @@ pub fn setup_ui(mut commands: Commands) {
     commands.spawn((Name::new("Camera"), Camera2d, IsDefaultUiCamera));
 }
 
+/// Create the playable character
 pub fn setup_player(
     mut commands: Commands,
     mut materials: ResMut<Assets<ColorMaterial>>,
@@ -53,6 +57,7 @@ pub fn setup_player(
     ));
 }
 
+/// Create a random distribution of balls in the playable area
 pub fn setup_balls(
     mut commands: Commands,
     mut materials: ResMut<Assets<ColorMaterial>>,
@@ -76,6 +81,7 @@ pub fn setup_balls(
     }
 }
 
+/// Create the 4 walls that enclose the playable area
 pub fn setup_walls(
     mut commands: Commands,
     mut materials: ResMut<Assets<ColorMaterial>>,
diff --git a/src/lib.rs b/src/lib.rs
index 2b74344..1c1a86b 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -10,6 +10,8 @@ use game::{
     setup::{setup_balls, setup_player, setup_pseudo_random, setup_ui, setup_walls},
 };
 
+/// The initial configuration passed to the game's setup functions.
+/// Also functions as a Bevy plugin to pass the configuration into the app.
 #[derive(Parser)]
 #[command(version, about)]
 pub struct AppSettings {