diff --git a/content/learn/book/welcome/apps/_index.md b/content/learn/book/welcome/apps/_index.md index 0b6dad0bd6..d8f0bb5f45 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 {{rust_type(type="struct" crate="bevy" mod = "app" name="App" no_mod = "true")}} data structure. +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 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")}}. +The process is straightforward: we first create a new [`App`]. 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" method="run" no_mod = "true")}} to actually make our app *do things*. +Finally once we're done configuring the app, we call [`App`] 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 {{rust_type(type="struct" crate="bevy" mod = "app" name="App" no_mod = "true")}} really store? +So, what sort of data does our [`App`] really store? Looking at the docs linked, we find three fields: `world`, `schedule` and `runner`. The `world` field stores all of our game's data, the `schedule` holds the systems that operate on this data (and the order in which they do so) and the `runner` interprets the schedule to control the broad execution strategy. You can read more about these by exploring the reference documentation linked just above. Generally, you'll be operating at a more granular level than these basic primitives: controlling data in terms of specific resources or components and adding systems to an existing schedule. -To do so, customize your own {{rust_type(type="struct" crate="bevy" mod = "app" name="App" no_mod = "true")}} by chaining its methods with the [builder pattern](https://doc.rust-lang.org/1.0.0/style/ownership/builders.html). +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 {{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. + 1. Initializing resources in the [`World`] to store globally available data that we only need a single copy of. + 2. Adding systems to our [`Schedule`], which can read and modify resources and our entities' components, according to our game logic. + 3. Importing other blocks of [`App`]-modifying code using [`Plugins`]. Let's write a very simple demo that shows how those work. ```rust @@ -68,3 +68,8 @@ fn read_message(message: Res) { println!(message.string); } ``` + +[`App`]: https://docs.rs/bevy/latest/bevy/app/struct.App.html +[`World`]: https://docs.rs/bevy/latest/bevy/ecs/world/struct.World.html +[`Schedule`]: https://docs.rs/bevy/latest/bevy/ecs/schedule/struct.Schedule.html +[`Plugins`]: https://docs.rs/bevy/latest/bevy/app/trait.Plugin.html diff --git a/content/learn/book/welcome/plugins/_index.md b/content/learn/book/welcome/plugins/_index.md index 2f555e480e..cc025a28ce 100644 --- a/content/learn/book/welcome/plugins/_index.md +++ b/content/learn/book/welcome/plugins/_index.md @@ -5,17 +5,17 @@ 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" 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)}}. +One of Bevy's core principles is modularity. In Bevy, all functionality is implemented via [`Plugins`], which are added to an [`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 [`Plugins`]. -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. +This empowers Bevy developers to modularly "build their own engine" using official, third party, and custom [`Plugins`]. Bevy intentionally blurs the lines between engine developers and app developers. ## Writing your own plugins -Plugins are collections of code that modify {{rust_type(type="struct" crate="bevy" mod = "app" name="App" no_mod = "true")}}. -Any code in a plugin could be directly applied to the base {{rust_type(type="struct" crate="bevy" mod = "app" name="App" no_mod = "true")}}. +Plugins are collections of code that modify [`Apps`]. +Any code in a plugin could be directly applied to the base [`App`]. 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: +Plugins are types that implement the [`Plugin`] trait: ```rust use bevy::prelude::*; @@ -57,11 +57,16 @@ fn report_score(score: Res){ } ``` +[`App`]: https://docs.rs/bevy/latest/bevy/app/struct.App.html +[`Apps`]: https://docs.rs/bevy/latest/bevy/app/struct.App.html +[`Plugin`]: https://docs.rs/bevy/latest/bevy/app/trait.Plugin.html +[`Plugins`]: https://docs.rs/bevy/latest/bevy/app/trait.Plugin.html + ## 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. +Bevy's [`DefaultPlugins`] is a [`PluginGroup`] that adds the "core engine features" like rendering, windowing, and sound that most developers want when building an app. -You can add {{rust_type(type="struct" crate="bevy" name="DefaultPlugins")}} to your app like this: +You can add [`DefaultPlugins`] to your app like this: ```rust App::new().add_plugins(DefaultPlugins) @@ -69,11 +74,15 @@ 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 (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. +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 [`MinimalPlugins`] instead. + +[`DefaultPlugins`]: https://docs.rs/bevy/latest/bevy/struct.DefaultPlugins.html +[`PluginGroup`]: https://docs.rs/bevy/latest/bevy/app/trait.PluginGroup.html +[`MinimalPlugins`]: https://docs.rs/bevy/latest/bevy/struct.MinimalPlugins.html ## Third-party plugins -Importing 3rd-party plugins is easy; they're just ordinary Rust code that can be managed with `cargo`. +Importing 3rd-party plugins is easy; they're just ordinary Rust code that can be managed with [`cargo`](https://doc.rust-lang.org/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/)). @@ -87,7 +96,7 @@ If you plan on releasing a plugin yourself, please refer to [Bevy's Plugin Guide ## 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. +Some apps won't need all of the features provided by [`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):