Welcome chapter

content/learn/book/welcome/_index.md

@@ -1,9 +1,49 @@
 +++
-title = "Welcome to Bevy"
+title = "Welcome"
 weight = 1
 sort_by = "weight"
 template = "book-section.html"
 page_template = "book-section.html"
 +++
 
-TODO: Briefly discuss what Bevy is.
+Welcome to the Bevy game engine! A bevy may be a group of birds, but our engine is:
+
+- **Rust-first:** all the safety, tooling and power that come with a modern systems language
+- **Completely free:** [free-of-charge](https://github.com/sponsors/cart), [open source](https://github.com/bevyengine/bevy/blob/main/LICENSE), and hackable with an architecture designed for modularity
+- **Innovative ECS:** powered by an ergonomic, full-native entity-component-system architecture that makes writing clear, performant gameplay and engine logic a joy
+- **Cross-platform:** support Windows, MacOS, Linux, web*, Android*, iOS and more** with a single code base
+- **Effortless parallelism:** a data-oriented design and automatic parallel scheduler provide a high-performance foundation for your game
+
+This book is designed for new and experienced users looking for a thoughtful, [explanation-first](https://diataxis.fr/explanation/) guide to the engine's essential features.
+If you just want to try it out hands-on, jump into one of our [quick-start guides](TODO: add link) instead!
+
+*: support for these platforms is still limited; you may encounter some missing features or a more involved setup process
+**: virtual and augmented reality (aka XR) compatability is [in development](https://github.com/bevyengine/bevy/pull/2319)
+
+## Stability warning
+
+Bevy aims to be a general-purpose game engine capable of handling arbitrary 2D or 3D games.
+However, Bevy is still in its infancy, and there are very good reasons not to choose it for your next project.
+No mature solutions currently exist for:
+
+- animation
+- networking
+- console support
+
+The following areas are part of the engine itself, but are very immature:
+
+- audio
+- user interfaces
+
+Solid third-party solutions currently exist for:
+
+- [advanced audio](https://crates.io/crates/bevy_kira_audio)
+- [realistic physics](https://github.com/dimforge/bevy_rapier)
+
+While Bevy's modular architecture makes it relatively easy to integrate your own (or third-party) solutions, be mindful that Bevy does not provide a complete game solution out of the box *yet*.
+[Contributions to the engine](https://github.com/bevyengine/bevy/) are extremely welcome, but if you want something fully-featured to make your dream game *today*, check out [Godot](https://godotengine.org/) instead!
+
+Unsurprisingly, Bevy's rapid pace of development means that our APIs will break, repeatedly, in both deep and pervasive ways.
+This allows us to refine the engine now, adding new features and fixing problems fast, rather than being tied to a first attempt.
+That said, updating versions of Bevy is surprisingly painless; we provide migration guides and Rust's excellent tooling will guide you.
+Chase the errors until everything compiles again and you should be basically done.

content/learn/book/welcome/apps/_index.md

@@ -0,0 +1,81 @@
++++
+title = "Apps"
+weight = 2
+template = "book-section.html"
+page_template = "book-section.html"
++++
+
+Bevy programs store and execute all of their game logic and data with a single {{rust_type(type="struct" crate="bevy" mod = "app" name="App" no_mod = "true")}} data structure.
+
+Let's make a trivial Hello World app to demonstrate how that works in practice.
+The process is straightforward: we first create a new {{rust_type(type="struct" crate="bevy" mod = "app" name="App" no_mod = "true")}}.
+Then, we add a simple system, which prints "Hello, Bevy!" when it is run.
+Finally once we're done configuring the app, we call {{rust_type(type="struct" crate="bevy" mod = "app" name="App" no_mod = "true")}} to actually make our app *do things*.
+
+```rust
+use bevy::prelude::*;
+
+fn main(){
+ App::new()
+ .add_system(hello)
+ .run();
+}
+
+fn hello(){
+ println!("Hello, Bevy!")
+}
+```
+
+## What makes an App?
+
+So, what sort of data does our {{rust_type(type="struct" crate="bevy" mod = "app" name="App" no_mod = "true")}} really store?
+Looking at the docs linked, we find three fields: `world`, `schedule` and `runner`.
+The `world` field stores all of our game's data, the `schedule` holds the systems that operate on this data (and the order in which they do so) and the `runner` interprets the schedule to control the broad execution strategy.
+You can read more about these by exploring the reference documentation linked just above.
+
+Generally, you'll be operating at a more granular level than these basic primitives: controlling data in terms of specific resources or components and adding systems to an existing schedule.
+To do so, customize your own {{rust_type(type="struct" crate="bevy" mod = "app" name="App" no_mod = "true")}} by chaining its methods with the [builder pattern](https://doc.rust-lang.org/1.0.0/style/ownership/builders.html).
+The most basic tools are:
+
+ 1. Initializing resources in the {{rust_type(type="struct" crate="bevy" mod = "ecs/world" name="World" no_mod = "true")}} to store global data.
+ 2. Adding systems to our {{rust_type(type="struct" crate="bevy" mod = "ecs/schedule" name="Schedule" no_mod = "true")}} to perform logic.
+ 3. Importing other blocks of {{rust_type(type="struct" crate="bevy" mod = "app" name="App" no_mod = "true")}}-modifying code using plugins.
+Let's write a very simple demo that shows how those work.
+
+```rust
+use bevy::prelude::*;
+
+fn main() {
+ App::new()
+ // Plugins are App code that was written elsewhere,
+ // imported as a single unit for organization and clarity
+ .add_plugins(DefaultPlugins)
+ // Resources are global singleton data stored in the `World`
+ .insert_resource(Fibonacci { a: 1, b: 1 })
+ // Systems run every pass of the game loop and perform logic
+ .add_system(fibonacci_sum.system())
+ .add_system(report_fibonacci.system())
+ .run();
+}
+
+// A simple data structure to store the two current fibonacci numbers
+struct Fibonacci {
+ a: u64,
+ b: u64,
+}
+
+// This system requires mutable access to our Fibonacci resource,
+// so we add `ResMut` to its function parameters
+fn fibonacci_sum(mut fibonacci: ResMut<Fibonacci>) {
+ // This crashes fairly quickly, as we overflow our u64 data storage
+ let new_sum = fibonacci.a + fibonacci.b;
+ fibonacci.a = fibonacci.b;
+ fibonacci.b = new_sum;
+}
+
+// This system only reads the value of our Fibonacci resource,
+// so we only need `Res`
+fn report_fibonacci(fibonacci: Res<Fibonacci>) {
+ info!(fibonacci.a, fibonacci.b);
+}
+```

content/learn/book/welcome/installation/_index.md

@@ -1,6 +1,6 @@
 +++
-title = "Installing Rust and Bevy"
-weight = 2
+title = "Setup"
+weight = 1
 template = "book-section.html"
 page_template = "book-section.html"
 +++
@@ -15,7 +15,7 @@ All Bevy app and engine code is written in Rust. This means that before we begin
 
 Install Rust by following the [Rust Getting Started Guide](https://www.rust-lang.org/learn/get-started).
 
-Once this is done, you should have the ```rustc``` compiler and the ```cargo``` build system installed in your path.
+Once this is done, you should have the `rustc` compiler and the `cargo` build system installed in your path.
 
 ### Install OS dependencies
 
@@ -95,6 +95,21 @@ Now run `cargo run` again. The Bevy dependencies should start building. This wil
 
 Now that we have our Bevy project set up, we're ready to start making our first Bevy app!
 
+### Checking that it works
+
+Within `main.rs`, let's create our first app and check that all the dependencies are working correctly!
+
+```rust
+use bevy::prelude::*;
+
+fn main(){
+ App::build().add_plugins(DefaultPlugins).run();
+}
+```
+
+Use `cargo run` to test it out.
+This will just show an empty window, and includes all of the standard functionality needed to make Bevy games.
+
 ## Troubleshooting
 
 Having trouble getting Bevy running?

content/learn/book/welcome/plugins/_index.md

@@ -1,16 +1,104 @@
 +++
-title = "Modularity through plugins"
-weight = 4
+title = "Plugins"
+weight = 3
 template = "book-section.html"
 page_template = "book-section.html"
 +++
 
-TODO: Explain how plugins work
+One of Bevy's core principles is modularity. In Bevy, all functionality is implemented via {{rust_type(type="trait" crate="bevy_app" name="Plugin" plural=true)}}, which are added to an {{rust_type(type="struct" crate="bevy" mod = "app" name="App" no_mod = "true")}}. Game logic like player movement, core engine logic like rendering and sound, and third party extensions like tile maps are all implemented the same way using {{rust_type(type="trait" crate="bevy_app" name="Plugin" plural=true)}}.
 
-## `MinimalPlugins`
-
-## `DefaultPlugins`
+This empowers Bevy developers to modularly "build their own engine" using official, third party, and custom {{rust_type(type="trait" crate="bevy_app" name="Plugin" plural=true)}}. Bevy intentionally blurs the lines between engine developers and app developers.
 
 ## Writing your own plugins
 
+Plugins are collections of code that modify {{rust_type(type="struct" crate="bevy" mod = "app" name="App" no_mod = "true")}}.
+Any code in a plugin could be directly substituted directly on the base {{rust_type(type="struct" crate="bevy" mod = "app" name="App" no_mod = "true")}}.
+There's no magic to be found here; they're just a straightforward tool for code organization.
+
+Plugins are types that implement the {{rust_type(type="trait" crate="bevy_app" name="Plugin")}} trait:
+
+```rust
+use bevy::prelude::*;
+
+fn main(){
+ App::build()
+ // Adds the "default" Bevy Engine plugins.
+ // We'll cover this in the next section.
+ .add_plugins(DefaultPlugins)
+ // Adds our new `Plugin` to the `App`
+ .add_plugin(ScorePlugin)
+ .run();
+}
+
+struct ScorePlugin;
+
+impl Plugin for ScorePlugin {
+ fn build(&self, app: &mut App) {
+ app
+ // The Score struct is added as a resource (global singleton) to the world, 
+ // beginning at the default value of 0
+ .init_resource::<Score>()
+ // Increments the score by 1 every pass of the game loop
+ .add_system(increment_score.system())
+ // Prints the current value of the score
+ .add_system(report_score.system());
+ }
+}
+
+#[derive(Default, Debug)]
+struct Score(u8);
+
+fn increment_score(score: ResMut<Score>){
+ score.0 += 1;
+}
+
+fn report_score(score: Res<Score>){
+ info!(score);
+}
+```
+
+## Plugin groups
+
+Bevy's {{rust_type(type="struct" crate="bevy" name="DefaultPlugins")}} is a {{rust_type(type="trait" crate="bevy_app" name="PluginGroup")}} that adds the "core engine features" like rendering, windowing, and sound that most developers want when building an app.
+
+You can add {{rust_type(type="struct" crate="bevy" name="DefaultPlugins")}} to your app like this:
+
+```rust
+App::new().add_plugins(DefaultPlugins)
+```
+
+Take a look at the [source](https://github.com/bevyengine/bevy/blob/latest/crates/bevy_internal/src/default_plugins.rs) to see a full list of what's included.
+
+If you're looking to structure your Bevy app in an unusual way and don't want to use most of the functionality provided by the engine, you can choose to use Bevy's {{rust_type(type="struct" crate="bevy" name="MinimalPlugins")}} instead.
+
+We can click through to the [source]((https://github.com/bevyengine/bevy/blob/latest/crates/bevy_internal/src/default_plugins.rs)) for the `impl PluginGroup for MinimalPlugins` to see that this adds {{rust_type(type="struct" crate="bevy_core" name="CorePlugin")}} and {{rust_type(type="struct" crate="bevy_app" name="ScheduleRunnerPlugin")}}.
+
+The {{rust_type(type="struct" crate="bevy_core" name="CorePlugin")}} handles low-level fundamentals such as updating app time, while the {{rust_type(type="struct" crate="bevy_app" name="ScheduleRunnerPlugin")}} sets up the main game loop to run repeatedly over time.
+This functionality is essential: starting with these plugins is virtually always going to be a safe bet.
+
 ## Third-party plugins
+
+Importing 3rd-party plugins is easy; they're just ordinary Rust code that can be managed with `cargo`.
+Bevy's modular nature tends to result in simple plug-and-play interoperability and easy extensibility, so don't be afraid to try out plugins that seem interesting or useful for your game.
+
+1. Find a Bevy plugin (such as from our [collection of assets](https://bevyengine.org/assets/)).
+2. Add it to your `Cargo.toml` as a crate under `[dependencies]`.
+3. Import the code definitions from the crate (i.e. `using bevy_third_party::prelude::*`) to add the appropriate items to your workspace.
+4. Add the plugin to your app (i.e. `app.add_plugin(bevy_third_party_plugin)`)!
+
+Follow the documentation and examples from the crates you're importing to make sure you have everything configured properly.
+
+If you plan on releasing a plugin yourself, please refer to [Bevy's Plugin Guidelines](https://github.com/bevyengine/bevy/blob/main/docs/plugins_guidelines.md), [release a crate](https://doc.rust-lang.org/cargo/reference/publishing.html), and then [add it to Bevy Assets](https://github.com/bevyengine/bevy-assets/) to share it with the community!
+
+## Pick-and-choose features
+
+Some apps won't need all of the features provided by {{rust_type(type="struct" crate="bevy" name="DefaultPlugins")}}. Other features must be opted into. We can use [cargo features](https://doc.rust-lang.org/cargo/reference/features.html) to enable and disable what features are compiled into our game.
+
+In your `Cargo.toml` file, you can disable default features and opt-in to the [features you want](https://github.com/bevyengine/bevy/blob/main/docs/cargo_features.md):
+
+```toml
+[dependencies]
+bevy = { version = "0.5", default-features = false, features = ["feature_name"] }
+```
+
+As shown in the [plugin_group.rs](https://github.com/bevyengine/bevy/blob/latest/examples/app/plugin_group.rs) example, you can also configure plugin groups from within Bevy itself.