big round of doc updates

Author: CleanCut

CHANGELOG.md

@@ -3,7 +3,7 @@
 
 ### Improved
 
-- Clarified the audio sections of the tutorial.
+- Made a pass through the API documentation and Tutorials, clarifying, correcting, and filling in blanks.
 
 ## [5.0.5] - 2022-05-10
 

README.md

@@ -1,5 +1,3 @@
-If you like Rusty Engine, please sponsor me [on GitHub] or [on Patreon], or [take one of my courses](https://agileperception.com). 💖
-
 # Rusty Engine
 
 Rusty Engine is a simple, 2D game engine for those who are learning Rust. Create simple game prototypes using straightforward Rust code without needing to learning difficult game engine concepts! It works on macOS, Linux, and Windows. Rusty Engine is a simplification wrapper over [Bevy], which I encourage you to use directly for more serious game engine needs.
@@ -8,6 +6,13 @@ Rusty Engine is a simple, 2D game engine for those who are learning Rust. Create
 
 https://user-images.githubusercontent.com/5838512/122880590-651bae00-d2f7-11eb-8e5c-4810b3777828.mp4
 
+## Documentation
+
+- [Tutorial](https://cleancut.github.io/rusty_engine/)
+- [API Reference](https://docs.rs/rusty_engine/latest/rusty_engine/)
+- [Code Examples](https://github.com/CleanCut/rusty_engine/tree/main/examples)
+- [Game Scenarios](https://github.com/CleanCut/rusty_engine/tree/main/scenarios)
+
 ## Features
 
 - Asset pack included (sprites, music, sound effects, and fonts)
@@ -26,28 +31,25 @@ https://user-images.githubusercontent.com/5838512/122880590-651bae00-d2f7-11eb-8
 
 ## Courses
 
+If you like Rusty Engine, please sponsor me [on GitHub] or [on Patreon], or take one of my courses below!
+
 The following courses use Rusty Engine in their curriculum:
 
 - [Ultimate Rust 2: Intermediate Concepts](https://www.udemy.com/course/ultimate-rust-2/?referralCode=8ED694EBE5637F954414) on Udemy (the sequel to [Ultimate Rust Crash Course](https://www.udemy.com/course/ultimate-rust-crash-course/?referralCode=AF30FAD8C6CCCC2C94F0))
 - [Rust in 3 Weeks](https://agileperception.com) conducted live on O'Reilly Online approximately once each quarter.
 
-## Documentation
-
-- [Rusty Engine Tutorial](https://cleancut.github.io/rusty_engine/)
-- [Rusty Engine API Reference](https://docs.rs/rusty_engine/latest/rusty_engine/)
-- [Game Scenarios](https://github.com/CleanCut/rusty_engine/tree/main/scenarios)
-
 ## Linux Dependencies (Including WSL 2)
 
 If you are using Linux or Windows Subsystem for Linux 2, please visit Bevy's [Installing Linux Dependencies](https://github.com/bevyengine/bevy/blob/main/docs/linux_dependencies.md) page and follow the instructions to install needed dependencies.
 
 ## Quick Start
 
 ### You MUST download the assets separately!!!
+
 Here are three different ways to download the assets (pick any of them--it should end up the same in the end):
 - Clone the `rusty_engine` repository and copy/move the `assets/` directory over to your own project
 - Download a [zip file](https://github.com/CleanCut/rusty_engine/archive/refs/heads/main.zip) or [tarball](https://github.com/CleanCut/rusty_engine/archive/refs/heads/main.tar.gz) of the `rusty_engine` repository, extract it, and copy/move the `assets/` directory over to your own project.
-- On a posix compatible shell, run this command inside your project directory:
+- (My favorite!) On a posix compatible shell, run this command inside your project directory:
 ```shell
 curl -L https://github.com/CleanCut/rusty_engine/archive/refs/heads/main.tar.gz | tar -zxv --strip-components=1 rusty_engine-main/assets
 ```
@@ -73,7 +75,7 @@ Write your game!
  fn main() {
      // Create a game
      let mut game = Game::new();
-     // Set up your game. `Game` exposes all of the methods (but not fields) of `Engine` as well.
+     // Set up your game. `Game` exposes all of the methods and fields of `Engine`.
      let sprite = game.add_sprite("player", SpritePreset::RacingCarBlue);
      sprite.scale = 2.0;
      game.audio_manager.play_music(MusicPreset::Classy8Bit, 1.0);
@@ -87,7 +89,7 @@ Write your game!
 
  // Your game logic functions can be named anything, but the first parameter is always a
  // `&mut Engine`, and the second parameter is a mutable reference to your custom game
- // state struct (`&mut GameState` in this case). The function returns a `bool`.
+ // state struct (`&mut GameState` in this case).
  //
  // This function will be run once each frame.
  fn game_logic(engine: &mut Engine, game_state: &mut GameState) {
@@ -101,15 +103,14 @@ Write your game!
          game_state.health -= 1;
      }
  }
-
 ```
 
 Run your game with `cargo run --release`!
 
 <img width="1348" alt="example screenshot" src="https://user-images.githubusercontent.com/5838512/146858022-1d91c7f4-8b21-4f85-a72a-c4b93edcabc6.png">
 
 
-See also the [game scenarios](https://github.com/CleanCut/rusty_engine/tree/main/scenarios), [code examples](https://github.com/CleanCut/rusty_engine/tree/main/examples) and the [API documentation](https://docs.rs/rusty_engine/latest/rusty_engine/)
+See also the [tutorial](https://cleancut.github.io/rusty_engine/), [game scenarios](https://github.com/CleanCut/rusty_engine/tree/main/scenarios), [code examples](https://github.com/CleanCut/rusty_engine/tree/main/examples) and the [API documentation](https://docs.rs/rusty_engine/latest/rusty_engine/)
 
 ## Contribution
 

src/audio.rs

@@ -1,9 +1,9 @@
 //! Facilities for interacting with audio, including: [`AudioManager`], [`MusicPreset`], and
 //! [`SfxPreset`]
 //!
-//! You may add your own sound files to the `assets/audio` directory or any of its subdirectories
+//! You may add your own sound files to the `assets/` directory or any of its subdirectories
 //! and play them as sound effects or music by providing the relative path to the file. For example,
-//!  if you place a file named `my_sound_effect.mp3` in this directory, you could play it with:
+//!  if you place a file named `my_sound_effect.mp3` in `assets/`, you can play it with:
 //!
 //! ```rust,no_run
 //! # use rusty_engine::prelude::*;
@@ -16,7 +16,8 @@
 //! # }
 //! ```
 //!
-//! Or, if you create a `my_game/` subdirectory and place a file named `spooky_loop.ogg`, you could play it as continuous music with:
+//! Or, if you create a `assets/my_game/` subdirectory and place a file named `spooky_loop.ogg`, you
+//! could play it as continuous music with:
 //!
 //! ```rust,no_run
 //! # use rusty_engine::prelude::*;
@@ -29,7 +30,8 @@
 //! # }
 //! ```
 //!
-//! The sound effects provided in this asset pack have convenient `enum`s defined that you can use instead of a path to the file: `SfxPreset` and `MusicPreset`. For example:
+//! The sound effects provided in this asset pack have convenient `enum`s defined that you can use
+//! instead of a path to the file: `SfxPreset` and `MusicPreset`. For example:
 //!
 //! ```rust,no_run
 //! // Import the enums into scope first
@@ -60,9 +62,10 @@ impl Plugin for AudioManagerPlugin {
     }
 }
 
-/// You will interact with a [`AudioManager`] for all audio needs in Rusty Engine. It is exposed
+/// You will interact with the [`AudioManager`] for all audio needs in Rusty Engine. It is exposed
 /// through the [`Engine`](crate::prelude::Engine) struct provided to your logic function
-/// each frame as the [`audio_manager`](crate::prelude::Engine::audio_manager) field.
+/// each frame as the [`audio_manager`](crate::prelude::Engine::audio_manager) field. It is also
+/// accessible through the [`Game`](crate::prelude::Game) struct in your `main` function.
 #[derive(Default)]
 pub struct AudioManager {
     sfx_queue: Vec<(String, f32)>,
@@ -83,7 +86,7 @@ impl Debug for AudioManager {
 
 impl AudioManager {
     /// Play a sound effect. `volume` ranges from `0.0` to `1.0`. `sfx` can be an [`SfxPreset`] or a
-    /// string containing the relative path/filename of a sound file within the `assets/audio`
+    /// string containing the relative path/filename of a sound file within the `assets/`
     /// directory. Sound effects are "fire and forget". They will play to completion and then stop.
     /// Multiple sound effects will be mixed and play simultaneously.
     pub fn play_sfx<S: Into<String>>(&mut self, sfx: S, volume: f32) {
@@ -92,7 +95,7 @@ impl AudioManager {
     /// Play looping music. `volume` ranges from `0.0` to `1.0`. Music will loop until stopped with
     /// [`stop_music`](AudioManager::stop_music). Playing music stops any previously playing music.
     /// `music` can be a [`MusicPreset`] or a string containing the relative path/filename of a
-    /// sound file within the `assets/audio` directory.
+    /// sound file within the `assets/` directory.
     pub fn play_music<S: Into<String>>(&mut self, music: S, volume: f32) {
         self.music_playing = true;
         self.music_queue
@@ -224,7 +227,7 @@ impl From<MusicPreset> for String {
     }
 }
 
-// The Bevy system that checks and see if there is any audio management that needs to be done.
+/// The Bevy system that checks to see if there is any audio management that needs to be done.
 #[doc(hidden)]
 pub fn queue_managed_audio_system(
     asset_server: Res<AssetServer>,

src/game.rs

@@ -31,22 +31,21 @@ use crate::{
 // Public re-export
 pub use bevy::window::{WindowDescriptor, WindowMode, WindowResizeConstraints};
 
-/// Engine is the primary way that you will interact with Rusty Engine. Every frame this struct
-/// is provided to the "logic" function (or closure) that you provided to [`Game::run`]. The
+/// Engine is the primary way that you will interact with Rusty Engine. Each frame this struct
+/// is provided to the "logic" functions (or closures) that you provided to [`Game::add_logic`]. The
 /// fields in this struct are divided into two groups:
 ///
 /// 1. `SYNCED` fields.
 ///
 /// These fields are marked with `SYNCED`. These fields are shared between you and the engine. Each
 /// frame Rusty Engine will populate these fields, then provide them to the user's game logic
 /// function, and then examine any changes the user made and sync those changes back to the engine.
-/// There are dedicated methods to create items for these fields.
 ///
 /// 2. `INFO` fields
 ///
 /// INFO fields are provided as fresh, readable information to you each frame. Since information in
-/// these fields are overwritten every frame, any changes are ignored. Thus, you can feel free to,
-/// e.g. consume all the events out of the `collision_events` vector.
+/// these fields are overwritten every frame, any changes to them are ignored. Thus, you can feel
+/// free to, e.g. consume all the events out of the `collision_events` vector.
 #[derive(Default, Debug)]
 pub struct Engine {
     /// SYNCED - The state of all sprites this frame. To add a sprite, use the
@@ -62,8 +61,10 @@ pub struct Engine {
     // so we can tell if the value changed this frame
     last_show_colliders: bool,
     /// INFO - All the collision events that occurred this frame. For collisions to be generated
-    /// between sprites, both sprites must have [`Sprite.collision`] set to `true`. Collision events
-    /// are generated when two sprites' colliders begin or end overlapping in 2D space.
+    /// between sprites, both sprites must have [`Sprite.collision`] set to `true` and both sprites
+    /// must have colliders (use the collider example to create a collider for your own images).
+    /// Collision events are generated when two sprites' colliders begin or end overlapping in 2D
+    /// space.
     pub collision_events: Vec<CollisionEvent>,
     /// INFO - The current state of mouse location and buttons. Useful for input handling that only
     /// cares about the final state of the mouse each frame, and not the intermediate states.
@@ -105,15 +106,17 @@ pub struct Engine {
     pub time_since_startup_f64: f64,
     /// A struct with methods to play sound effects and music
     pub audio_manager: AudioManager,
-    /// INFO - Window dimensions in logical pixels
+    /// INFO - Window dimensions in logical pixels. On high DPI screens, there will often be four
+    /// physical pixels per logical pixel. On low DPI screens, one logical pixel is one physical
+    /// pixel.
     pub window_dimensions: Vec2,
 }
 
 impl Engine {
     #[must_use]
-    /// Add an [`Sprite`]. Use the `&mut Sprite` that is returned to set the translation, rotation,
-    /// etc. Use a unique label for each sprite. Attempting to add two sprites with the same label
-    /// will crash.
+    /// Create and add a [`Sprite`] to the game. Use the `&mut Sprite` that is returned to adjust
+    /// the translation, rotation, etc. Use a *unique* label for each sprite. Attempting to add two
+    /// sprites with the same label will cause a crash.
     pub fn add_sprite<T: Into<String>, P: Into<PathBuf>>(
         &mut self,
         label: T,
@@ -127,9 +130,9 @@ impl Engine {
     }
 
     #[must_use]
-    /// Add a [`Text`]. Use the `&mut Text` that is returned to set the translation, rotation, etc.
-    /// Use a unique label for each text. Attempting to add two texts with the same label will
-    /// crash.
+    /// Create and add a [`Text`] to the game. Use the `&mut Text` that is returned to adjust the
+    /// translation, rotation, etc. Use a *unique* label for each text. Attempting to add two texts
+    /// with the same label will cause a crash.
     pub fn add_text<T, S>(&mut self, label: T, text: S) -> &mut Text
     where
         T: Into<String>,
@@ -148,13 +151,14 @@ impl Engine {
     }
 }
 
-// startup system - grab window settings, initialize all the starting sprites
+/// startup system - grab window settings, initialize all the starting sprites
 #[doc(hidden)]
 pub fn setup(mut commands: Commands, asset_server: Res<AssetServer>, mut engine: ResMut<Engine>) {
     add_sprites(&mut commands, &asset_server, &mut engine);
     add_texts(&mut commands, &asset_server, &mut engine);
 }
 
+/// Add visible lines representing a collider
 fn add_collider_lines(commands: &mut Commands, sprite: &mut Sprite) {
     // Add the collider lines, a visual representation of the sprite's collider
     let points = sprite.collider.points(); // will be empty vector if NoCollider
@@ -180,7 +184,7 @@ fn add_collider_lines(commands: &mut Commands, sprite: &mut Sprite) {
     sprite.collider_dirty = false;
 }
 
-// helper function: Add Bevy components for all the sprites in engine.sprites
+/// helper function: Add Bevy components for all the sprites in engine.sprites
 #[doc(hidden)]
 pub fn add_sprites(commands: &mut Commands, asset_server: &Res<AssetServer>, engine: &mut Engine) {
     for (_, sprite) in engine.sprites.drain() {
@@ -223,7 +227,7 @@ pub fn add_texts(commands: &mut Commands, asset_server: &Res<AssetServer>, engin
     }
 }
 
-// system - update current window dimensions in the engine, because people resize windows
+/// system - update current window dimensions in the engine, because people resize windows
 #[doc(hidden)]
 pub fn update_window_dimensions(windows: Res<Windows>, mut engine: ResMut<Engine>) {
     // Unwrap: If we can't access the primary window...there's no point to running Rusty Engine
@@ -235,7 +239,7 @@ pub fn update_window_dimensions(windows: Res<Windows>, mut engine: ResMut<Engine
     }
 }
 
-// Component to add to the collider lines visualizations to link them to the sprite they represent
+/// Component to add to the collider lines visualizations to link them to the sprite they represent
 #[derive(Component)]
 #[doc(hidden)]
 pub struct ColliderLines {
@@ -244,11 +248,11 @@ pub struct ColliderLines {
 
 /// A [`Game`] represents the entire game and its data.
 /// By default the game will spawn an empty window, and exit upon Esc or closing of the window.
-/// Under the hood, Rusty Engine syncs the game data to Bevy to power most of the underlying
-/// functionality.
+/// Under the hood, Rusty Engine syncs the game data to [Bevy](https://bevyengine.org/) to power
+/// most of the underlying functionality.
 ///
 /// [`Game`] forwards method calls to [`Engine`] when it can, so you should be able to use all
-/// of the methods in [`Engine`] on [`Game`] during your game setup in your `main()` function.
+/// of the methods from [`Engine`] on [`Game`] during your game setup in your `main()` function.
 pub struct Game<S: Send + Sync + 'static> {
     app: App,
     engine: Engine,
@@ -271,7 +275,7 @@ impl<S: Send + Sync + 'static> Default for Game<S> {
 }
 
 impl<S: Send + Sync + 'static> Game<S> {
-    /// Create an empty [`Game`] with an empty [`Engine`]
+    /// Create an new, empty [`Game`] with an empty [`Engine`]
     pub fn new() -> Self {
         if std::fs::read_dir("assets").is_err() {
             println!("FATAL: Could not find assets directory. Have you downloaded the assets?\nhttps://github.com/CleanCut/rusty_engine#you-must-download-the-assets-separately");
@@ -323,18 +327,17 @@ impl<S: Send + Sync + 'static> Game<S> {
         self.app.run();
     }
 
-    /// `logic_function` is a function or closure that takes two parameters:
+    /// `logic_function` is a function or closure that takes two parameters and returns nothing:
     ///
     /// - `engine: &mut Engine`
-    /// - `game_state`, which is a mutable reference (`&mut`) to the game state struct you defined, or `&mut ()` if you didn't define one.
-    ///
-    /// If `false` is returned, no more logic functions are processed this frame.
+    /// - `game_state`, which is a mutable reference (`&mut`) to the game state struct you defined,
+    ///    or `&mut ()` if you didn't define one.
     pub fn add_logic(&mut self, logic_function: fn(&mut Engine, &mut S)) {
         self.logic_functions.push(logic_function);
     }
 }
 
-// system - the magic that connects Rusty Engine to Bevy, frame by frame
+/// system - the magic that connects Rusty Engine to Bevy, frame by frame
 #[allow(clippy::type_complexity, clippy::too_many_arguments)]
 fn game_logic_sync<S: Send + Sync + 'static>(
     mut commands: Commands,
@@ -359,15 +362,6 @@ fn game_logic_sync<S: Send + Sync + 'static>(
     engine.time_since_startup = time.time_since_startup();
     engine.time_since_startup_f64 = time.seconds_since_startup();
 
-    // TODO: Transfer any changes to the Bevy components by the physics system over to the Sprites
-    // for (mut sprite, mut transform) in sprite_query.iter_mut() {
-    //     sprite.translation = Vec2::from(transform.translation);
-    //     sprite.layer = transform.translation.z;
-    //     // transform.rotation = Quat::from_axis_angle(Vec3::Z, sprite.rotation);
-    //     sprite.rotation = ???
-    //     sprite.scale = transform.scale.x;
-    // }
-
     // Copy keyboard state over to engine to give to users
     engine.keyboard_state = keyboard_state.clone();