add more example comments

Cargo.toml

@@ -38,8 +38,6 @@ bevy_ui = { path = "crates/bevy_ui" }
 bevy_window = { path = "crates/bevy_window" }
 bevy_wgpu = { path = "crates/bevy_wgpu", optional = true }
 bevy_winit = { path = "crates/bevy_winit", optional = true }
-# other
-log = { version = "0.4", features = ["release_max_level_info"] }
 
 [dev-dependencies]
 rand = "0.7.2"
@@ -189,10 +187,6 @@ path = "examples/ui/font_atlas_debug.rs"
 name = "ui"
 path = "examples/ui/ui.rs"
 
-[[example]]
-name = "ui_bench"
-path = "examples/ui/ui_bench.rs"
-
 [[example]]
 name = "clear_color"
 path = "examples/window/clear_color.rs"

crates/bevy_render/src/color.rs

@@ -5,10 +5,10 @@ use crate::{
 };
 use bevy_asset::Handle;
 use bevy_core::{Byteable, Bytes};
-use bevy_math::Vec4;
+use bevy_math::{Vec3, Vec4};
 use bevy_property::Property;
 use serde::{Deserialize, Serialize};
-use std::ops::{Add, AddAssign};
+use std::ops::{Add, AddAssign, Mul, MulAssign};
 
 #[repr(C)]
 #[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize, Property)]
@@ -95,6 +95,67 @@ impl Into<[f32; 4]> for Color {
         [self.r, self.g, self.b, self.a]
     }
 }
