Integration of new WIP Bevy Book

content/learn/book/_index.md

@@ -1,8 +1,4 @@
 +++
-title = "Book"
-sort_by = "weight"
-template = "docs-section.html"
-page_template = "docs-section.html"
-redirect_to = "learn/book/introduction"
+redirect_to = "learn/book/v0.11.0/welcome"
 insert_anchor_links = "right"
 +++

content/learn/book/v0.11.0/_index.md

@@ -0,0 +1,10 @@
++++
+title = "Bevy Book v0.11.0"
+sort_by = "weight"
+template = "book-section.html"
+page_template = "book-section.html"
+redirect_to = "learn/book/v0.11.0/welcome"
+insert_anchor_links = "right"
+[extra]
+header_message = "v0.11.0"
++++

content/learn/book/v0.11.0/assets/_index.md

@@ -0,0 +1,12 @@
++++
+title = "Assets"
+weight = 5
+sort_by = "weight"
+template = "book-section.html"
+page_template = "book-section.html"
+insert_anchor_links = "right"
++++
+
+TODO: explain what an asset is.
+
+TODO: Give a high-level overview of asset loading in Bevy. Make sure to describe how handles work.

content/learn/book/v0.11.0/assets/custom-assets/_index.md

@@ -0,0 +1,10 @@
++++
+title = "Custom assets"
+weight = 3
+sort_by = "weight"
+template = "book-section.html"
+page_template = "book-section.html"
+insert_anchor_links = "right"
++++
+
+TODO: Demonstrate how to write a custom asset loader.

content/learn/book/v0.11.0/assets/hot-reloading/_index.md

@@ -0,0 +1,12 @@
++++
+title = "Hot reloading"
+weight = 4
+sort_by = "weight"
+template = "book-section.html"
+page_template = "book-section.html"
+insert_anchor_links = "right"
++++
+
+TODO: demonstrate how to watch for changes to automatically hot reload assets when modified
+
+Steal from [hot reloading example](https://github.com/bevyengine/bevy/blob/main/examples/asset/hot_asset_reloading.rs)

content/learn/book/v0.11.0/assets/loading-assets/_index.md

@@ -0,0 +1,14 @@
++++
+title = "Loading assets"
+weight = 1
+sort_by = "weight"
+template = "book-section.html"
+page_template = "book-section.html"
+insert_anchor_links = "right"
++++
+
+TODO: Demonstrate how to load assets.
+
+TODO: Discuss how to change the asset loading folder.
+
+TODO: Discuss asset loading patterns to deal with async nature.

content/learn/book/v0.11.0/assets/scenes/_index.md

@@ -0,0 +1,18 @@
++++
+title = "Scenes and reflection"
+weight = 5
+sort_by = "weight"
+template = "book-section.html"
+page_template = "book-section.html"
+insert_anchor_links = "right"
++++
+
+TODO: explain what scenes are
+
+TODO: explain what reflection is
+
+TODO: demonstrate how to use scenes to load a prefab
+
+TODO: demonstrate how to use scenes to load a level
+
+TODO: demonstrate how to use scenes to save and load a game

content/learn/book/v0.11.0/assets/working-with-handles/_index.md

@@ -0,0 +1,16 @@
++++
+title = "Working with handles"
+weight = 2
+sort_by = "weight"
+template = "book-section.html"
+page_template = "book-section.html"
+insert_anchor_links = "right"
++++
+
+TODO: Explain what a handle is, and point to resources on reference counting in Rust
+
+TODO: Demonstrate handle storage patterns
+
+TODO: Demonstrate how to change materials of an asset
+
+TODO: Explain what weak handles are

content/learn/book/v0.11.0/audio/_index.md

@@ -0,0 +1,12 @@
++++
+title = "Audio"
+weight = 7
+sort_by = "weight"
+template = "book-section.html"
+page_template = "book-section.html"
+insert_anchor_links = "right"
++++
+
+TODO: Tiny blurb about audio
+
+TODO: disclaim WIP status, point to `bevy_kira_audio` and competing community crates

content/learn/book/v0.11.0/audio/audio-basics/_index.md

@@ -0,0 +1,12 @@
++++
+title = "Audio basics"
+weight = 1
+sort_by = "weight"
+template = "book-section.html"
+page_template = "book-section.html"
+insert_anchor_links = "right"
++++
+
+TODO: demonstrate how to load and play sounds
+
+TODO: discuss compatible file formats

content/learn/book/v0.11.0/development-practices/_index.md

@@ -0,0 +1,10 @@
++++
+title = "Development practices"
+weight = 9
+sort_by = "weight"
+template = "book-section.html"
+page_template = "book-section.html"
+insert_anchor_links = "right"
++++
+
+TODO: this chapter covers practices that help you write larger Bevy apps in a clearer, safer and more productive way

content/learn/book/v0.11.0/development-practices/boilerplate-reduction/_index.md

@@ -0,0 +1,12 @@
++++
+title = "Boilerplate reduction"
+weight = 5
+sort_by = "weight"
+template = "book-section.html"
+page_template = "book-section.html"
+insert_anchor_links = "right"
++++
+
+TODO: link to resources on macros
+
+TODO: discuss custom system parameters

content/learn/book/v0.11.0/development-practices/error-handling/_index.md

@@ -0,0 +1,14 @@
++++
+title = "Error handling"
+weight = 4
+sort_by = "weight"
+template = "book-section.html"
+page_template = "book-section.html"
+insert_anchor_links = "right"
++++
+
+TODO: discuss errors in Rust, link to other good resources
+
+TODO: explain system chaining, and demonstrate how to apply it to error handling
+
+TODO: explain and demonstrate [error handling in commands](https://github.com/bevyengine/bevy/pull/2241)

content/learn/book/v0.11.0/development-practices/fast-compiles/_index.md

@@ -0,0 +1,52 @@
++++
+title = "Fast compiles"
+weight = 2
+sort_by = "weight"
+template = "book-section.html"
+page_template = "book-section.html"
+insert_anchor_links = "right"
++++
+
+TODO: explain why you might want faster compiles
+
+* **Enable Bevy's Dynamic Linking Feature**: This is the most impactful compilation time decrease! If `bevy` is a dependency you can compile the binary with the "dynamic" feature flag (enables dynamic linking):
+
+    ```sh
+    cargo run --features bevy/dynamic
+    ```
+
+    If you don't want to add the `--features bevy/dynamic` to each run, this flag can permanently be set via `Cargo.toml`:
+
+    ```toml
+    [dependencies]
+    bevy = { version = "0.5.0", features = ["dynamic"] }
+    ```
+
+    NOTE: Remember to revert this before releasing your game! Otherwise you will need to include `libbevy_dylib` alongside your game if you want it to run. If you remove the "dynamic" feature, your game executable can run standalone.
+
+* **LLD linker**: The Rust compiler spends a lot of time in the "link" step. LLD is _much faster_ at linking than the default Rust linker. To install LLD, find your OS below and run the given command:
+  * **Ubuntu**: `sudo apt-get install lld`
+  * **Arch**: `sudo pacman -S lld`
+  * **Windows**: Ensure you have the latest [cargo-binutils](https://github.com/rust-embedded/cargo-binutils)
+
+ ```sh
+ cargo install -f cargo-binutils
+ rustup component add llvm-tools-preview
+ ```
+
+* **MacOS**: Modern LLD does not yet support MacOS, but we can use zld instead: `brew install michaeleisel/zld/zld`
+* **Nightly Rust Compiler**: This gives access to the latest performance improvements and "unstable" optimizations
+
+ ```sh
+    # Install the nightly toolchain
+    rustup toolchain install nightly
+    # Configure your current project to use nightly (run this command within the project)
+    rustup override set nightly
+    # OR configure cargo to use nightly for all projects -- switch back with `rustup default stable`
+    rustup default nightly
+    ```
+
+  * You can use `cargo +nightly ...` if you don't want to change the default to nightly.
+* **Generic Sharing**: Allows crates to share monomorphized generic code instead of duplicating it. In some cases this allows us to "precompile" generic code so it doesn't affect iterative compiles. This is only available on nightly Rust.
+
+To enable fast compiles, install the nightly rust compiler and LLD. Then copy [this file](https://github.com/bevyengine/bevy/blob/main/.cargo/config_fast_builds) to `YOUR_WORKSPACE/.cargo/config.toml`. For the project in this guide, that would be `my_bevy_game/.cargo/config.toml`.

content/learn/book/v0.11.0/development-practices/organizing-your-code/_index.md

@@ -0,0 +1,14 @@
++++
+title = "Organizing your code"
+weight = 1
+sort_by = "weight"
+template = "book-section.html"
+page_template = "book-section.html"
+insert_anchor_links = "right"
++++
+
+TODO: refresh on Rust modules, link to official docs
+
+TODO: discuss plugins as a code organization tool
+
+TODO discuss how to split your code out into libraries

content/learn/book/v0.11.0/development-practices/testing/_index.md

@@ -0,0 +1,16 @@
++++
+title = "Testing"
+weight = 3
+sort_by = "weight"
+template = "book-section.html"
+page_template = "book-section.html"
+insert_anchor_links = "right"
++++
+
+TODO: discuss unit testing using the examples framework
+
+TODO: discuss strategies for integration testing
+
+TODO: discuss input mocking
+
+TODO: discuss setting up CI

content/learn/book/v0.11.0/ecs/_index.md

@@ -0,0 +1,83 @@
++++
+title = "Entities, components and systems"
+weight = 2
+sort_by = "weight"
+template = "book-section.html"
+page_template = "book-section.html"
+insert_anchor_links = "right"
++++
+
+In Bevy, game objects are stored as **entities**, whose data is stored as **components**.
+**Systems** operate on this data, modifying the **world** to carry out the behavior that brings your game to life.
+Together, these these form the basis of Bevy's **ECS**, which unsurprisingly stands for ["Entity-Component-System"](https://en.wikipedia.org/wiki/Entity_component_system).
+Let's go over the most important definitions:
+
+- **World:** A unifying collection of all of the data stored in the ECS.
+  - Access to the [`World`] follows Rust's borrow checker rules: you can read from the same data any number of times, but you must have exclusive access to modify a piece of data.
+- **Entities:** Game objects (either abstract, like a camera, or tangible, like a player character), whose data is stored as components.
+  - The [`Entity`] type is just a simple identifier (like a URL address, a unique name, or a row number in a database).
+- **Components:** Data stored on an entity, that can be manipulated in systems.
+  - Each component has a different Rust type that implements the [`Component`] trait, and only one component of each type can exist for each entity.
+  - Components without data are called **marker components**, and can be used to efficiently select entities that have a specific property (like being `Poisoned`, or defining a `Player`).
+  - Any combination of components can be added to each entity, allowing us to extend and share behavior through composition.
+- **Systems:** Special functions that operate on data from the [`World`]: most commonly modifying the data stored in components on entities.
+  - Any function whose parameters all implement the [`SystemParam`] type can be converted into a [`System`].
+
+Suppose we wanted to make a [Breakout game](https://github.com/bevyengine/bevy/blob/latest/examples/games/breakout.rs) in Bevy.
+Let's think about what entities we might want, what components they might have, and what systems we might create:
+
+- A paddle entity
+  - a `Paddle` marker component, to allow us to uniquely identify the paddle
+  - a [`Sprite`] component, which describes how to draw our paddle
+    - in reality, this is a bit more complex, and requires a [`SpriteBundle`] collection of components
+  - a [`Transform`] component, to let us know the translation (position), rotation (orientation) and scale (size) of our paddles
+  - a `Velocity` component, giving us more realistic movement
+  - a `Collidable` component, to let us know that the ball can bounce off of it
+- A ball entity
+  - a `Ball` marker component, so we can uniquely identify our ball
+  - a [`Sprite`] component
+  - a [`Transform`] component
+  - a `Velocity` component, to ensure the ball keeps moving
+- Brick entities
+  - a [`Brick`] marker component
+  - a [`Sprite`] component
+  - a [`Transform`] component
+  - a `Collidable` component
+- Wall entities
+  - a `Collidable` component, to make sure our ball bounces off the walls
+  - a `Transform` component, so we know where the boundaries are
+
+As you can see, each component implies specific behavior, but does not provide it on it. Components are just data (although they often have simple methods), and only act when systems use them.
+Each of our components is quite small, allowing us to reuse these types and share behavior across entities using systems.
+For our simple Breakout game, we may have:
+
+- `setup`: a simple **startup system** that runs a single time when our game is launched, **spawning** our paddles, ball and walls
+- `apply_velocity`: a system that operates on all entities with a `Transform` and `Velocity`, and moves the entity according to its velocity
+- `handle_collisions`: a system that operates on the `Ball` entity, and any entity with both a `Collidable` component and a `Transform` component, to bounce the ball appropriately
+- `destroy_bricks`: a system that **despawns** entities with the `Brick` marker component when they are collided with
+
+In order to start working with Bevy, you should know a few other critical pieces of ECS vocabulary:
+
+- **Resources:** Globally unique stores of data that live in the [`World`], but are not associated with a specific entity.
+  - Events, configuration and global game state are all commonly stored as resources, which can be accessed with the [`Res`] system parameter.
+- **Queries:** Requests for specific entity-component data from the [`World`].
+  - The [`Query`] type has two type parameters: the first describes what component data should be fetched, and the second filters down which entities with that data should be returned when looping over the query.
+- **Commands:** Instructions to modify the [`World`] at a later point in time.
+  - Most commonly, this is used to spawn and despawn entities, or insert and remove components.
+  - [`Commands`] require [exclusive world access](./exclusive-world-access/), and so are deferred until there are no other systems running.
+
+While there's much more to learn about Bevy's ECS, this basic overview should give you the vocabulary you need to start exploring the rest of this chapter.
+Don't worry if some concepts are too abstract, advanced or impractical for you at this point:
+this book is intended to be skimmed on the first read.
+Refer back to it later for more detailed explanations as you start building your own awesome projects in Bevy!
+
+[`Entity`]: https://docs.rs/bevy/latest/bevy/ecs/entity/struct.Entity.html
+[`Component`]: https://docs.rs/bevy/latest/bevy/ecs/component/trait.Component.html
+[`World`]: https://docs.rs/bevy/latest/bevy/ecs/world/struct.World.html
+[`SystemParam`]: https://docs.rs/bevy/latest/bevy/ecs/system/trait.SystemParam.html
+[`System`]: https://docs.rs/bevy/latest/bevy/ecs/system/trait.System.html
+[`Sprite`]: https://docs.rs/bevy/latest/bevy/sprite/struct.Sprite.html
+[`SpriteBundle`]: https://docs.rs/bevy/latest/bevy/sprite/struct.SpriteBundle.html
+[`Res`]: https://docs.rs/bevy/latest/bevy/ecs/system/struct.Res.html
+[`Query`]: https://docs.rs/bevy/latest/bevy/ecs/system/struct.Query.html
+[`Commands`]: https://docs.rs/bevy/latest/bevy/ecs/system/struct.Commands.html

content/learn/book/v0.11.0/ecs/commands/_index.md

@@ -0,0 +1,7 @@
++++
+title = "Commands queue up work"
+weight = 5
+template = "book-section.html"
+page_template = "book-section.html"
+insert_anchor_links = "right"
++++

content/learn/book/v0.11.0/ecs/detecting-changes/_index.md

@@ -0,0 +1,7 @@
++++
+title = "Detecting changes"
+weight = 6
+template = "book-section.html"
+page_template = "book-section.html"
+insert_anchor_links = "right"
++++

content/learn/book/v0.11.0/ecs/ecs-magic/_index.md

@@ -0,0 +1,7 @@
++++
+title = "Understanding the magic"
+weight = 8
+template = "book-section.html"
+page_template = "book-section.html"
+insert_anchor_links = "right"
++++