Skip to content

Commit

Permalink
Replace shortcodes in Welcome chapter
Browse files Browse the repository at this point in the history
  • Loading branch information
alice-i-cecile committed Feb 11, 2022
1 parent edbd9f3 commit 09810af
Show file tree
Hide file tree
Showing 2 changed files with 32 additions and 18 deletions.
21 changes: 13 additions & 8 deletions content/learn/book/welcome/apps/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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::*;
Expand All @@ -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
Expand Down Expand Up @@ -68,3 +68,8 @@ fn read_message(message: Res<Message>) {
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
29 changes: 19 additions & 10 deletions content/learn/book/welcome/plugins/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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::*;
Expand Down Expand Up @@ -57,23 +57,32 @@ fn report_score(score: Res<Score>){
}
```

[`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)
```

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/)).
Expand All @@ -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):

Expand Down

0 comments on commit 09810af

Please sign in to comment.