+impl Mul<f32> for Color {
+    type Output = Color;
+    fn mul(self, rhs: f32) -> Self::Output {
+        Color {
+            r: self.r * rhs,
+            g: self.g * rhs,
+            b: self.b * rhs,
+            a: self.a * rhs,
+        }
+    }
+}
+
+impl MulAssign<f32> for Color {
+    fn mul_assign(&mut self, rhs: f32) {
+        self.r *= rhs;
+        self.g *= rhs;
+        self.b *= rhs;
+        self.a *= rhs;
+    }
+}
+
+impl Mul<Vec4> for Color {
+    type Output = Color;
+    fn mul(self, rhs: Vec4) -> Self::Output {
+        Color {
+            r: self.r * rhs.x(),
+            g: self.g * rhs.y(),
+            b: self.b * rhs.z(),
+            a: self.a * rhs.w(),
+        }
+    }
+}
+
+impl MulAssign<Vec4> for Color {
+    fn mul_assign(&mut self, rhs: Vec4) {
+        self.r *= rhs.x();
+        self.g *= rhs.y();
+        self.b *= rhs.z();
+        self.a *= rhs.w();
+    }
+}
+
+impl Mul<Vec3> for Color {
+    type Output = Color;
+    fn mul(self, rhs: Vec3) -> Self::Output {
+        Color {
+            r: self.r * rhs.x(),
+            g: self.g * rhs.y(),
+            b: self.b * rhs.z(),
+            a: self.a
+        }
+    }
+}
+
+impl MulAssign<Vec3> for Color {
+    fn mul_assign(&mut self, rhs: Vec3) {
+        self.r *= rhs.x();
+        self.g *= rhs.y();
+        self.b *= rhs.z();
+    }
+}
 
 impl Bytes for ColorSource {
     fn write_bytes(&self, buffer: &mut [u8]) {

examples/2d/texture_atlas.rs

@@ -4,10 +4,10 @@ use bevy::{
     sprite::TextureAtlasBuilder,
 };
 
+/// In this example we generate a new texture atlas (sprite sheet) from a folder containing individual sprites
 fn main() {
     App::build()
         .init_resource::<RpgSpriteHandles>()
-        .init_resource::<State>()
         .add_default_plugins()
         .add_startup_system(setup.system())
         .add_system(load_atlas.system())
@@ -17,6 +17,7 @@ fn main() {
 #[derive(Default)]
 pub struct RpgSpriteHandles {
     handles: Vec<HandleId>,
+    atlas_loaded: bool,
 }
 
 fn setup(
@@ -27,24 +28,19 @@ fn setup(
     rpg_sprite_handles.handles = asset_server
         .load_asset_folder("assets/textures/rpg")
         .unwrap();
-    commands.spawn(Camera2dComponents::default());
-}
-
-#[derive(Default)]
-struct State {
-    atlas_loaded: bool,
+        commands
+            .spawn(Camera2dComponents::default());
 }
 
 fn load_atlas(
     mut commands: Commands,
-    mut state: ResMut<State>,
-    rpg_sprite_handles: Res<RpgSpriteHandles>,
+    mut rpg_sprite_handles: ResMut<RpgSpriteHandles>,
     asset_server: Res<AssetServer>,
     mut texture_atlases: ResMut<Assets<TextureAtlas>>,
     mut textures: ResMut<Assets<Texture>>,
     mut materials: ResMut<Assets<ColorMaterial>>,
 ) {
-    if state.atlas_loaded {
+    if rpg_sprite_handles.atlas_loaded {
         return;
     }
 
@@ -65,6 +61,8 @@ fn load_atlas(
             .unwrap();
         let vendor_index = texture_atlas.get_texture_index(vendor_handle).unwrap();
         let atlas_handle = texture_atlases.add(texture_atlas);
+
+        // set up a scene to display our texture atlas
         commands
             // draw a sprite from the atlas
             .spawn(SpriteSheetComponents {
@@ -81,6 +79,6 @@ fn load_atlas(
                 ..Default::default()
             });
 
-        state.atlas_loaded = true;
+        rpg_sprite_handles.atlas_loaded = true;
     }
 }

examples/3d/3d_scene.rs

@@ -7,7 +7,7 @@ fn main() {
         .run();
 }
 
-/// set up a simple scene
+/// set up a simple 3D scene
 fn setup(
     mut commands: Commands,
     mut meshes: ResMut<Assets<Mesh>>,

examples/3d/spawner.rs

@@ -4,6 +4,10 @@ use bevy::{
 };
 use rand::{rngs::StdRng, 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 properties
+/// For the best results, run it in release mode: ```cargo run --example spawner --release
+/// 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() {
     App::build()
         .add_default_plugins()
@@ -22,7 +26,8 @@ fn move_cubes(
     for (mut translation, material_handle) in &mut query.iter() {
         let material = materials.get_mut(&material_handle).unwrap();
         translation.0 += Vec3::new(1.0, 0.0, 0.0) * time.delta_seconds;
-        material.albedo += Color::rgb(-time.delta_seconds, -time.delta_seconds, time.delta_seconds);
+        material.albedo =
+            Color::BLUE * Vec3::splat((3.0 * time.seconds_since_startup as f32).sin());
     }
 }
 
@@ -32,30 +37,7 @@ fn setup(
     mut materials: ResMut<Assets<StandardMaterial>>,
 ) {
     let cube_handle = meshes.add(Mesh::from(shape::Cube { size: 1.0 }));
-    let plane_handle = meshes.add(Mesh::from(shape::Plane { size: 10.0 }));
-    let cube_material_handle = materials.add(StandardMaterial {
-        albedo: Color::rgb(0.5, 0.4, 0.3),
-        ..Default::default()
-    });
-    let plane_material_handle = materials.add(StandardMaterial {
-        albedo: Color::rgb(0.1, 0.2, 0.1),
-        ..Default::default()
-    });
-
     commands
-        // plane
-        .spawn(PbrComponents {
-            mesh: plane_handle,
-            material: plane_material_handle,
-            ..Default::default()
-        })
-        // cube
-        .spawn(PbrComponents {
-            mesh: cube_handle,
-            material: cube_material_handle,
-            translation: Translation::new(0.0, 0.0, 1.0),
-            ..Default::default()
-        })
         // light
         .spawn(LightComponents {
             translation: Translation::new(4.0, -4.0, 5.0),
@@ -64,30 +46,29 @@ fn setup(
         // camera
         .spawn(Camera3dComponents {
             transform: Transform::new_sync_disabled(Mat4::face_toward(
-                Vec3::new(0.0, 150.0, -15.0),
+                Vec3::new(0.0, 15.0, 150.0),
                 Vec3::new(0.0, 0.0, 0.0),
-                Vec3::new(0.0, 1.0, 0.0),
+                Vec3::new(0.0, 0.0, 1.0),
             )),
             ..Default::default()
         });
 
     let mut rng = StdRng::from_entropy();
     for _ in 0..10000 {
-        let spawned_material_handle = materials.add(StandardMaterial {
-            albedo: Color::rgb(
-                rng.gen_range(0.0, 1.0),
-                rng.gen_range(0.0, 1.0),
-                rng.gen_range(0.0, 1.0),
-            ),
-            ..Default::default()
-        });
         commands.spawn(PbrComponents {
             mesh: cube_handle,
-            material: spawned_material_handle,
+            material: materials.add(StandardMaterial {
+                albedo: Color::rgb(
+                    rng.gen_range(0.0, 1.0),
+                    rng.gen_range(0.0, 1.0),
+                    rng.gen_range(0.0, 1.0),
+                ),
+                ..Default::default()
+            }),
             translation: Translation::new(
                 rng.gen_range(-50.0, 50.0),
-                0.0,
                 rng.gen_range(-50.0, 50.0),
+                0.0,
             ),
             ..Default::default()
         });

examples/3d/z_sort_debug.rs

@@ -6,8 +6,7 @@ use bevy::{
     },
 };
 
-struct Rotator;
-
+/// This example visualizes camera z-ordering by setting the material of rotating cubes to their distance from the camera
 fn main() {
     App::build()
         .add_default_plugins()
@@ -17,6 +16,8 @@ fn main() {
         .run();
 }
 
+struct Rotator;
+
 /// rotates the parent, which will result in the child also rotating
 fn rotator_system(time: Res<Time>, mut query: Query<(&Rotator, &mut Rotation)>) {
     for (_rotator, mut rotation) in &mut query.iter() {
@@ -42,7 +43,6 @@ fn camera_order_color_system(
     }
 }
 
-/// set up a simple scene with a "parent" cube and a "child" cube
 fn setup(
     mut commands: Commands,
     mut meshes: ResMut<Assets<Mesh>>,

examples/app/plugin.rs

@@ -1,8 +1,9 @@
 use bevy::prelude::*;
 use std::time::Duration;
 
-// Plugins are the foundation of Bevy. They are scoped sets of components, resources, and systems
-// that provide a specific piece of functionality (generally the smaller the scope, the better).
+/// Plugins are the foundation of Bevy. They are scoped sets of components, resources, and systems
+/// that provide a specific piece of functionality (generally the smaller the scope, the better).
+/// This example illustrates how to create a simple plugin that prints out a message.
 fn main() {
     App::build()
         .add_default_plugins()

examples/asset/asset_loading.rs

@@ -1,5 +1,6 @@
 use bevy::prelude::*;
 
+/// This example illustrates various ways to load assets
 fn main() {
     App::build()
         .add_default_plugins()

examples/asset/hot_asset_reloading.rs

@@ -2,6 +2,7 @@ use bevy::prelude::*;
 
 /// Hot reloading allows you to modify assets on disk and they will be "live reloaded" while your game is running.
 /// This lets you immediately see the results of your changes without restarting the game.
+/// This example illustrates hot reloading mesh changes.
 fn main() {
     App::build()
         .add_default_plugins()

examples/audio/audio.rs

@@ -1,5 +1,6 @@
 use bevy::prelude::*;
 
+/// This example illustrates how to load and play an audio file
 fn main() {
     App::build()
         .add_default_plugins()

examples/diagnostics/custom_diagnostic.rs

@@ -3,6 +3,7 @@ use bevy::{
     prelude::*,
 };
 
+/// This example illustrates how to create a custom diagnostic
 fn main() {
     App::build()
         .add_default_plugins()

examples/ecs/event.rs

@@ -1,5 +1,7 @@
 use bevy::prelude::*;
 
+/// This example creates a new event, a system that triggers the event once per second,
+/// and a system that prints a message whenever the event is received.
 fn main() {
     App::build()
         .add_default_plugins()

examples/ecs/startup_system.rs

@@ -1,8 +1,7 @@
-use bevy::{app::ScheduleRunnerPlugin, prelude::*};
+use bevy::prelude::*;
 
 fn main() {
     App::build()
-        .add_plugin(ScheduleRunnerPlugin::run_once()) // only run the app once so the printed system order is clearer
         .add_startup_system(startup_system.system())
         .add_system(normal_system.system())
         .run();

examples/game/breakout.rs

@@ -4,6 +4,7 @@ use bevy::{
     sprite::collide_aabb::{collide, Collision},
 };
 
+/// An implementation of the classic game "Breakout"
 fn main() {
     App::build()
         .add_default_plugins()

examples/scene/load_scene.rs

@@ -1,5 +1,6 @@
 use bevy::{prelude::*, type_registry::TypeRegistry};
 
+/// This example illustrates loading and saving scenes from files
 fn main() {
     App::build()
         .add_default_plugins()

examples/scene/properties.rs

@@ -6,6 +6,9 @@ use bevy::{
 };
 use serde::{Deserialize, Serialize};
 
+/// This example illustrates how Properties work. Properties provide a way to dynamically interact with Rust struct fields using
+/// their names. Properties are a core part of Bevy and enable a number of interesting scenarios (like scenes). If you are
+/// familiar with "reflection" in other languages, Properties are very similar to that concept. 
 fn main() {
     App::build()
         .add_default_plugins()

examples/shader/shader_custom_material.rs

@@ -9,6 +9,7 @@ use bevy::{
     },
 };
 
+/// This example illustrates how to create a custom material asset and a shader that uses that uses that material
 fn main() {
     App::build()
         .add_default_plugins()

examples/shader/shader_defs.rs

@@ -9,6 +9,8 @@ use bevy::{
     },
 };
 
+/// This example illustrates how to create a custom material asset that uses "shader defs" and a shader that uses that uses that material.
+/// In Bevy, "shader defs" are a way to selectively enable parts of a shader based on values set in a component or asset.
 fn main() {
     App::build()
         .add_default_plugins()

examples/ui/button.rs

@@ -1,5 +1,6 @@
 use bevy::prelude::*;
 
+/// This example illustrates how to create a button that changes color and text based on its interaction state.
 fn main() {
     App::build()
         .add_default_plugins()

examples/ui/font_atlas_debug.rs

@@ -1,5 +1,6 @@
 use bevy::{prelude::*, text::FontAtlasSet};
 
+/// This example illustrates how FontAtlases are populated. Bevy uses FontAtlases under the hood to optimize text rendering. 
 fn main() {
     App::build()
         .init_resource::<State>()

examples/ui/text.rs

@@ -3,6 +3,7 @@ use bevy::{
     prelude::*,
 };
 
+/// This example illustrates how to create text and update it in a system. It displays the current FPS in the upper left hand corner.
 fn main() {
     App::build()
         .add_default_plugins()

examples/ui/ui.rs

@@ -1,5 +1,6 @@
 use bevy::prelude::*;
 
+/// This example illustrates the various features of Bevy UI.
 fn main() {
     App::build()
         .add_default_plugins()

examples/ui/ui_bench.rs

@@ -1,52 +0,0 @@
-use bevy::prelude::*;
-
-fn main() {
-    App::build()
-        .add_default_plugins()
-        .add_startup_system(setup.system())
-        .add_system(placement_system.system())
-        .run();
-}
-
-fn placement_system(
-    time: Res<Time>,
-    materials: Res<Assets<ColorMaterial>>,
-    mut query: Query<(&mut Style, &Handle<ColorMaterial>)>,
-) {
-    for (mut style, material_handle) in &mut query.iter() {
-        let material = materials.get(&material_handle).unwrap();
-        if material.color.r > 0.2 {
-            style.position.left += 0.1 * time.delta_seconds;
-        }
-    }
-}
-
-fn setup(mut commands: Commands, mut materials: ResMut<Assets<ColorMaterial>>) {
-    // 2d camera
-    commands.spawn(Camera2dComponents::default());
-
-    let mut prev = Vec2::default();
-    let count = 1000;
-    for i in 0..count {
-        let cur = Vec2::new(1.0, 1.0) + prev;
-        commands.spawn(NodeComponents {
-            style: Style {
-                size: Size {
-                    width: Val::Px(100.0),
-                    height: Val::Px(100.0),
-                },
-                position_type: PositionType::Absolute,
-                position: Rect {
-                    left: Val::Px(75.0 + cur.x()),
-                    bottom: Val::Px(75.0 + cur.y()),
-                    ..Default::default()
-                },
-                ..Default::default()
-            },
-            material: materials.add(Color::rgb(0.0 + i as f32 / count as f32, 0.1, 0.1).into()),
-            ..Default::default()
-        });
-
-        prev = cur;
-    }
-}

examples/window/multiple_windows.rs

@@ -9,6 +9,7 @@ use bevy::{
     window::{CreateWindow, WindowDescriptor, WindowId},
 };
 
+/// This example creates a second window and draws a mesh from two different cameras. 
 fn main() {
     App::build()
         .add_default_plugins()
@@ -58,7 +59,7 @@ fn setup(
         ),
     );
 
-    // add a new depth texture node for our new window
+    // add a new camera node for our new window
     render_graph.add_system_node("secondary_camera", CameraNode::new("Secondary"));
 
     // add a new render pass for our new camera

examples/window/window_settings.rs

@@ -1,5 +1,6 @@
 use bevy::prelude::*;
 
+/// This example illustrates how to customize the default window settings
 fn main() {
     App::build()
         .add_resource(WindowDescriptor {