From f734bc53657abd5050a3cc18334c2b9b50d856bd Mon Sep 17 00:00:00 2001 From: Alice Date: Sun, 13 Jun 2021 20:51:42 -0400 Subject: [PATCH 01/44] Welcome blurb --- content/learn/book/welcome/_index.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/content/learn/book/welcome/_index.md b/content/learn/book/welcome/_index.md index 33726b27b9..186095a3ae 100644 --- a/content/learn/book/welcome/_index.md +++ b/content/learn/book/welcome/_index.md @@ -6,4 +6,13 @@ template = "book-section.html" page_template = "book-section.html" +++ -TODO: Briefly discuss what Bevy is. +Welcome to the Bevy game engine! While Bevy is still very early in development, it's already: + +- Rust-first: with all the safety, tooling and power that comes with a modern systems language +- completely free, open source and hackable with an architecture designed for modularity +- powered by an ergonomic and innovative ECS that makes writing gameplay and engine logic a joy +- support all major desktop platforms with a single code-base, with limited mobile and web support +- high-performance enough that it won't get in your way + +This book is designed to provide a more thoughtful, explanation-first to the engine's essential features. +If you just want to try it out hands-on, jump into one of our quick-start guides instead! From 528a91fde3c84f1add8b88d7fa50f1060feeed26 Mon Sep 17 00:00:00 2001 From: Alice Date: Sun, 13 Jun 2021 21:08:43 -0400 Subject: [PATCH 02/44] Community blurb --- content/learn/book/welcome/community/_index.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/content/learn/book/welcome/community/_index.md b/content/learn/book/welcome/community/_index.md index ce256cf037..fd85643a59 100644 --- a/content/learn/book/welcome/community/_index.md +++ b/content/learn/book/welcome/community/_index.md @@ -5,9 +5,15 @@ template = "book-section.html" page_template = "book-section.html" +++ -TODO: List places where the community congregates, and differentiate +The Bevy community can be great for finding support, discovering resources and sharing the cool stuff you're making! +Here's where you should look: -TODO: link to awesome-bevy and discuss crate ecosystem +1. [GitHub]: The official space for development activity. Check out the [CONTRIBUTING.md] if you'd like to help out! + 1. [Issues]: Add suggestions and report bugs. + 2. [Discussions]: Ask open-ended questions and get help with code review. + 3. [Pull requests]: Submit new features and fixes. +2. [Discord]: A thriving social community; handy if you want to quickly bounce ideas off of people +3. [Reddit]: Great for sharing links and resources. +4. [Stack Overflow]: For detailed, concrete questions that will help future users in the future. +5. [Awesome-Bevy]: Tutorials, plugins, community crates and assets for using Bevy. -TODO: link to CONTRIBUTING.md and talk about how Bevy is maintained by Cart plus a broad community of volunteers. -Link to Cart's donation page From b35d0b8465a2233a8e8fccab9789cb346b4bad0a Mon Sep 17 00:00:00 2001 From: Alice Date: Sun, 13 Jun 2021 21:29:18 -0400 Subject: [PATCH 03/44] Why not Bevy --- content/learn/book/welcome/_index.md | 25 +++++++++++++++++++ content/learn/book/welcome/why-bevy/_index.md | 12 --------- 2 files changed, 25 insertions(+), 12 deletions(-) delete mode 100644 content/learn/book/welcome/why-bevy/_index.md diff --git a/content/learn/book/welcome/_index.md b/content/learn/book/welcome/_index.md index 186095a3ae..ea60b6932a 100644 --- a/content/learn/book/welcome/_index.md +++ b/content/learn/book/welcome/_index.md @@ -16,3 +16,28 @@ Welcome to the Bevy game engine! While Bevy is still very early in development, This book is designed to provide a more thoughtful, explanation-first to the engine's essential features. If you just want to try it out hands-on, jump into one of our quick-start guides instead! + +## Why not Bevy? + +Of course, Bevy is *extremely* immature, and there are very good reasons not to choose it for your next project. +It is currently completely missing first-party solutions for: + +- animation +- networking +- console support +- physics + +The following areas are very immature: + +- audio +- user interface +- web support +- mobile support + +While Bevy's modular architecture makes it relatively easy to integrate your own (or third-party) solutions, be mindful that it won't Just Work out of the box. +Contributions are extremely welcome, but if you want something fully featured for a game *today*, Bevy is not the right engine for you yet. + +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. + +While we'll do our best to provide [migration guides, updating versions of Bevy is largely an exercise in letting the excellent Rust tooling guide you and chasing the errors until everything compiles again. \ No newline at end of file diff --git a/content/learn/book/welcome/why-bevy/_index.md b/content/learn/book/welcome/why-bevy/_index.md deleted file mode 100644 index 5134f6ac56..0000000000 --- a/content/learn/book/welcome/why-bevy/_index.md +++ /dev/null @@ -1,12 +0,0 @@ -+++ -title = "Why Bevy?" -weight = 1 -template = "book-section.html" -page_template = "book-section.html" -+++ - -TODO: discuss the cool features and design philosophy - -## Why not Bevy? - -TODO: discuss current limitations From 8e7794cec300a20e436c63f9c24dfd9a99a1c0de Mon Sep 17 00:00:00 2001 From: Alice Date: Mon, 14 Jun 2021 17:15:02 -0400 Subject: [PATCH 04/44] Hello World --- .../learn/book/welcome/community/_index.md | 3 +- .../learn/book/welcome/hello-world/_index.md | 12 ------ .../learn/book/welcome/installation/_index.md | 37 ++++++++++++++++++- content/learn/book/welcome/plugins/_index.md | 2 +- 4 files changed, 38 insertions(+), 16 deletions(-) delete mode 100644 content/learn/book/welcome/hello-world/_index.md diff --git a/content/learn/book/welcome/community/_index.md b/content/learn/book/welcome/community/_index.md index fd85643a59..5b7b7375fd 100644 --- a/content/learn/book/welcome/community/_index.md +++ b/content/learn/book/welcome/community/_index.md @@ -1,6 +1,6 @@ +++ title = "The Bevy community" -weight = 5 +weight = 4 template = "book-section.html" page_template = "book-section.html" +++ @@ -16,4 +16,3 @@ Here's where you should look: 3. [Reddit]: Great for sharing links and resources. 4. [Stack Overflow]: For detailed, concrete questions that will help future users in the future. 5. [Awesome-Bevy]: Tutorials, plugins, community crates and assets for using Bevy. - diff --git a/content/learn/book/welcome/hello-world/_index.md b/content/learn/book/welcome/hello-world/_index.md deleted file mode 100644 index f96b20ee3a..0000000000 --- a/content/learn/book/welcome/hello-world/_index.md +++ /dev/null @@ -1,12 +0,0 @@ -+++ -title = "Hello World" -weight = 3 -template = "book-section.html" -page_template = "book-section.html" -+++ - -TODO: explain basic model of how Bevy apps are structured - -TODO: demonstrate `App::new().build().run()` - -TODO: make one system that says "Hello, World!" diff --git a/content/learn/book/welcome/installation/_index.md b/content/learn/book/welcome/installation/_index.md index e34b5a04ee..3c72a337b8 100644 --- a/content/learn/book/welcome/installation/_index.md +++ b/content/learn/book/welcome/installation/_index.md @@ -1,6 +1,6 @@ +++ title = "Installing Rust and Bevy" -weight = 2 +weight = 1 template = "book-section.html" page_template = "book-section.html" +++ @@ -95,6 +95,41 @@ 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! +### Hello Bevy World + +Within `main.rs`, let's create our first app! + +```rust +use bevy::prelude::*; + +fn main(){ + App::new().build().run(); +} +``` + +This won't report anything interesting: it merely creates an empty app with an empty **world**. + +Let's add our first system by modifying the file to the following: + +```rust +use bevy::prelude::*; + +fn main(){ + App::new() + .build() + .add_system(hello.system()) + .run(); +} + +fn hello(){ + println!("Hello, Bevy!") +} +``` + +Systems in Bevy are just ordinary Rust functions, which are registered in our app to operate on our world. + +Calling `cargo run` will run our schedule once, causing `hello` to print "Hello, Bevy!", allowing us to verify our installation of Bevy. + ## Troubleshooting Having trouble getting Bevy running? diff --git a/content/learn/book/welcome/plugins/_index.md b/content/learn/book/welcome/plugins/_index.md index b0e526ae07..cd67efe229 100644 --- a/content/learn/book/welcome/plugins/_index.md +++ b/content/learn/book/welcome/plugins/_index.md @@ -1,6 +1,6 @@ +++ title = "Modularity through plugins" -weight = 4 +weight = 3 template = "book-section.html" page_template = "book-section.html" +++ From b0a7a0bb21009ea7c9d6b6b156c0d636b34ee08d Mon Sep 17 00:00:00 2001 From: Alice Date: Mon, 14 Jun 2021 17:55:55 -0400 Subject: [PATCH 05/44] Quick draft on plugins --- .../learn/book/welcome/community/_index.md | 2 +- content/learn/book/welcome/plugins/_index.md | 128 +++++++++++++++++- 2 files changed, 127 insertions(+), 3 deletions(-) diff --git a/content/learn/book/welcome/community/_index.md b/content/learn/book/welcome/community/_index.md index 5b7b7375fd..967448713f 100644 --- a/content/learn/book/welcome/community/_index.md +++ b/content/learn/book/welcome/community/_index.md @@ -1,6 +1,6 @@ +++ title = "The Bevy community" -weight = 4 +weight = 3 template = "book-section.html" page_template = "book-section.html" +++ diff --git a/content/learn/book/welcome/plugins/_index.md b/content/learn/book/welcome/plugins/_index.md index cd67efe229..c52531fb21 100644 --- a/content/learn/book/welcome/plugins/_index.md +++ b/content/learn/book/welcome/plugins/_index.md @@ -1,16 +1,140 @@ +++ title = "Modularity through plugins" -weight = 3 +weight = 2 template = "book-section.html" page_template = "book-section.html" +++ -TODO: Explain how plugins work +In Bevy, virtually all of the functionality you might want is added via *plugins*, which are added to your app. +These might provide basic windowing functionality, handle input or sound, calculate physics or provide game-specific logic like a tile map system. + +By combining Bevy's first-party plugins with third-party alternatives, you can modularly customize the behaviour of the Bevy game engine, and then add your own plugins to contain your own game-specific code in a well-organized way. ## `MinimalPlugins` +Unless you're doing something very unusual, you will *always* want to include the plugins provided by Bevy's [`MinimalPlugins`](https://docs.rs/bevy/latest/bevy/struct.MinimalPlugins.html). We can click through to the source for the `impl PluginGroup for MinimalPlugins` to see what this adds: + +```rust +use bevy_app::{PluginGroup, PluginGroupBuilder}; + +pub struct MinimalPlugins; + +impl PluginGroup for MinimalPlugins { + fn build(&mut self, group: &mut PluginGroupBuilder) { + group.add(bevy_core::CorePlugin::default()); + group.add(bevy_app::ScheduleRunnerPlugin::default()); + } +} +``` + +TODO: explain what these do. + +The `CorePlugin` controls ??, while the `ScheduleRunnerPlugin` ???. + ## `DefaultPlugins` +Bevy's `DefaultPlugins` are intended to get up and running with a "standard game" as quickly as possible. Let's take a look at the source again: + +```rust +pub struct DefaultPlugins; + +impl PluginGroup for DefaultPlugins { + fn build(&mut self, group: &mut PluginGroupBuilder) { + group.add(bevy_log::LogPlugin::default()); + group.add(bevy_core::CorePlugin::default()); + group.add(bevy_transform::TransformPlugin::default()); + group.add(bevy_diagnostic::DiagnosticsPlugin::default()); + group.add(bevy_input::InputPlugin::default()); + group.add(bevy_window::WindowPlugin::default()); + group.add(bevy_asset::AssetPlugin::default()); + group.add(bevy_scene::ScenePlugin::default()); + + #[cfg(feature = "bevy_render")] + group.add(bevy_render::RenderPlugin::default()); + + #[cfg(feature = "bevy_sprite")] + group.add(bevy_sprite::SpritePlugin::default()); + + #[cfg(feature = "bevy_pbr")] + group.add(bevy_pbr::PbrPlugin::default()); + + #[cfg(feature = "bevy_ui")] + group.add(bevy_ui::UiPlugin::default()); + + #[cfg(feature = "bevy_text")] + group.add(bevy_text::TextPlugin::default()); + + #[cfg(feature = "bevy_audio")] + group.add(bevy_audio::AudioPlugin::default()); + + #[cfg(feature = "bevy_gilrs")] + group.add(bevy_gilrs::GilrsPlugin::default()); + + #[cfg(feature = "bevy_gltf")] + group.add(bevy_gltf::GltfPlugin::default()); + + #[cfg(feature = "bevy_winit")] + group.add(bevy_winit::WinitPlugin::default()); + + #[cfg(feature = "bevy_wgpu")] + group.add(bevy_wgpu::WgpuPlugin::default()); + } +} +``` + +As you can see, there are some added niceties (logging and diagnostics, scenes, input and windowing) as well as a number of plugins controlled by feature flags. +These are heavier dependencies that you may want to disable for some games (or platforms), and replace with your own alternatives. +To do so: + +TODO: explain how to disable plugins. + ## Writing your own plugins +Plugins are simply collections of code that modify the `AppBuilder`. + +You can write your own to organize your own code by implementing the `Plugin` trait on a struct of your own creation. + +```rust +use bevy::prelude::*; + +fn main(){ + App::build() + .add_plugins(DefaultPlugins) + // Plugins merely organize code: this could just be replaced directly with + // the add_system and init_resource calls from below + .add_plugin(ScorePlugin) + .run(); +} + +struct ScorePlugin; + +impl Plugin for ScorePlugin { + fn build(&self, app: &mut AppBuilder) { + app + // The Score struct is addded as a resource (global singleton) to the world, + // beginning at the default value of 0 + .init_resource::() + // 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.0 += 1; +} + +fn report_score(score: Res){ + dbg!(score); +} +``` + ## Third-party plugins + +Importing 3rd-party plugins is easy; they're just Rust code! + +TODO: show how to import another plugin. \ No newline at end of file From d82ee9b19680cba8dbb19c1f23abea7179f91235 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Mon, 14 Jun 2021 18:31:09 -0400 Subject: [PATCH 06/44] Explain MinimalPlugins --- content/learn/book/welcome/plugins/_index.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/content/learn/book/welcome/plugins/_index.md b/content/learn/book/welcome/plugins/_index.md index c52531fb21..b0f7ea92e9 100644 --- a/content/learn/book/welcome/plugins/_index.md +++ b/content/learn/book/welcome/plugins/_index.md @@ -27,9 +27,7 @@ impl PluginGroup for MinimalPlugins { } ``` -TODO: explain what these do. - -The `CorePlugin` controls ??, while the `ScheduleRunnerPlugin` ???. +The `CorePlugin` handles low-level fundamentals such as updating app time, while the `ScheduleRunnerPlugin` sets up the main game loop to run repeatedly over time. ## `DefaultPlugins` From 989627847714d667702db915b88efa795170f433 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Mon, 14 Jun 2021 18:47:33 -0400 Subject: [PATCH 07/44] Disabling plugins --- content/learn/book/welcome/plugins/_index.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/content/learn/book/welcome/plugins/_index.md b/content/learn/book/welcome/plugins/_index.md index b0f7ea92e9..3beb0f1b55 100644 --- a/content/learn/book/welcome/plugins/_index.md +++ b/content/learn/book/welcome/plugins/_index.md @@ -82,9 +82,16 @@ impl PluginGroup for DefaultPlugins { As you can see, there are some added niceties (logging and diagnostics, scenes, input and windowing) as well as a number of plugins controlled by feature flags. These are heavier dependencies that you may want to disable for some games (or platforms), and replace with your own alternatives. -To do so: +To do so, we can use [cargo features](https://doc.rust-lang.org/cargo/reference/features.html) to disable them in our game. -TODO: explain how to disable plugins. +In your `Cargo.toml` file, 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 = {"0.5", , default-features = false, features = ["..."]} +``` + +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. ## Writing your own plugins From 1c28e5616a540b76434aecab6a211aaedf4f9cb6 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Mon, 14 Jun 2021 18:52:47 -0400 Subject: [PATCH 08/44] Third-party plugins --- content/learn/book/welcome/plugins/_index.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/content/learn/book/welcome/plugins/_index.md b/content/learn/book/welcome/plugins/_index.md index 3beb0f1b55..27d71fad6d 100644 --- a/content/learn/book/welcome/plugins/_index.md +++ b/content/learn/book/welcome/plugins/_index.md @@ -142,4 +142,9 @@ fn report_score(score: Res){ Importing 3rd-party plugins is easy; they're just Rust code! -TODO: show how to import another plugin. \ No newline at end of file +1. Find a Bevy (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. +4. Add the plugin to your app! + +Follow the documentation and examples from the crates you're importing to make sure you have everything configured properly. From 62b998a113d9f74fa22a3b7a49904e80c58fa31f Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Wed, 16 Jun 2021 04:13:14 -0400 Subject: [PATCH 09/44] Removed Community page Redundant to https://bevyengine.org/community/ --- content/learn/book/welcome/community/_index.md | 18 ------------------ 1 file changed, 18 deletions(-) delete mode 100644 content/learn/book/welcome/community/_index.md diff --git a/content/learn/book/welcome/community/_index.md b/content/learn/book/welcome/community/_index.md deleted file mode 100644 index 967448713f..0000000000 --- a/content/learn/book/welcome/community/_index.md +++ /dev/null @@ -1,18 +0,0 @@ -+++ -title = "The Bevy community" -weight = 3 -template = "book-section.html" -page_template = "book-section.html" -+++ - -The Bevy community can be great for finding support, discovering resources and sharing the cool stuff you're making! -Here's where you should look: - -1. [GitHub]: The official space for development activity. Check out the [CONTRIBUTING.md] if you'd like to help out! - 1. [Issues]: Add suggestions and report bugs. - 2. [Discussions]: Ask open-ended questions and get help with code review. - 3. [Pull requests]: Submit new features and fixes. -2. [Discord]: A thriving social community; handy if you want to quickly bounce ideas off of people -3. [Reddit]: Great for sharing links and resources. -4. [Stack Overflow]: For detailed, concrete questions that will help future users in the future. -5. [Awesome-Bevy]: Tutorials, plugins, community crates and assets for using Bevy. From 07f45289f22f0758be5b3d5b8f4d20c5bf462bee Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Wed, 16 Jun 2021 04:26:38 -0400 Subject: [PATCH 10/44] Content polish --- content/learn/book/welcome/_index.md | 30 ++++++++++++-------- content/learn/book/welcome/plugins/_index.md | 2 +- 2 files changed, 19 insertions(+), 13 deletions(-) diff --git a/content/learn/book/welcome/_index.md b/content/learn/book/welcome/_index.md index ea60b6932a..1d422d13b4 100644 --- a/content/learn/book/welcome/_index.md +++ b/content/learn/book/welcome/_index.md @@ -6,38 +6,44 @@ template = "book-section.html" page_template = "book-section.html" +++ -Welcome to the Bevy game engine! While Bevy is still very early in development, it's already: +Welcome to the Bevy game engine! A bevy may be a group of birds, but our engine is: - Rust-first: with all the safety, tooling and power that comes with a modern systems language - completely free, open source and hackable with an architecture designed for modularity -- powered by an ergonomic and innovative ECS that makes writing gameplay and engine logic a joy -- support all major desktop platforms with a single code-base, with limited mobile and web support -- high-performance enough that it won't get in your way +- powered by an ergonomic and innovative ECS that makes writing clear, performant gameplay and engine logic a joy +- cross-platform: support all major desktop platforms with a single code-base, with limited mobile and web support +- designed for effortless parallelism with a data-oriented design and automatic parallel scheduler +- built on a high-performance foundation This book is designed to provide a more thoughtful, explanation-first to the engine's essential features. -If you just want to try it out hands-on, jump into one of our quick-start guides instead! +If you just want to try it out hands-on, jump into one of our [quick-start guides](TODO: add link) instead! -## Why not Bevy? +## Stability warning -Of course, Bevy is *extremely* immature, and there are very good reasons not to choose it for your next project. +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. It is currently completely missing first-party solutions for: - animation - networking - console support -- physics -The following areas are very immature: +Solid third-party (but not first-party) solutions currently exist for: + +- [audio](https://crates.io/crates/bevy_kira_audio) +- [physics](https://github.com/dimforge/bevy_rapier) + +The following areas are being explored by the engine itself, but are very immature: -- audio - user interface - web support - mobile support -While Bevy's modular architecture makes it relatively easy to integrate your own (or third-party) solutions, be mindful that it won't Just Work out of the box. +While Bevy's modular architecture makes it relatively easy to integrate your own (or third-party) solutions, be mindful that Bevy does not Just Work out of the box yet. Contributions are extremely welcome, but if you want something fully featured for a game *today*, Bevy is not the right engine for you yet. +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. -While we'll do our best to provide [migration guides, updating versions of Bevy is largely an exercise in letting the excellent Rust tooling guide you and chasing the errors until everything compiles again. \ No newline at end of file +While we'll do our best to provide [migration guides, updating versions of Bevy is largely an exercise in letting the excellent Rust tooling guide you and chasing the errors until everything compiles again. diff --git a/content/learn/book/welcome/plugins/_index.md b/content/learn/book/welcome/plugins/_index.md index 27d71fad6d..a510887fa8 100644 --- a/content/learn/book/welcome/plugins/_index.md +++ b/content/learn/book/welcome/plugins/_index.md @@ -5,7 +5,7 @@ template = "book-section.html" page_template = "book-section.html" +++ -In Bevy, virtually all of the functionality you might want is added via *plugins*, which are added to your app. +In Bevy, virtually all of the functionality you might want is added via **plugins**, which are added to your app. These might provide basic windowing functionality, handle input or sound, calculate physics or provide game-specific logic like a tile map system. By combining Bevy's first-party plugins with third-party alternatives, you can modularly customize the behaviour of the Bevy game engine, and then add your own plugins to contain your own game-specific code in a well-organized way. From 50dbe1c14017040d24abd796625e407361d92717 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Wed, 16 Jun 2021 04:29:35 -0400 Subject: [PATCH 11/44] Link to documentation strategies --- content/learn/book/welcome/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/learn/book/welcome/_index.md b/content/learn/book/welcome/_index.md index 1d422d13b4..87143eb153 100644 --- a/content/learn/book/welcome/_index.md +++ b/content/learn/book/welcome/_index.md @@ -15,7 +15,7 @@ Welcome to the Bevy game engine! A bevy may be a group of birds, but our engine - designed for effortless parallelism with a data-oriented design and automatic parallel scheduler - built on a high-performance foundation -This book is designed to provide a more thoughtful, explanation-first to the engine's essential features. +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! ## Stability warning From bef720e51c7fda11075a39260d34f58e324efaa5 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Wed, 16 Jun 2021 16:43:45 -0400 Subject: [PATCH 12/44] Typo Co-authored-by: Federico Rinaldi --- content/learn/book/welcome/plugins/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/learn/book/welcome/plugins/_index.md b/content/learn/book/welcome/plugins/_index.md index a510887fa8..d71514add8 100644 --- a/content/learn/book/welcome/plugins/_index.md +++ b/content/learn/book/welcome/plugins/_index.md @@ -142,7 +142,7 @@ fn report_score(score: Res){ Importing 3rd-party plugins is easy; they're just Rust code! -1. Find a Bevy (such as from our [collection of assets](https://bevyengine.org/assets/)). +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. 4. Add the plugin to your app! From a4ef5f86ea0f75da4aa25a46ed2dcd3daf2b794f Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Wed, 16 Jun 2021 16:44:02 -0400 Subject: [PATCH 13/44] Typo fix Co-authored-by: Federico Rinaldi --- content/learn/book/welcome/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/learn/book/welcome/_index.md b/content/learn/book/welcome/_index.md index 87143eb153..a29dc2d3c9 100644 --- a/content/learn/book/welcome/_index.md +++ b/content/learn/book/welcome/_index.md @@ -46,4 +46,4 @@ 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. -While we'll do our best to provide [migration guides, updating versions of Bevy is largely an exercise in letting the excellent Rust tooling guide you and chasing the errors until everything compiles again. +While we'll do our best to provide migration guides, updating versions of Bevy is largely an exercise in letting the excellent Rust tooling guide you and chasing the errors until everything compiles again. From a0b0363219779b67b89ca7f964d2e743f2a34e7a Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Fri, 18 Jun 2021 20:54:54 -0400 Subject: [PATCH 14/44] Use link over embedding default plugins code --- content/learn/book/welcome/plugins/_index.md | 49 +------------------- 1 file changed, 1 insertion(+), 48 deletions(-) diff --git a/content/learn/book/welcome/plugins/_index.md b/content/learn/book/welcome/plugins/_index.md index d71514add8..1732aa8f93 100644 --- a/content/learn/book/welcome/plugins/_index.md +++ b/content/learn/book/welcome/plugins/_index.md @@ -31,54 +31,7 @@ The `CorePlugin` handles low-level fundamentals such as updating app time, while ## `DefaultPlugins` -Bevy's `DefaultPlugins` are intended to get up and running with a "standard game" as quickly as possible. Let's take a look at the source again: - -```rust -pub struct DefaultPlugins; - -impl PluginGroup for DefaultPlugins { - fn build(&mut self, group: &mut PluginGroupBuilder) { - group.add(bevy_log::LogPlugin::default()); - group.add(bevy_core::CorePlugin::default()); - group.add(bevy_transform::TransformPlugin::default()); - group.add(bevy_diagnostic::DiagnosticsPlugin::default()); - group.add(bevy_input::InputPlugin::default()); - group.add(bevy_window::WindowPlugin::default()); - group.add(bevy_asset::AssetPlugin::default()); - group.add(bevy_scene::ScenePlugin::default()); - - #[cfg(feature = "bevy_render")] - group.add(bevy_render::RenderPlugin::default()); - - #[cfg(feature = "bevy_sprite")] - group.add(bevy_sprite::SpritePlugin::default()); - - #[cfg(feature = "bevy_pbr")] - group.add(bevy_pbr::PbrPlugin::default()); - - #[cfg(feature = "bevy_ui")] - group.add(bevy_ui::UiPlugin::default()); - - #[cfg(feature = "bevy_text")] - group.add(bevy_text::TextPlugin::default()); - - #[cfg(feature = "bevy_audio")] - group.add(bevy_audio::AudioPlugin::default()); - - #[cfg(feature = "bevy_gilrs")] - group.add(bevy_gilrs::GilrsPlugin::default()); - - #[cfg(feature = "bevy_gltf")] - group.add(bevy_gltf::GltfPlugin::default()); - - #[cfg(feature = "bevy_winit")] - group.add(bevy_winit::WinitPlugin::default()); - - #[cfg(feature = "bevy_wgpu")] - group.add(bevy_wgpu::WgpuPlugin::default()); - } -} -``` +Bevy's `DefaultPlugins` are intended to get up and running with a "standard game" as quickly as possible. Let's take a look at the [source](https://github.com/bevyengine/bevy/blob/latest/crates/bevy_internal/src/default_plugins.rs) again. As you can see, there are some added niceties (logging and diagnostics, scenes, input and windowing) as well as a number of plugins controlled by feature flags. These are heavier dependencies that you may want to disable for some games (or platforms), and replace with your own alternatives. From ab2410c53ecc9cba294f529fa6ed9bb02362d83e Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Fri, 18 Jun 2021 20:59:26 -0400 Subject: [PATCH 15/44] Better explained how plugins work --- content/learn/book/welcome/plugins/_index.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/content/learn/book/welcome/plugins/_index.md b/content/learn/book/welcome/plugins/_index.md index 1732aa8f93..1b353ac3d0 100644 --- a/content/learn/book/welcome/plugins/_index.md +++ b/content/learn/book/welcome/plugins/_index.md @@ -48,7 +48,9 @@ As shown in the [plugin_group.rs](https://github.com/bevyengine/bevy/blob/latest ## Writing your own plugins -Plugins are simply collections of code that modify the `AppBuilder`. +Plugins are collections of code that modify the `AppBuilder` (which controls all of the data and logic of our game) using the builder pattern. +Any code in a plugin could be directly substituted directly on the base `AppBuilder`. +There's no magic to be found here; they're just a straightforward tool for code organization. You can write your own to organize your own code by implementing the `Plugin` trait on a struct of your own creation. @@ -59,7 +61,7 @@ fn main(){ App::build() .add_plugins(DefaultPlugins) // Plugins merely organize code: this could just be replaced directly with - // the add_system and init_resource calls from below + // the init_resource and add_system calls from below .add_plugin(ScorePlugin) .run(); } From b6b0de48a40db79155c744d7d6324d53b667e43b Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Fri, 18 Jun 2021 21:00:35 -0400 Subject: [PATCH 16/44] Concrete example of a plugin before jumping to DefaultPlugins --- content/learn/book/welcome/plugins/_index.md | 73 ++++++++++---------- 1 file changed, 37 insertions(+), 36 deletions(-) diff --git a/content/learn/book/welcome/plugins/_index.md b/content/learn/book/welcome/plugins/_index.md index 1b353ac3d0..515fbbf314 100644 --- a/content/learn/book/welcome/plugins/_index.md +++ b/content/learn/book/welcome/plugins/_index.md @@ -10,42 +10,6 @@ These might provide basic windowing functionality, handle input or sound, calcul By combining Bevy's first-party plugins with third-party alternatives, you can modularly customize the behaviour of the Bevy game engine, and then add your own plugins to contain your own game-specific code in a well-organized way. -## `MinimalPlugins` - -Unless you're doing something very unusual, you will *always* want to include the plugins provided by Bevy's [`MinimalPlugins`](https://docs.rs/bevy/latest/bevy/struct.MinimalPlugins.html). We can click through to the source for the `impl PluginGroup for MinimalPlugins` to see what this adds: - -```rust -use bevy_app::{PluginGroup, PluginGroupBuilder}; - -pub struct MinimalPlugins; - -impl PluginGroup for MinimalPlugins { - fn build(&mut self, group: &mut PluginGroupBuilder) { - group.add(bevy_core::CorePlugin::default()); - group.add(bevy_app::ScheduleRunnerPlugin::default()); - } -} -``` - -The `CorePlugin` handles low-level fundamentals such as updating app time, while the `ScheduleRunnerPlugin` sets up the main game loop to run repeatedly over time. - -## `DefaultPlugins` - -Bevy's `DefaultPlugins` are intended to get up and running with a "standard game" as quickly as possible. Let's take a look at the [source](https://github.com/bevyengine/bevy/blob/latest/crates/bevy_internal/src/default_plugins.rs) again. - -As you can see, there are some added niceties (logging and diagnostics, scenes, input and windowing) as well as a number of plugins controlled by feature flags. -These are heavier dependencies that you may want to disable for some games (or platforms), and replace with your own alternatives. -To do so, we can use [cargo features](https://doc.rust-lang.org/cargo/reference/features.html) to disable them in our game. - -In your `Cargo.toml` file, 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 = {"0.5", , default-features = false, features = ["..."]} -``` - -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. - ## Writing your own plugins Plugins are collections of code that modify the `AppBuilder` (which controls all of the data and logic of our game) using the builder pattern. @@ -59,6 +23,7 @@ use bevy::prelude::*; fn main(){ App::build() + // As discussed below, DefaultPlugins provide the standard scaffolding for Bevy games .add_plugins(DefaultPlugins) // Plugins merely organize code: this could just be replaced directly with // the init_resource and add_system calls from below @@ -93,6 +58,42 @@ fn report_score(score: Res){ } ``` +## `MinimalPlugins` + +Unless you're doing something very unusual, you will *always* want to include the plugins provided by Bevy's [`MinimalPlugins`](https://docs.rs/bevy/latest/bevy/struct.MinimalPlugins.html). We can click through to the source for the `impl PluginGroup for MinimalPlugins` to see what this adds: + +```rust +use bevy_app::{PluginGroup, PluginGroupBuilder}; + +pub struct MinimalPlugins; + +impl PluginGroup for MinimalPlugins { + fn build(&mut self, group: &mut PluginGroupBuilder) { + group.add(bevy_core::CorePlugin::default()); + group.add(bevy_app::ScheduleRunnerPlugin::default()); + } +} +``` + +The `CorePlugin` handles low-level fundamentals such as updating app time, while the `ScheduleRunnerPlugin` sets up the main game loop to run repeatedly over time. + +## `DefaultPlugins` + +Bevy's `DefaultPlugins` are intended to get up and running with a "standard game" as quickly as possible. Let's take a look at the [source](https://github.com/bevyengine/bevy/blob/latest/crates/bevy_internal/src/default_plugins.rs) again. + +As you can see, there are some added niceties (logging and diagnostics, scenes, input and windowing) as well as a number of plugins controlled by feature flags. +These are heavier dependencies that you may want to disable for some games (or platforms), and replace with your own alternatives. +To do so, we can use [cargo features](https://doc.rust-lang.org/cargo/reference/features.html) to disable them in our game. + +In your `Cargo.toml` file, 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 = {"0.5", , default-features = false, features = ["..."]} +``` + +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. + ## Third-party plugins Importing 3rd-party plugins is easy; they're just Rust code! From 0e9677d35018185352c59b74480e1c636d45f117 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Fri, 18 Jun 2021 23:54:44 -0400 Subject: [PATCH 17/44] Added page on App and AppBuilder --- content/learn/book/welcome/app/_index.md | 91 ++++++++++++++++++++ content/learn/book/welcome/plugins/_index.md | 2 +- 2 files changed, 92 insertions(+), 1 deletion(-) create mode 100644 content/learn/book/welcome/app/_index.md diff --git a/content/learn/book/welcome/app/_index.md b/content/learn/book/welcome/app/_index.md new file mode 100644 index 0000000000..d3d70a38c7 --- /dev/null +++ b/content/learn/book/welcome/app/_index.md @@ -0,0 +1,91 @@ ++++ +title = "Creating Bevy apps" +weight = 2 +template = "book-section.html" +page_template = "book-section.html" ++++ + +When you're making a game in Bevy, you will have a single `App`, which stores and handles all of your game logic and data. +Let's take a closer look at that hello world code. + +```rust +use bevy::prelude::*; + +fn main(){ + App::new() + .build() + .add_system(hello.system()) + .run(); +} + +fn hello(){ + println!("Hello, Bevy!") +} +``` + +So, we first create our [`App`](https://docs.rs/bevy/latest/bevy/app/struct.App.html), then tell it to [`build`](https://docs.rs/bevy/latest/bevy/app/struct.App.html#method.build), performing initialization steps. +This produces an [`AppBuilder`](https://docs.rs/bevy/latest/bevy/app/struct.AppBuilder.html), which we can use to configure the `App`. +We do so by add a simple system, which prints "Hello, Bevy!" when it is run. +Finally once all of our work is complete, we call [`AppBuilder::run()`](https://docs.rs/bevy/latest/bevy/app/struct.AppBuilder.html#method.run) to actually make our app *do things*. + +## What makes an App? + +So, what sort of data does are `App` really store? +Turns out: it's fairly simple. +Looking at the docs for [`App`](https://docs.rs/bevy/latest/bevy/app/struct.App.html), we find three fields: + +```rust +struct App { + world: World + runner: Box + schedule: Schedule +} +``` + +The `World` stores all of our data, both entity-component data and resources. +The `runner` field contains a function that tells our app how to loop and execute. +And the `Schedule` contains all of the systems that execute on our data, stored in a way that our scheduler can use to run them at the appropriate time. + +Generally, you'll be operating at a higher-level of abstraction than this: thinking about data in terms of specific resources or components, adding systems to the right place rather than manipulating the `Schedule` yourself, and sticking to the default runner. + +To do so, you'll use the API defined by `AppBuilder`. +The most fundamental things you'll do here are to initialize resources in the `World`, add systems to our schedule, and import logic in bulk using plugins. +Let's write a very simple demo that shows how those work. + +```rust +use bevy::prelude::*; + +fn main() { + App::build() + // Plugins are AppBuilder 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) { + // 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) { + info!(fibonacci.a, fibonacci.b); +} +``` diff --git a/content/learn/book/welcome/plugins/_index.md b/content/learn/book/welcome/plugins/_index.md index 515fbbf314..b4a9f1fa55 100644 --- a/content/learn/book/welcome/plugins/_index.md +++ b/content/learn/book/welcome/plugins/_index.md @@ -1,6 +1,6 @@ +++ title = "Modularity through plugins" -weight = 2 +weight = 3 template = "book-section.html" page_template = "book-section.html" +++ From 0b38fbac5d98c7d5a88aec0bbfec28d1c41f73e3 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Fri, 18 Jun 2021 23:56:15 -0400 Subject: [PATCH 18/44] Fix hello_world code It's simply App::build() --- content/learn/book/welcome/app/_index.md | 5 ++--- content/learn/book/welcome/installation/_index.md | 5 ++--- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/content/learn/book/welcome/app/_index.md b/content/learn/book/welcome/app/_index.md index d3d70a38c7..3be1722586 100644 --- a/content/learn/book/welcome/app/_index.md +++ b/content/learn/book/welcome/app/_index.md @@ -12,8 +12,7 @@ Let's take a closer look at that hello world code. use bevy::prelude::*; fn main(){ - App::new() - .build() + App::build() .add_system(hello.system()) .run(); } @@ -23,7 +22,7 @@ fn hello(){ } ``` -So, we first create our [`App`](https://docs.rs/bevy/latest/bevy/app/struct.App.html), then tell it to [`build`](https://docs.rs/bevy/latest/bevy/app/struct.App.html#method.build), performing initialization steps. +So, we first create our [`App`](https://docs.rs/bevy/latest/bevy/app/struct.App.html) by telling it to [`build`](https://docs.rs/bevy/latest/bevy/app/struct.App.html#method.build), performing initialization steps. This produces an [`AppBuilder`](https://docs.rs/bevy/latest/bevy/app/struct.AppBuilder.html), which we can use to configure the `App`. We do so by add a simple system, which prints "Hello, Bevy!" when it is run. Finally once all of our work is complete, we call [`AppBuilder::run()`](https://docs.rs/bevy/latest/bevy/app/struct.AppBuilder.html#method.run) to actually make our app *do things*. diff --git a/content/learn/book/welcome/installation/_index.md b/content/learn/book/welcome/installation/_index.md index 3c72a337b8..4e7d4a1a32 100644 --- a/content/learn/book/welcome/installation/_index.md +++ b/content/learn/book/welcome/installation/_index.md @@ -103,7 +103,7 @@ Within `main.rs`, let's create our first app! use bevy::prelude::*; fn main(){ - App::new().build().run(); + App::build().run(); } ``` @@ -115,8 +115,7 @@ Let's add our first system by modifying the file to the following: use bevy::prelude::*; fn main(){ - App::new() - .build() + App::build() .add_system(hello.system()) .run(); } From 138fa48aefb9aca22244723ce91bce7c3af97625 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Sat, 19 Jun 2021 16:20:47 -0400 Subject: [PATCH 19/44] Swapped out Hello World example in Installation DefaultPlugins will stress test the install much better --- content/learn/book/welcome/app/_index.md | 2 +- .../learn/book/welcome/installation/_index.md | 29 ++++--------------- 2 files changed, 6 insertions(+), 25 deletions(-) diff --git a/content/learn/book/welcome/app/_index.md b/content/learn/book/welcome/app/_index.md index 3be1722586..d859cb0c0e 100644 --- a/content/learn/book/welcome/app/_index.md +++ b/content/learn/book/welcome/app/_index.md @@ -6,7 +6,7 @@ page_template = "book-section.html" +++ When you're making a game in Bevy, you will have a single `App`, which stores and handles all of your game logic and data. -Let's take a closer look at that hello world code. +Let's make a trivial Hello World app. ```rust use bevy::prelude::*; diff --git a/content/learn/book/welcome/installation/_index.md b/content/learn/book/welcome/installation/_index.md index 4e7d4a1a32..507ea64894 100644 --- a/content/learn/book/welcome/installation/_index.md +++ b/content/learn/book/welcome/installation/_index.md @@ -95,39 +95,20 @@ 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! -### Hello Bevy World +### Checking that it works -Within `main.rs`, let's create our first app! +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().run(); + App::build().add_plugins(DefaultPlugins).run(); } ``` -This won't report anything interesting: it merely creates an empty app with an empty **world**. - -Let's add our first system by modifying the file to the following: - -```rust -use bevy::prelude::*; - -fn main(){ - App::build() - .add_system(hello.system()) - .run(); -} - -fn hello(){ - println!("Hello, Bevy!") -} -``` - -Systems in Bevy are just ordinary Rust functions, which are registered in our app to operate on our world. - -Calling `cargo run` will run our schedule once, causing `hello` to print "Hello, Bevy!", allowing us to verify our installation of Bevy. +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 From 70fbcb1579855b40fa697dab9d910a17883c399e Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Sat, 19 Jun 2021 16:33:57 -0400 Subject: [PATCH 20/44] Condensed section on MinimalPlugins to link to code --- content/learn/book/welcome/plugins/_index.md | 28 +++++++------------- 1 file changed, 9 insertions(+), 19 deletions(-) diff --git a/content/learn/book/welcome/plugins/_index.md b/content/learn/book/welcome/plugins/_index.md index b4a9f1fa55..daac9108b0 100644 --- a/content/learn/book/welcome/plugins/_index.md +++ b/content/learn/book/welcome/plugins/_index.md @@ -58,25 +58,6 @@ fn report_score(score: Res){ } ``` -## `MinimalPlugins` - -Unless you're doing something very unusual, you will *always* want to include the plugins provided by Bevy's [`MinimalPlugins`](https://docs.rs/bevy/latest/bevy/struct.MinimalPlugins.html). We can click through to the source for the `impl PluginGroup for MinimalPlugins` to see what this adds: - -```rust -use bevy_app::{PluginGroup, PluginGroupBuilder}; - -pub struct MinimalPlugins; - -impl PluginGroup for MinimalPlugins { - fn build(&mut self, group: &mut PluginGroupBuilder) { - group.add(bevy_core::CorePlugin::default()); - group.add(bevy_app::ScheduleRunnerPlugin::default()); - } -} -``` - -The `CorePlugin` handles low-level fundamentals such as updating app time, while the `ScheduleRunnerPlugin` sets up the main game loop to run repeatedly over time. - ## `DefaultPlugins` Bevy's `DefaultPlugins` are intended to get up and running with a "standard game" as quickly as possible. Let's take a look at the [source](https://github.com/bevyengine/bevy/blob/latest/crates/bevy_internal/src/default_plugins.rs) again. @@ -94,6 +75,15 @@ bevy = {"0.5", , default-features = false, features = ["..."]} 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. +## `MinimalPlugins` + +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 [`MinimalPlugins`](https://docs.rs/bevy/latest/bevy/struct.MinimalPlugins.html) 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 [`CorePlugin`](https://docs.rs/bevy/latest/bevy/core/struct.CorePlugin.html) and [`ScheduleRunnerPlugin`](https://docs.rs/bevy/latest/bevy/app/struct.ScheduleRunnerPlugin.html). + +The `CorePlugin` handles low-level fundamentals such as updating app time, while the `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 Rust code! From c2f90707d400c29e9c549cd10052e048165cdac1 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Sat, 31 Jul 2021 15:20:31 -0400 Subject: [PATCH 21/44] Added advice on publishing 3rd party plugins Credit to @BlackPhlox for the suggestion and initial work in #195. --- content/learn/book/welcome/plugins/_index.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/content/learn/book/welcome/plugins/_index.md b/content/learn/book/welcome/plugins/_index.md index daac9108b0..2b14f27546 100644 --- a/content/learn/book/welcome/plugins/_index.md +++ b/content/learn/book/welcome/plugins/_index.md @@ -86,11 +86,14 @@ This functionality is essential: starting with these plugins is virtually always ## Third-party plugins -Importing 3rd-party plugins is easy; they're just Rust code! +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. +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! 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) for guidance, [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! From b2f30c18b66a8bb6520d2fc55c5c198366a640e2 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Sat, 31 Jul 2021 15:50:18 -0400 Subject: [PATCH 22/44] Removed references to AppBuilder --- content/learn/book/welcome/app/_index.md | 13 ++++++------- content/learn/book/welcome/plugins/_index.md | 6 +++--- 2 files changed, 9 insertions(+), 10 deletions(-) diff --git a/content/learn/book/welcome/app/_index.md b/content/learn/book/welcome/app/_index.md index d859cb0c0e..c855fa6edd 100644 --- a/content/learn/book/welcome/app/_index.md +++ b/content/learn/book/welcome/app/_index.md @@ -12,7 +12,7 @@ Let's make a trivial Hello World app. use bevy::prelude::*; fn main(){ - App::build() + App::new() .add_system(hello.system()) .run(); } @@ -22,10 +22,9 @@ fn hello(){ } ``` -So, we first create our [`App`](https://docs.rs/bevy/latest/bevy/app/struct.App.html) by telling it to [`build`](https://docs.rs/bevy/latest/bevy/app/struct.App.html#method.build), performing initialization steps. -This produces an [`AppBuilder`](https://docs.rs/bevy/latest/bevy/app/struct.AppBuilder.html), which we can use to configure the `App`. -We do so by add a simple system, which prints "Hello, Bevy!" when it is run. -Finally once all of our work is complete, we call [`AppBuilder::run()`](https://docs.rs/bevy/latest/bevy/app/struct.AppBuilder.html#method.run) to actually make our app *do things*. +The process is straightforward: we first create a new [`App`](https://docs.rs/bevy/latest/bevy/app/struct.App.html). +Then, we add a simple system, which prints "Hello, Bevy!" when it is run. +Finally once we're done configuring the app, we call [`App::run()`](https://docs.rs/bevy/latest/bevy/app/struct.App.html#method.run) to actually make our app *do things*. ## What makes an App? @@ -47,7 +46,7 @@ And the `Schedule` contains all of the systems that execute on our data, stored Generally, you'll be operating at a higher-level of abstraction than this: thinking about data in terms of specific resources or components, adding systems to the right place rather than manipulating the `Schedule` yourself, and sticking to the default runner. -To do so, you'll use the API defined by `AppBuilder`. +To do so, you'll use the various methods of the `App`. The most fundamental things you'll do here are to initialize resources in the `World`, add systems to our schedule, and import logic in bulk using plugins. Let's write a very simple demo that shows how those work. @@ -56,7 +55,7 @@ use bevy::prelude::*; fn main() { App::build() - // Plugins are AppBuilder code that was written elsewhere, + // 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` diff --git a/content/learn/book/welcome/plugins/_index.md b/content/learn/book/welcome/plugins/_index.md index 2b14f27546..f24139cabb 100644 --- a/content/learn/book/welcome/plugins/_index.md +++ b/content/learn/book/welcome/plugins/_index.md @@ -12,8 +12,8 @@ By combining Bevy's first-party plugins with third-party alternatives, you can m ## Writing your own plugins -Plugins are collections of code that modify the `AppBuilder` (which controls all of the data and logic of our game) using the builder pattern. -Any code in a plugin could be directly substituted directly on the base `AppBuilder`. +Plugins are collections of code that modify the `App` (which controls all of the data and logic of our game) using the builder pattern. +Any code in a plugin could be directly substituted directly on the base `App`. There's no magic to be found here; they're just a straightforward tool for code organization. You can write your own to organize your own code by implementing the `Plugin` trait on a struct of your own creation. @@ -34,7 +34,7 @@ fn main(){ struct ScorePlugin; impl Plugin for ScorePlugin { - fn build(&self, app: &mut AppBuilder) { + fn build(&self, app: &mut App) { app // The Score struct is addded as a resource (global singleton) to the world, // beginning at the default value of 0 From a3a00adc5cc1e7f14ad27afaff8da1cf11a43240 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Sat, 31 Jul 2021 16:03:34 -0400 Subject: [PATCH 23/44] Encourage the reader to explore the reference docs more --- content/learn/book/welcome/app/_index.md | 23 ++++++++--------------- 1 file changed, 8 insertions(+), 15 deletions(-) diff --git a/content/learn/book/welcome/app/_index.md b/content/learn/book/welcome/app/_index.md index c855fa6edd..5138675441 100644 --- a/content/learn/book/welcome/app/_index.md +++ b/content/learn/book/welcome/app/_index.md @@ -30,24 +30,17 @@ Finally once we're done configuring the app, we call [`App::run()`](https://docs So, what sort of data does are `App` really store? Turns out: it's fairly simple. -Looking at the docs for [`App`](https://docs.rs/bevy/latest/bevy/app/struct.App.html), we find three fields: +Looking at the docs for [`App`](https://docs.rs/bevy/latest/bevy/app/struct.App.html), we find three fields: `world`, `runner` and `schedule`. +You can read more about these by exploring the reference documentation linked just above. -```rust -struct App { - world: World - runner: Box - schedule: Schedule -} -``` - -The `World` stores all of our data, both entity-component data and resources. -The `runner` field contains a function that tells our app how to loop and execute. -And the `Schedule` contains all of the systems that execute on our data, stored in a way that our scheduler can use to run them at the appropriate time. +Generally, you'll be operating at a higher-level of abstraction than these basic primitives: thinking about data in terms of specific resources or components, adding systems via convenient methods rather than manually supplying a `Schedule`, and sticking to the default runner which runs your game logic in a loop. -Generally, you'll be operating at a higher-level of abstraction than this: thinking about data in terms of specific resources or components, adding systems to the right place rather than manipulating the `Schedule` yourself, and sticking to the default runner. +To do so, you'll customize your own `App` using various methods with the builder pattern. +The most fundamental tools to do so are: -To do so, you'll use the various methods of the `App`. -The most fundamental things you'll do here are to initialize resources in the `World`, add systems to our schedule, and import logic in bulk using plugins. + 1. Initializing resources in the `World` to store global data. + 2. Adding systems to our `Schedule` to perform logic in the specified order. + 3. Importing other blocks of logic and code using plugins. Let's write a very simple demo that shows how those work. ```rust From 3e370de9103180da0a0d8f12a627b23b9a4484d2 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Sun, 1 Aug 2021 11:25:34 -0400 Subject: [PATCH 24/44] Introduction page optimism and clarity --- content/learn/book/welcome/_index.md | 34 ++++++++++++++-------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/content/learn/book/welcome/_index.md b/content/learn/book/welcome/_index.md index a29dc2d3c9..95afb5f2bc 100644 --- a/content/learn/book/welcome/_index.md +++ b/content/learn/book/welcome/_index.md @@ -8,16 +8,17 @@ page_template = "book-section.html" Welcome to the Bevy game engine! A bevy may be a group of birds, but our engine is: -- Rust-first: with all the safety, tooling and power that comes with a modern systems language -- completely free, open source and hackable with an architecture designed for modularity -- powered by an ergonomic and innovative ECS that makes writing clear, performant gameplay and engine logic a joy -- cross-platform: support all major desktop platforms with a single code-base, with limited mobile and web support -- designed for effortless parallelism with a data-oriented design and automatic parallel scheduler -- built on a high-performance foundation +- **Rust-first:** with all the safety, tooling and power that comes with a modern systems language +- **Completely free:** open source 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* and iOS 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 + ## Stability warning Bevy aims to be a general-purpose game engine capable of handling arbitrary 2D or 3D games. @@ -28,22 +29,21 @@ It is currently completely missing first-party solutions for: - networking - console support -Solid third-party (but not first-party) solutions currently exist for: +The following areas are part of the engine itself, but are very immature: -- [audio](https://crates.io/crates/bevy_kira_audio) -- [physics](https://github.com/dimforge/bevy_rapier) +- audio +- user interfaces -The following areas are being explored by the engine itself, but are very immature: +Solid third-party solutions currently exist for: -- user interface -- web support -- mobile support +- [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 Just Work out of the box yet. -Contributions are extremely welcome, but if you want something fully featured for a game *today*, Bevy is not the right engine for you yet. +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 are extremely welcome, but if you want something fully featured to make your dream game *today*, Bevy is not the right engine for you yet. 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. - -While we'll do our best to provide migration guides, updating versions of Bevy is largely an exercise in letting the excellent Rust tooling guide you and chasing the errors until everything compiles again. +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. From 190c6a214f4a79809b2d6216a9423908367b6118 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Sun, 1 Aug 2021 11:28:10 -0400 Subject: [PATCH 25/44] Cleaned up game terminology --- content/learn/book/welcome/app/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/learn/book/welcome/app/_index.md b/content/learn/book/welcome/app/_index.md index 5138675441..ebfd42c8e8 100644 --- a/content/learn/book/welcome/app/_index.md +++ b/content/learn/book/welcome/app/_index.md @@ -5,7 +5,7 @@ template = "book-section.html" page_template = "book-section.html" +++ -When you're making a game in Bevy, you will have a single `App`, which stores and handles all of your game logic and data. +Bevy programs store and execute all of their game logic and data with a single `App` data structure. Let's make a trivial Hello World app. ```rust From ec50cff0ca3655be9088b77aeafdb97dafb18edd Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Sun, 1 Aug 2021 11:29:27 -0400 Subject: [PATCH 26/44] dbg -> info --- content/learn/book/welcome/plugins/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/learn/book/welcome/plugins/_index.md b/content/learn/book/welcome/plugins/_index.md index f24139cabb..9aa133942c 100644 --- a/content/learn/book/welcome/plugins/_index.md +++ b/content/learn/book/welcome/plugins/_index.md @@ -54,7 +54,7 @@ fn increment_score(score: ResMut){ } fn report_score(score: Res){ - dbg!(score); + info!(score); } ``` From f2799f534035ea289c0902355514f8b9dbe57ed3 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Mon, 2 Aug 2021 12:22:19 -0400 Subject: [PATCH 27/44] Clarity improvements for Plugin page --- content/learn/book/welcome/plugins/_index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/learn/book/welcome/plugins/_index.md b/content/learn/book/welcome/plugins/_index.md index 9aa133942c..9df1b3fdbf 100644 --- a/content/learn/book/welcome/plugins/_index.md +++ b/content/learn/book/welcome/plugins/_index.md @@ -60,7 +60,7 @@ fn report_score(score: Res){ ## `DefaultPlugins` -Bevy's `DefaultPlugins` are intended to get up and running with a "standard game" as quickly as possible. Let's take a look at the [source](https://github.com/bevyengine/bevy/blob/latest/crates/bevy_internal/src/default_plugins.rs) again. +Bevy's [`DefaultPlugins`](https://docs.rs/bevy/latest/bevy/struct.DefaultPlugins.html) are intended to get up and running with a "standard game" as quickly as possible. Let's take a look at the [source](https://github.com/bevyengine/bevy/blob/latest/crates/bevy_internal/src/default_plugins.rs) to see what's included. As you can see, there are some added niceties (logging and diagnostics, scenes, input and windowing) as well as a number of plugins controlled by feature flags. These are heavier dependencies that you may want to disable for some games (or platforms), and replace with your own alternatives. @@ -92,7 +92,7 @@ Bevy's modular nature tends to result in simple plug-and-play interoperability a 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! +4. Add the plugin to your app (i.e. `app.add_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. From fc9a7ad9040960053a08aaf12ba5d5381bb4a003 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Mon, 2 Aug 2021 12:38:29 -0400 Subject: [PATCH 28/44] Clarity improvements for `App` page --- content/learn/book/welcome/app/_index.md | 27 ++++++++++++------------ 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/content/learn/book/welcome/app/_index.md b/content/learn/book/welcome/app/_index.md index ebfd42c8e8..7d16e6c56d 100644 --- a/content/learn/book/welcome/app/_index.md +++ b/content/learn/book/welcome/app/_index.md @@ -6,7 +6,11 @@ page_template = "book-section.html" +++ Bevy programs store and execute all of their game logic and data with a single `App` data structure. -Let's make a trivial Hello World app. + +Let's make a trivial Hello World app to demonstrate how that works in practice. +The process is straightforward: we first create a new [`App`](https://docs.rs/bevy/latest/bevy/app/struct.App.html). +Then, we add a simple system, which prints "Hello, Bevy!" when it is run. +Finally once we're done configuring the app, we call [`App::run()`](https://docs.rs/bevy/latest/bevy/app/struct.App.html#method.run) to actually make our app *do things*. ```rust use bevy::prelude::*; @@ -22,25 +26,20 @@ fn hello(){ } ``` -The process is straightforward: we first create a new [`App`](https://docs.rs/bevy/latest/bevy/app/struct.App.html). -Then, we add a simple system, which prints "Hello, Bevy!" when it is run. -Finally once we're done configuring the app, we call [`App::run()`](https://docs.rs/bevy/latest/bevy/app/struct.App.html#method.run) to actually make our app *do things*. - ## What makes an App? -So, what sort of data does are `App` really store? -Turns out: it's fairly simple. -Looking at the docs for [`App`](https://docs.rs/bevy/latest/bevy/app/struct.App.html), we find three fields: `world`, `runner` and `schedule`. +So, what sort of data does our `App` really store? +Looking at the docs for [`App`](https://docs.rs/bevy/latest/bevy/app/struct.App.html), 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 higher-level of abstraction than these basic primitives: thinking about data in terms of specific resources or components, adding systems via convenient methods rather than manually supplying a `Schedule`, and sticking to the default runner which runs your game logic in a loop. - -To do so, you'll customize your own `App` using various methods with the builder pattern. -The most fundamental tools to do so are: +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 `App` 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 `World` to store global data. - 2. Adding systems to our `Schedule` to perform logic in the specified order. - 3. Importing other blocks of logic and code using plugins. + 2. Adding systems to our `Schedule` to perform logic. + 3. Importing other blocks of `App`-modifying code using plugins. Let's write a very simple demo that shows how those work. ```rust From d8ebee377e81091536130893b4df7cb564d5602b Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Mon, 2 Aug 2021 12:53:25 -0400 Subject: [PATCH 29/44] Clarified that Bevy is both free and libre --- content/learn/book/welcome/_index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/learn/book/welcome/_index.md b/content/learn/book/welcome/_index.md index 95afb5f2bc..6ef58eec08 100644 --- a/content/learn/book/welcome/_index.md +++ b/content/learn/book/welcome/_index.md @@ -8,8 +8,8 @@ page_template = "book-section.html" Welcome to the Bevy game engine! A bevy may be a group of birds, but our engine is: -- **Rust-first:** with all the safety, tooling and power that comes with a modern systems language -- **Completely free:** open source and hackable with an architecture designed for modularity +- **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* and iOS with a single code base - **Effortless parallelism:** a data-oriented design and automatic parallel scheduler provide a high-performance foundation for your game From 4f169abf6528b92b263fed3dd39a480adae4a572 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Mon, 2 Aug 2021 12:53:49 -0400 Subject: [PATCH 30/44] Clarity improvements to Welcome page --- content/learn/book/welcome/_index.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/content/learn/book/welcome/_index.md b/content/learn/book/welcome/_index.md index 6ef58eec08..925516f0c2 100644 --- a/content/learn/book/welcome/_index.md +++ b/content/learn/book/welcome/_index.md @@ -23,7 +23,7 @@ If you just want to try it out hands-on, jump into one of our [quick-start guide 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. -It is currently completely missing first-party solutions for: +No mature solutions currently exist for: - animation - networking @@ -39,9 +39,8 @@ 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 are extremely welcome, but if you want something fully featured to make your dream game *today*, Bevy is not the right engine for you yet. -Check out [Godot](https://godotengine.org/) instead! +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. From ee2bfc3d2ddd2277bc58197761f38d79795002cc Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Fri, 6 Aug 2021 16:53:29 -0400 Subject: [PATCH 31/44] Removed .system() call --- content/learn/book/welcome/app/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/learn/book/welcome/app/_index.md b/content/learn/book/welcome/app/_index.md index 7d16e6c56d..8b025871d3 100644 --- a/content/learn/book/welcome/app/_index.md +++ b/content/learn/book/welcome/app/_index.md @@ -17,7 +17,7 @@ use bevy::prelude::*; fn main(){ App::new() - .add_system(hello.system()) + .add_system(hello) .run(); } From 4bd12cc348cb7b8ff41b9aa5afc06f2ed7edc8d3 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Fri, 6 Aug 2021 16:58:44 -0400 Subject: [PATCH 32/44] Typo fix --- content/learn/book/welcome/plugins/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/learn/book/welcome/plugins/_index.md b/content/learn/book/welcome/plugins/_index.md index 9df1b3fdbf..ec79702b86 100644 --- a/content/learn/book/welcome/plugins/_index.md +++ b/content/learn/book/welcome/plugins/_index.md @@ -92,7 +92,7 @@ Bevy's modular nature tends to result in simple plug-and-play interoperability a 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_add_plugin(bevy_third_party_plugin)`)! +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. From ce83f8582ae39cfccbf72bce69eb5b8b6051eafc Mon Sep 17 00:00:00 2001 From: Carter Anderson Date: Fri, 6 Aug 2021 16:19:45 -0700 Subject: [PATCH 33/44] Style and phrasing tweaks --- content/learn/book/welcome/_index.md | 2 +- .../book/welcome/{app => apps}/_index.md | 10 +-- .../learn/book/welcome/installation/_index.md | 2 +- content/learn/book/welcome/plugins/_index.md | 74 ++++++++++--------- 4 files changed, 48 insertions(+), 40 deletions(-) rename content/learn/book/welcome/{app => apps}/_index.md (97%) diff --git a/content/learn/book/welcome/_index.md b/content/learn/book/welcome/_index.md index 925516f0c2..a959c733fb 100644 --- a/content/learn/book/welcome/_index.md +++ b/content/learn/book/welcome/_index.md @@ -1,5 +1,5 @@ +++ -title = "Welcome to Bevy" +title = "Welcome" weight = 1 sort_by = "weight" template = "book-section.html" diff --git a/content/learn/book/welcome/app/_index.md b/content/learn/book/welcome/apps/_index.md similarity index 97% rename from content/learn/book/welcome/app/_index.md rename to content/learn/book/welcome/apps/_index.md index 8b025871d3..20add3cb4f 100644 --- a/content/learn/book/welcome/app/_index.md +++ b/content/learn/book/welcome/apps/_index.md @@ -1,5 +1,5 @@ +++ -title = "Creating Bevy apps" +title = "Apps" weight = 2 template = "book-section.html" page_template = "book-section.html" @@ -16,9 +16,9 @@ Finally once we're done configuring the app, we call [`App::run()`](https://docs use bevy::prelude::*; fn main(){ - App::new() - .add_system(hello) - .run(); + App::new() + .add_system(hello) + .run(); } fn hello(){ @@ -46,7 +46,7 @@ Let's write a very simple demo that shows how those work. use bevy::prelude::*; fn main() { - App::build() + App::new() // Plugins are App code that was written elsewhere, // imported as a single unit for organization and clarity .add_plugins(DefaultPlugins) diff --git a/content/learn/book/welcome/installation/_index.md b/content/learn/book/welcome/installation/_index.md index 507ea64894..6a2f2ad03b 100644 --- a/content/learn/book/welcome/installation/_index.md +++ b/content/learn/book/welcome/installation/_index.md @@ -1,5 +1,5 @@ +++ -title = "Installing Rust and Bevy" +title = "Setup" weight = 1 template = "book-section.html" page_template = "book-section.html" diff --git a/content/learn/book/welcome/plugins/_index.md b/content/learn/book/welcome/plugins/_index.md index ec79702b86..887bbab979 100644 --- a/content/learn/book/welcome/plugins/_index.md +++ b/content/learn/book/welcome/plugins/_index.md @@ -1,48 +1,47 @@ +++ -title = "Modularity through plugins" +title = "Plugins" weight = 3 template = "book-section.html" page_template = "book-section.html" +++ -In Bevy, virtually all of the functionality you might want is added via **plugins**, which are added to your app. -These might provide basic windowing functionality, handle input or sound, calculate physics or provide game-specific logic like a tile map system. +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_app", name="App")}}. 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)}}. -By combining Bevy's first-party plugins with third-party alternatives, you can modularly customize the behaviour of the Bevy game engine, and then add your own plugins to contain your own game-specific code in a well-organized way. +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 the `App` (which controls all of the data and logic of our game) using the builder pattern. +Plugins are collections of code that modify {{rust_type(type="trait" crate="bevy_app" name="App" plural=true)}}. Any code in a plugin could be directly substituted directly on the base `App`. There's no magic to be found here; they're just a straightforward tool for code organization. -You can write your own to organize your own code by implementing the `Plugin` trait on a struct of your own creation. +Plugins are types that implement the {{rust_type(type="trait" crate="bevy_app" name="Plugin")}} trait: ```rust use bevy::prelude::*; fn main(){ - App::build() - // As discussed below, DefaultPlugins provide the standard scaffolding for Bevy games - .add_plugins(DefaultPlugins) - // Plugins merely organize code: this could just be replaced directly with - // the init_resource and add_system calls from below - .add_plugin(ScorePlugin) - .run(); + 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 addded as a resource (global singleton) to the world, - // beginning at the default value of 0 - .init_resource::() - // 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()); + app + // The Score struct is added as a resource (global singleton) to the world, + // beginning at the default value of 0 + .init_resource::() + // 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()); } } @@ -58,22 +57,18 @@ fn report_score(score: Res){ } ``` -## `DefaultPlugins` +## `DefaultPlugins` and `PluginGroup` -Bevy's [`DefaultPlugins`](https://docs.rs/bevy/latest/bevy/struct.DefaultPlugins.html) are intended to get up and running with a "standard game" as quickly as possible. Let's take a look at the [source](https://github.com/bevyengine/bevy/blob/latest/crates/bevy_internal/src/default_plugins.rs) to see what's included. +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. -As you can see, there are some added niceties (logging and diagnostics, scenes, input and windowing) as well as a number of plugins controlled by feature flags. -These are heavier dependencies that you may want to disable for some games (or platforms), and replace with your own alternatives. -To do so, we can use [cargo features](https://doc.rust-lang.org/cargo/reference/features.html) to disable them in our game. +You can add {{rust_type(type="struct" crate="bevy" name="DefaultPlugins")}} to your app like this: -In your `Cargo.toml` file, 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 = {"0.5", , default-features = false, features = ["..."]} +```rust +App::new().add_plugins(DefaultPlugins) ``` -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. +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. + ## `MinimalPlugins` @@ -96,4 +91,17 @@ Bevy's modular nature tends to result in simple plug-and-play interoperability a 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) for guidance, [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! +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! + +## Configuring Features in `DefaultPlugins` + +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. From 97a6f9140ef78a0cd135511f5a2c7a90baa3606d Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Mon, 9 Aug 2021 10:21:04 -0400 Subject: [PATCH 34/44] Mention efforts towards XR support --- content/learn/book/welcome/_index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/learn/book/welcome/_index.md b/content/learn/book/welcome/_index.md index a959c733fb..5f95b81ee7 100644 --- a/content/learn/book/welcome/_index.md +++ b/content/learn/book/welcome/_index.md @@ -11,13 +11,14 @@ Welcome to the Bevy game engine! A bevy may be a group of birds, but our engine - **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* and iOS with a single code base +- **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 From 2f0c543c29f3d735ab263a32d36e403395067d67 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Mon, 9 Aug 2021 10:24:47 -0400 Subject: [PATCH 35/44] Removed code blocks from headings --- content/learn/book/welcome/plugins/_index.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/content/learn/book/welcome/plugins/_index.md b/content/learn/book/welcome/plugins/_index.md index 887bbab979..7ceca9a94b 100644 --- a/content/learn/book/welcome/plugins/_index.md +++ b/content/learn/book/welcome/plugins/_index.md @@ -57,7 +57,7 @@ fn report_score(score: Res){ } ``` -## `DefaultPlugins` and `PluginGroup` +## 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. @@ -69,9 +69,6 @@ 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. - -## `MinimalPlugins` - 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 [`MinimalPlugins`](https://docs.rs/bevy/latest/bevy/struct.MinimalPlugins.html) 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 [`CorePlugin`](https://docs.rs/bevy/latest/bevy/core/struct.CorePlugin.html) and [`ScheduleRunnerPlugin`](https://docs.rs/bevy/latest/bevy/app/struct.ScheduleRunnerPlugin.html). @@ -93,7 +90,7 @@ Follow the documentation and examples from the crates you're importing to make s 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! -## Configuring Features in `DefaultPlugins` +## 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. From 331e95126987119f25867ca50c0c9109b75cb62c Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Mon, 9 Aug 2021 11:59:10 -0400 Subject: [PATCH 36/44] Use shortcodes --- content/learn/book/welcome/apps/_index.md | 18 +++++++++--------- .../learn/book/welcome/installation/_index.md | 2 +- content/learn/book/welcome/plugins/_index.md | 12 ++++++------ 3 files changed, 16 insertions(+), 16 deletions(-) diff --git a/content/learn/book/welcome/apps/_index.md b/content/learn/book/welcome/apps/_index.md index 20add3cb4f..fe407165ae 100644 --- a/content/learn/book/welcome/apps/_index.md +++ b/content/learn/book/welcome/apps/_index.md @@ -5,12 +5,12 @@ template = "book-section.html" page_template = "book-section.html" +++ -Bevy programs store and execute all of their game logic and data with a single `App` data structure. +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 [`App`](https://docs.rs/bevy/latest/bevy/app/struct.App.html). +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 [`App::run()`](https://docs.rs/bevy/latest/bevy/app/struct.App.html#method.run) to actually make our app *do things*. +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::*; @@ -28,18 +28,18 @@ fn hello(){ ## What makes an App? -So, what sort of data does our `App` really store? -Looking at the docs for [`App`](https://docs.rs/bevy/latest/bevy/app/struct.App.html), we find three fields: `world`, `schedule` and `runner`. +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 `App` by chaining its methods with the [builder pattern](https://doc.rust-lang.org/1.0.0/style/ownership/builders.html). +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 `World` to store global data. - 2. Adding systems to our `Schedule` to perform logic. - 3. Importing other blocks of `App`-modifying code using plugins. + 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 diff --git a/content/learn/book/welcome/installation/_index.md b/content/learn/book/welcome/installation/_index.md index 6a2f2ad03b..e27bdda0eb 100644 --- a/content/learn/book/welcome/installation/_index.md +++ b/content/learn/book/welcome/installation/_index.md @@ -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 diff --git a/content/learn/book/welcome/plugins/_index.md b/content/learn/book/welcome/plugins/_index.md index 7ceca9a94b..d9d96b4a63 100644 --- a/content/learn/book/welcome/plugins/_index.md +++ b/content/learn/book/welcome/plugins/_index.md @@ -5,14 +5,14 @@ template = "book-section.html" page_template = "book-section.html" +++ -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_app", name="App")}}. 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)}}. +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)}}. 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="trait" crate="bevy_app" name="App" plural=true)}}. -Any code in a plugin could be directly substituted directly on the base `App`. +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: @@ -69,11 +69,11 @@ 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 [`MinimalPlugins`](https://docs.rs/bevy/latest/bevy/struct.MinimalPlugins.html) instead. +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 [`CorePlugin`](https://docs.rs/bevy/latest/bevy/core/struct.CorePlugin.html) and [`ScheduleRunnerPlugin`](https://docs.rs/bevy/latest/bevy/app/struct.ScheduleRunnerPlugin.html). +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 `CorePlugin` handles low-level fundamentals such as updating app time, while the `ScheduleRunnerPlugin` sets up the main game loop to run repeatedly over time. +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 From c289603e12da66aec6833a10e4a3cc10e791f594 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Fri, 13 Aug 2021 18:28:54 -0400 Subject: [PATCH 37/44] Tiny cleanup --- content/learn/book/welcome/_index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/learn/book/welcome/_index.md b/content/learn/book/welcome/_index.md index 5f95b81ee7..94e29bff27 100644 --- a/content/learn/book/welcome/_index.md +++ b/content/learn/book/welcome/_index.md @@ -18,7 +18,7 @@ This book is designed for new and experienced users looking for a thoughtful, [e 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) +**: virtual, mixed and augmented reality (aka XR) compatibility is [in development](https://github.com/bevyengine/bevy/pull/2319) ## Stability warning @@ -40,7 +40,7 @@ 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*. +While Bevy's [modular architecture](plugins/_index.md) 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. From 7042901faaaefbc05dc39843eb1f22758a702c57 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Fri, 13 Aug 2021 18:34:18 -0400 Subject: [PATCH 38/44] Swapped out Fibonacci example Examples that crash are bad. --- content/learn/book/welcome/apps/_index.md | 31 ++++++++--------------- 1 file changed, 10 insertions(+), 21 deletions(-) diff --git a/content/learn/book/welcome/apps/_index.md b/content/learn/book/welcome/apps/_index.md index fe407165ae..769ff6daf9 100644 --- a/content/learn/book/welcome/apps/_index.md +++ b/content/learn/book/welcome/apps/_index.md @@ -49,33 +49,22 @@ fn main() { App::new() // Plugins are App code that was written elsewhere, // imported as a single unit for organization and clarity - .add_plugins(DefaultPlugins) + .add_plugins(MinimalPlugins) // Resources are global singleton data stored in the `World` - .insert_resource(Fibonacci { a: 1, b: 1 }) + .insert_resource(Message {string: "Welcome to Bevy!"}) // Systems run every pass of the game loop and perform logic - .add_system(fibonacci_sum.system()) - .add_system(report_fibonacci.system()) + .add_system(print_message_system.system()) .run(); } -// A simple data structure to store the two current fibonacci numbers -struct Fibonacci { - a: u64, - b: u64, +// This resource can store a string +struct Message { + string: String, } -// This system requires mutable access to our Fibonacci resource, -// so we add `ResMut` to its function parameters -fn fibonacci_sum(mut fibonacci: ResMut) { - // 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) { - info!(fibonacci.a, fibonacci.b); +// This system reads our Message resource, +// so we add `Res` to its function parameters +fn (mut message: Res) { + println!(message.string); } ``` From c7aa36bf6e3a1cdbde1b7acb81e4596b6df09190 Mon Sep 17 00:00:00 2001 From: "Alice I. Cecile" Date: Wed, 13 Oct 2021 13:33:28 -0400 Subject: [PATCH 39/44] Misc cleanup; credit to @djeedai --- content/learn/book/welcome/_index.md | 4 ++-- content/learn/book/welcome/apps/_index.md | 8 ++++---- content/learn/book/welcome/plugins/_index.md | 4 ++-- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/content/learn/book/welcome/_index.md b/content/learn/book/welcome/_index.md index 94e29bff27..24ffdf13e7 100644 --- a/content/learn/book/welcome/_index.md +++ b/content/learn/book/welcome/_index.md @@ -9,7 +9,7 @@ page_template = "book-section.html" 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 +- **Completely free:** [free-of-charge](https://github.com/sponsors/cart), [open source](https://github.com/bevyengine/bevy/blob/main/LICENSE), and fully customizable 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 @@ -23,7 +23,7 @@ If you just want to try it out hands-on, jump into one of our [quick-start guide ## 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. +However, Bevy is not yet production-ready, and there are very good reasons not to choose it for your next project. No mature solutions currently exist for: - animation diff --git a/content/learn/book/welcome/apps/_index.md b/content/learn/book/welcome/apps/_index.md index 769ff6daf9..1128cfe393 100644 --- a/content/learn/book/welcome/apps/_index.md +++ b/content/learn/book/welcome/apps/_index.md @@ -10,7 +10,7 @@ Bevy programs store and execute all of their game logic and data with a single { 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*. +Finally once we're done configuring the app, we call {{rust_type(type="struct" crate="bevy" mod = "app" name="App" method="run" no_mod = "true")}} to actually make our app *do things*. ```rust use bevy::prelude::*; @@ -38,7 +38,7 @@ To do so, customize your own {{rust_type(type="struct" crate="bevy" mod = "app" 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. + 2. Adding systems to our {{rust_type(type="struct" crate="bevy" mod = "ecs/schedule" name="Schedule" no_mod = "true")}} to mutate the state of the world based on game 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. @@ -53,7 +53,7 @@ fn main() { // Resources are global singleton data stored in the `World` .insert_resource(Message {string: "Welcome to Bevy!"}) // Systems run every pass of the game loop and perform logic - .add_system(print_message_system.system()) + .add_system(print_message_system) .run(); } @@ -64,7 +64,7 @@ struct Message { // This system reads our Message resource, // so we add `Res` to its function parameters -fn (mut message: Res) { +fn read_message(message: Res) { println!(message.string); } ``` diff --git a/content/learn/book/welcome/plugins/_index.md b/content/learn/book/welcome/plugins/_index.md index d9d96b4a63..3c0bc3adf0 100644 --- a/content/learn/book/welcome/plugins/_index.md +++ b/content/learn/book/welcome/plugins/_index.md @@ -12,7 +12,7 @@ This empowers Bevy developers to modularly "build their own engine" using offici ## 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")}}. +Any code in a plugin could be directly applied to 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: @@ -71,7 +71,7 @@ Take a look at the [source](https://github.com/bevyengine/bevy/blob/latest/crate 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")}}. +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. From b8a794f918002c3c87c7211d5576e36ebedf32aa Mon Sep 17 00:00:00 2001 From: "Alice I. Cecile" Date: Wed, 13 Oct 2021 13:41:41 -0400 Subject: [PATCH 40/44] Introductory text polish --- content/learn/book/welcome/_index.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/content/learn/book/welcome/_index.md b/content/learn/book/welcome/_index.md index 24ffdf13e7..5dbfcd2682 100644 --- a/content/learn/book/welcome/_index.md +++ b/content/learn/book/welcome/_index.md @@ -6,18 +6,19 @@ template = "book-section.html" page_template = "book-section.html" +++ -Welcome to the Bevy game engine! A bevy may be a group of birds, but our engine is: +Welcome to the Bevy game engine! A bevy may be a group of birds, but our engine offers a fresh new experience that's: - **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 fully customizable 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 +- **Hardware-aware:** a data-oriented design and automatic parallel scheduler provide a high-performance foundation for your game +- **Powered by an innovative ECS:** our ergonomic, type-safe, full-native entity-component-system architecture that makes writing clear, scalable 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 +*: support for these platforms is still limited; you may encounter some missing features or a [more involved setup process](https://bevy-cheatbook.github.io/platforms/wasm.html) + **: virtual, mixed and augmented reality (aka XR) compatibility is [in development](https://github.com/bevyengine/bevy/pull/2319) ## Stability warning @@ -44,6 +45,6 @@ While Bevy's [modular architecture](plugins/_index.md) makes it relatively easy [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. +This allows us to get user feedback and refine the engine now, adding new features and fixing problems fast, rather than being tied to our 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. From 662380b27caf5f0a1d63ce85b0248ee4531da488 Mon Sep 17 00:00:00 2001 From: "Alice I. Cecile" Date: Wed, 13 Oct 2021 13:52:39 -0400 Subject: [PATCH 41/44] Better setup page, including @lukors work in #137 --- .../welcome/{installation => setup}/_index.md | 62 ++++++++++++++++++- 1 file changed, 61 insertions(+), 1 deletion(-) rename content/learn/book/welcome/{installation => setup}/_index.md (58%) diff --git a/content/learn/book/welcome/installation/_index.md b/content/learn/book/welcome/setup/_index.md similarity index 58% rename from content/learn/book/welcome/installation/_index.md rename to content/learn/book/welcome/setup/_index.md index e27bdda0eb..d46359edbe 100644 --- a/content/learn/book/welcome/installation/_index.md +++ b/content/learn/book/welcome/setup/_index.md @@ -21,7 +21,7 @@ Once this is done, you should have the `rustc` compiler and the `cargo` build sy * [Linux](https://github.com/bevyengine/bevy/blob/main/docs/linux_dependencies.md) * Windows: Make sure to install [VS2019 build tools](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools&rel=16) -* MacOS: No dependencies here +* MacOS: No dependencies here! ### Code Editor / IDE @@ -110,6 +110,66 @@ fn main(){ 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. +### Performance by default + +Rust's compiler supports several levels of performance optimization, with fairly dramatic effects on Bevy's performance. +For a more pleasant and realistic development experience, we recommend enabling optimized compilation by default by adding the following lines to your `Cargo.toml`. + +```toml +[profile.dev] +opt-level = 3 +``` + +### Faster compiling + +* **Bevy's Dynamic Linking Feature**: This is the most impactful iterative compilation time decrease! It requires no special setup except on Windows, where you also have to follow the three numbered steps below for it to work. 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. + +For the fastest iterative compile times, we recommend the following configuration as well. You need to follow all three steps for any effect: + +1. **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 clang` + * **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` +2. **Nightly Rust Compiler**: This gives access to the latest performance improvements and "unstable" optimizations + + ```sh + # Install the nightly toolchain + rustup toolchain install nightly + # EITHER 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, but just want to use it once for the current command. + +3. **Configure cargo**: With the linker installed and nightly rust activated, all we need to do now is put them to proper use. 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`. + + Beyond enabling the LLD linker, this configuration file also activates **Generic Sharing** (unless you use Windows), which 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. + +4. **Hot reloading**: Sometimes, the fastest compilation is no compilation. +For instant, compile-free simple changes, the excellent community-run [`bevy-inspector-egui`](https://crates.io/crates/bevy-inspector-egui) crate allows you to visually edit the values of your structs, and see the effect on your game in real time. + ## Troubleshooting Having trouble getting Bevy running? From 2ae08988d8e8f6a96e17924185fe86e62e941309 Mon Sep 17 00:00:00 2001 From: "Alice I. Cecile" Date: Wed, 13 Oct 2021 13:56:46 -0400 Subject: [PATCH 42/44] More review in App page --- content/learn/book/welcome/apps/_index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/learn/book/welcome/apps/_index.md b/content/learn/book/welcome/apps/_index.md index 1128cfe393..0b6dad0bd6 100644 --- a/content/learn/book/welcome/apps/_index.md +++ b/content/learn/book/welcome/apps/_index.md @@ -37,8 +37,8 @@ Generally, you'll be operating at a more granular level than these basic primiti 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 mutate the state of the world based on game logic. + 1. Initializing resources in the {{rust_type(type="struct" crate="bevy" mod = "ecs/world" name="World" no_mod = "true")}} to store globally available data that we only need a single copy of. + 2. Adding systems to our {{rust_type(type="struct" crate="bevy" mod = "ecs/schedule" name="Schedule" no_mod = "true")}}, which can read and modify resources and our entities' components, according to our game 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. From 5faa8fad224b61b0e6d963d2b3f4679577a35637 Mon Sep 17 00:00:00 2001 From: "Alice I. Cecile" Date: Wed, 13 Oct 2021 14:03:03 -0400 Subject: [PATCH 43/44] Cut detail about minimal plugins --- content/learn/book/welcome/plugins/_index.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/content/learn/book/welcome/plugins/_index.md b/content/learn/book/welcome/plugins/_index.md index 3c0bc3adf0..2f555e480e 100644 --- a/content/learn/book/welcome/plugins/_index.md +++ b/content/learn/book/welcome/plugins/_index.md @@ -69,12 +69,7 @@ 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. +If you're looking to structure your Bevy app in an unusual way (for example, if you want to run it in a [headless fashion](https://github.com/bevyengine/bevy/blob/latest/examples/app/headless.rs)) 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. ## Third-party plugins @@ -101,4 +96,7 @@ In your `Cargo.toml` file, you can disable default features and opt-in to the [f 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. +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. + +Many of Bevy's subcrates can also be used directly on their own and integrated with other engines or your own framework. +[`bevy_ecs`](https://crates.io/crates/bevy_ecs) is a particularly popular choice for this, allowing you to use our fast, featureful ECS in more unusual projects. From 038618041da7bbcd577ed4db9f0f2b9d100403d7 Mon Sep 17 00:00:00 2001 From: "Alice I. Cecile" Date: Wed, 13 Oct 2021 14:08:03 -0400 Subject: [PATCH 44/44] Slightly better cargo new directions --- content/learn/book/welcome/setup/_index.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/learn/book/welcome/setup/_index.md b/content/learn/book/welcome/setup/_index.md index d46359edbe..e1a4704827 100644 --- a/content/learn/book/welcome/setup/_index.md +++ b/content/learn/book/welcome/setup/_index.md @@ -45,13 +45,15 @@ Now we are ready to set up a Bevy project! Bevy is just a normal Rust dependency ### Create a new Rust project -First, navigate to a folder where you want to create your new project. Then, run the following command to create a new folder containing our rust executable project: +First, navigate to a folder where you want to create your new project. Then, run the following command to create (and then navigate to) a new folder containing our rust executable project: ```sh cargo new my_bevy_game cd my_bevy_game ``` +If you already have a folder that you'd like to use, use `cargo init` from within that folder instead. + Now run `cargo run` to build and run your project. You should see `Hello, world!` printed to your terminal. Open the `my_bevy_game` folder in your code editor of choice and take some time to look through the files. `main.rs` is the entry point of your program: