diff --git a/content/learn/book/migration-guides/0.4-0.5/_index.md b/content/learn/book/migration-guides/0.4-0.5/_index.md index 906c613b40..ec0945d984 100644 --- a/content/learn/book/migration-guides/0.4-0.5/_index.md +++ b/content/learn/book/migration-guides/0.4-0.5/_index.md @@ -24,15 +24,17 @@ fn foo(mut commands: Commands) { Systems using the old `commands: &mut Commands` syntax in 0.5 will fail to compile when calling `foo.system()`. -This change was made because {{rust_type(type="struct" crate="bevy_ecs" mod="system" version="0.5.0" name="Commands" no_mod=true)}} -now holds an internal {{rust_type(type="struct" crate="bevy_ecs" mod="world" version="0.5.0" name="World" no_mod=true)}} +This change was made because [`Commands`] now holds an internal [`World`] reference to enable safe entity allocations. -Note: The internal {{rust_type(type="struct" crate="bevy_ecs" mod="world" version="0.5.0" name="World" no_mod=true)}} reference requires two lifetime parameters to pass Commands into a non-system function: `commands: &'a mut Commands<'b>` +Note: The internal [`World`] reference requires two lifetime parameters to pass Commands into a non-system function: `commands: &'a mut Commands<'b>` + +[`Commands`]: https://docs.rs/bevy/0.5.0/bevy/ecs/system/struct.Commands.html +[`World`]: https://docs.rs/bevy/0.5.0/bevy/ecs/world/struct.World.html ### Commands API -The {{rust_type(type="struct" crate="bevy_ecs" version="0.5.0" mod="system" name="Commands" no_mod=true)}} API has been completely reworked for consistency with the {{rust_type(type="struct" crate="bevy_ecs" mod="world" version="0.5.0" name="World" no_mod=true)}} API. +The [`Commands`] API has been completely reworked for consistency with the [`World`] API. ```rust // 0.4 @@ -97,12 +99,15 @@ if timer.tick(time.delta()).finished() { /* do stuff */ } timer.elapsed() // returns a `Duration` ``` -Most of the methods of {{rust_type(type="struct" crate="bevy_core" version="0.5.0" name="Timer" no_mod=true)}} -now use `Duration` instead of `f32`. +Most of the methods of [`Timer`] +now use [`Duration`] instead of `f32`. This change allows timers to have consistent, high precision. For convenience, there is also an `elapsed_secs` method that returns `f32`. Otherwise, when you need an `f32`, use the -`as_secs_f32()` method on `Duration` to make the conversion. +`as_secs_f32()` method on [`Duration`] to make the conversion. + +[`Timer`]: https://docs.rs/bevy/0.5.0/bevy/core/struct.Timer.html +[`Duration`]: https://docs.rs/bevy/0.5.0/bevy/utils/struct.Duration.html ### Simplified Events diff --git a/content/learn/book/migration-guides/0.5-0.6/_index.md b/content/learn/book/migration-guides/0.5-0.6/_index.md index 6096d8bf9b..1746a9e530 100644 --- a/content/learn/book/migration-guides/0.5-0.6/_index.md +++ b/content/learn/book/migration-guides/0.5-0.6/_index.md @@ -29,9 +29,9 @@ members = [ "my_crate1", "my_crate2" ] ### "AppBuilder" was merged into "App" -All functions of {{rust_type(type="struct" crate="bevy_app" mod="" version="0.5.0" name="AppBuilder" no_mod=true)}} were merged into {{rust_type(type="struct" crate="bevy_app" mod="" version="0.6.0" name="App" no_mod=true)}}. +All functions of [`AppBuilder`] were merged into [`App`]. -In practice this means that you start constructing an {{rust_type(type="struct" crate="bevy_app" mod="" version="0.6.0" name="App" no_mod=true)}} by calling {{rust_type(type="struct" crate="bevy_app" mod="" version="0.6.0" name="App" no_mod=true method="new")}} instead of {{rust_type(type="struct" crate="bevy_app" mod="" version="0.5.0" name="App" no_mod=true method="build")}} and {{rust_type(type="trait" crate="bevy_app" mod="" version="0.5.0" name="Plugin" no_mod=true method="build")}} takes a {{rust_type(type="struct" crate="bevy_app" mod="" version="0.6.0" name="App" no_mod=true)}} instead of a {{rust_type(type="struct" crate="bevy_app" mod="" version="0.5.0" name="AppBuilder" no_mod=true)}} +In practice this means that you start constructing an [`App`] by calling [`App::new`] instead of [`App::build`] and [`Plugin::build`] takes a [`App`] instead of a [`AppBuilder`]. ```rs // 0.5 @@ -61,9 +61,15 @@ impl Plugin for SomePlugin { } ``` +[`AppBuilder`]: https://docs.rs/bevy/0.5.0/bevy/app/struct.AppBuilder.html +[`App`]: https://docs.rs/bevy/0.6.0/bevy/app/struct.App.html +[`App::new`]: https://docs.rs/bevy/0.6.0/bevy/app/struct.App.html#method.new +[`App::build`]: https://docs.rs/bevy/0.5.0/bevy/app/struct.App.html#method.build +[`Plugin::build`]: https://docs.rs/bevy/0.6.0/bevy/app/trait.Plugin.html#tymethod.build + ### The "Component" trait now needs to be derived -Bevy no longer has a blanket implementation for the {{rust_type(type="trait" crate="bevy_ecs" mod="component" version="0.6.0" name="Component" no_mod=true)}} trait. +Bevy no longer has a blanket implementation for the [`Component`] trait. Instead you need to derive (or manualy implement) the trait for every Type that needs it. ```rust @@ -82,9 +88,11 @@ In order to use foreign types as components, wrap them using the newtype pattern struct Cooldown(std::time::Duration); ``` +[`Component`]: https://docs.rs/bevy/0.6.0/bevy/ecs/component/trait.Component.html + ### Setting the Component Storage is now done in "Component" Trait -The change to deriving {{rust_type(type="trait" crate="bevy_ecs" mod="component" version="0.6.0" name="Component" no_mod=true)}}, enabled setting the Component Storage at compiletime instead of runtime. +The change to deriving [`Component`], enabled setting the Component Storage at compiletime instead of runtime. ```rust // 0.5 @@ -145,9 +153,9 @@ fn main() { ### ".single()" and ".single_mut()" are now infallible -The functions {{rust_type(type="struct" crate="bevy_ecs" mod="system" version="0.6.0" name="Query" no_mod=true method="single")}} and {{rust_type(type="struct" crate="bevy_ecs" mod="system" version="0.6.0" name="Query" no_mod=true method="single_mut")}} no longer return a {{rust_type(type="enum", crate="std" mod="result", name="Result", no_mod=true)}} and Panic instead, if not exactly one Entity was found. +The functions [`Query::single()`] and [`Query::single_mut()`] no longer return a `Result` and instead panic unless exactly one entity was found. -If you need the old behavior you can use the fallible {{rust_type(type="struct" crate="bevy_ecs" mod="system" version="0.6.0" name="Query" no_mod=true method="get_single")}} and {{rust_type(type="struct" crate="bevy_ecs" mod="system" version="0.6.0" name="Query" no_mod=true method="get_single_mut")}} instead. +If you need the old behavior you can use the fallible [`Query::get_single()`] and [`Query_get_single_mut()`] instead. ```rs // 0.5 @@ -168,6 +176,11 @@ fn player_system_fallible(query: Query<&Transform, With>) { } ``` +[`Query::single()`]: https://docs.rs/bevy/0.6.0/bevy/ecs/system/struct.Query.html#method.single +[`Query::single_mut()`]: https://docs.rs/bevy/0.6.0/bevy/ecs/system/struct.Query.html#method.single_mut +[`Query::get_single`]: https://docs.rs/bevy/0.6.0/bevy/ecs/system/struct.Query.html#method.get_single +[`Query_get_single_mut`]: https://docs.rs/bevy/0.6.0/bevy/ecs/system/struct.Query.html#method.get_single_mut + ### "Light" and "LightBundle" are now "PointLight" and "PointLightBundle" ```rust @@ -194,18 +207,17 @@ commands.spawn_bundle(PointLightBundle { }); ``` -The {{rust_type(type="struct" crate="bevy_pbr" mod="" version="0.5.0" name="Light" no_mod=true)}} and {{rust_type(type="struct" crate="bevy_pbr" mod="" version="0.5.0" name="LightBundle" no_mod=true)}} were renamed to {{rust_type(type="struct" crate="bevy_pbr" mod="" version="0.6.0" name="PointLight" no_mod=true)}} and {{rust_type(type="struct" crate="bevy_pbr" mod="" version="0.6.0" name="PointLightBundle" no_mod=true)}} to more clearly communicate the behavior of the Light Source. -At the same time the `fov` and `depth` fields were removed from the {{rust_type(type="struct" crate="bevy_pbr" mod="" version="0.6.0" name="PointLight" no_mod=true)}} as they were unused. - - +[`Light`]: https://docs.rs/bevy/0.5.0/bevy/pbr/struct.Light.html +[`LightBundle`]: https://docs.rs/bevy/0.5.0/bevy/pbr/struct.LightBundle.html +[`PointLight`]: https://docs.rs/bevy/0.6.0/bevy/pbr/struct.PointLight.html +[`PointLightBundle`]: https://docs.rs/bevy/0.6.0/bevy/pbr/struct.PointLightBundle.html ### System Param Lifetime Split -The Lifetime of {{rust_type(type="trait" crate="bevy_ecs" mod="system" version="0.5.0" name="SystemParam" no_mod=true)}} was split in two separate Lifetimes. +The Lifetime of [`SystemParam`] was split in two separate Lifetimes. ```rust // 0.5 @@ -229,11 +241,11 @@ struct SystemParamDerive<'w, 's> { } ``` -### QuerySet declare "QueryState" instead of "Query" +[`SystemParam`]: https://docs.rs/bevy/0.6.0/bevy/ecs/system/trait.SystemParam.html - +### QuerySet declare "QueryState" instead of "Query" -Due to the [System Param Lifetime Split](#system-param-lifetime-split), {{rust_type(type="struct" crate="bevy_ecs" mod="system" name="QuerySet" version="0.6.0" no_mod=true plural=true)}} now need to specify their Queries with {{rust_type(type="struct" crate="bevy_ecs" mod="query" version="0.6.0" name="QueryState" no_mod=true)}} instead of {{rust_type(type="struct" crate="bevy_ecs" mod="system" version="0.6.0" name="Query" no_mod=true)}}. +Due to the [System Param Lifetime Split](#system-param-lifetime-split), [`QuerySet`] system parameters now need to specify their Queries with [`QuerySet`] instead of [`Query`]. ```rust // 0.5 @@ -247,21 +259,31 @@ fn query_set(mut queries: QuerySet<(QueryState<&mut Transform>, QueryState<&Tran } ``` +[`QuerySet`]: https://docs.rs/bevy/0.6.0/bevy/ecs/system/struct.QuerySet.html +[`QueryState`]: https://docs.rs/bevy/0.6.0/bevy/ecs/query/struct.QueryState.html +[`Query`]: https://docs.rs/bevy/0.6.0/bevy/ecs/system/struct.Query.html + ### "Input\.update()" is renamed to "Input\.clear()" -The {{rust_type(type="struct" crate="bevy_input" mod="" version="0.5.0" name="Input" no_mod=true method="update")}} function was renamed to {{rust_type(type="struct" crate="bevy_input" mod="" version="0.6.0" name="Input" no_mod=true method="clear")}}. +The [`Input::update`] function was renamed to [`Input::clear`]. + +[`Input::update`]: https://docs.rs/bevy/0.5.0/bevy/input/struct.Input.html#method.update +[`Input::clear`]: https://docs.rs/bevy/0.6.0/bevy/input/struct.Input.html#method.clear ### "SystemState" is now "SystemMeta" -The {{rust_type(type="struct" crate="bevy_ecs" mod="system" version="0.5.0" name="SystemState" no_mod=true)}} struct, which stores the metadata of a System, was renamed to {{rust_type(type="struct" crate="bevy_ecs" mod="system" version="0.6.0" name="SystemMeta" no_mod=true)}}. +The struct formerly known as [`SystemState`](https://docs.rs/bevy/0.5.0/bevy/ecs/system/struct.SystemState.html), which stores the metadata of a System, was renamed to [`SystemMeta`]. -This was done to accommodate the new {{rust_type(type="struct" crate="bevy_ecs" mod="system" version="0.6.0" name="SystemState" no_mod=true)}} which allows easier cached access to {{rust_type(type="trait" crate="bevy_ecs" mod="system" version="0.6.0" name="SystemParam" no_mod=true plural=true)}} outside of a regular System. +This was done to accommodate the new [`SystemState`] which allows easier cached access to [`SystemParam`] outside of a regular System. + +[`SystemState`]: https://docs.rs/bevy/0.6.0/bevy/ecs/system/struct.SystemState.html +[`SystemMeta`]: https://docs.rs/bevy/0.6.0/bevy/ecs/system/struct.SystemMeta.html ### Vector casting functions are now named to match return type -The casting functions for {{rust_type(type="struct" crate="bevy" mod="math" version="0.6.0" name="IVec2" no_mod=true)}}, {{rust_type(type="struct" crate="bevy" mod="math" version="0.6.0" name="DVec2" no_mod=true)}}, {{rust_type(type="struct" crate="bevy" mod="math" version="0.6.0" name="UVec2" no_mod=true)}}, {{rust_type(type="struct" crate="bevy" mod="math" version="0.6.0" name="Vec2" no_mod=true)}} have all been changed from being named after their inner elements' cast target to what the entire "Vec" is being casted into. This affects all the different dimensions of the math vectors (i.e., {{rust_type(type="struct" crate="bevy" mod="math" version="0.6.0" name="Vec2" no_mod=true)}}, {{rust_type(type="struct" crate="bevy" mod="math" version="0.6.0" name="Vec3" no_mod=true)}} and {{rust_type(type="struct" crate="bevy" mod="math" version="0.6.0" name="Vec4" no_mod=true)}}). +The casting functions for [`IVec2`], [`DVec2`], [`UVec2`], and [`Vec2`] have all been changed from being named after their inner elements' cast target to what the entire "Vec" is being casted into. This affects all the different dimensions of the math vectors (i.e., [`Vec2`], [`Vec3` ]and [`Vec4`]). ```rust // 0.5 @@ -273,13 +295,22 @@ let xyz: Vec3 = Vec3::new(0.0, 0.0, 0.0); let xyz: IVec3 = xyz.as_ivec3(); ``` + [`IVec2`]: https://docs.rs/bevy/0.6.0/bevy/math/struct.IVec2.html + [`DVec2`]: https://docs.rs/bevy/0.6.0/bevy/math/struct.DVec2.html + [`UVec2`]: https://docs.rs/bevy/0.6.0/bevy/math/struct.UVec2.html + [`Vec2`]: https://docs.rs/bevy/0.6.0/bevy/math/struct.Vec2.html + [`Vec3`]: https://docs.rs/bevy/0.6.0/bevy/math/struct.Vec3.html + [`Vec4`]: https://docs.rs/bevy/0.6.0/bevy/math/struct.Vec4.html + ### StandardMaterial's "roughness" is renamed to "perceptual_roughness" -The {{rust_type(type="struct" crate="bevy_pbr" mod="" version="0.6.0" name="StandardMaterial" no_mod=true)}} field `roughness` was renamed to `perceptual_roughness`. +The [`StandardMaterial`] field `roughness` was renamed to `perceptual_roughness`. + +[`StandardMaterial`]: https://docs.rs/bevy/0.6.0/bevy/pbr/struct.StandardMaterial.html ### SpriteBundle and Sprite -The {{rust_type(type="struct" crate="bevy_sprite" mod="" version="0.6.0" name="SpriteBundle" no_mod=true)}} now uses a `texture` handle rather than a `material`. The `color` field of the material is now directly available inside of the {{rust_type(type="struct" crate="bevy_sprite" mod="" version="0.6.0" name="Sprite" no_mod=true)}} struct, which also had its `resize_mode` field replaced with a `custom_size`. The following example shows how to spawn a tinted sprite at a particular size. For simpler cases, check out the updated [sprite](https://github.com/bevyengine/bevy/blob/v0.6.0/examples/2d/sprite.rs) and [rect](https://github.com/bevyengine/bevy/blob/v0.6.0/examples/2d/rect.rs) examples. +The [`SpriteBundle`] bundle type now uses a `texture` handle rather than a `material`. The `color` field of the material is now directly available inside of the [`Sprite`] struct, which also had its `resize_mode` field replaced with a `custom_size`. The following example shows how to spawn a tinted sprite at a particular size. For simpler cases, check out the updated [sprite](https://github.com/bevyengine/bevy/blob/v0.6.0/examples/2d/sprite.rs) and [rect](https://github.com/bevyengine/bevy/blob/v0.6.0/examples/2d/rect.rs) examples. ```rust // 0.5 @@ -308,8 +339,11 @@ SpriteBundle { } ``` +[`SpriteBundle`]: https://docs.rs/bevy/0.6.0/bevy/sprite/struct.SpriteBundle.html +[`Sprite`]: https://docs.rs/bevy/0.6.0/bevy/sprite/struct.Sprite.html + ### Visible is now Visibility -The {{rust_type(type="struct" crate="bevy" mod="render::draw" version="0.5.0" name="Visible" no_mod=true)}} struct, which is used in a number of components to set visibility, was renamed to {{rust_type(type="struct" crate="bevy" mod="render::view" version="0.6.0" name="Visibility" no_mod=true)}}. Additionally, the field `is_transparent` was removed from the struct. For 3D, transparency can be set using the `alpha_mode` field on a material. Transparency is now automatically enabled for all objects in 2D. +The [`Visible`] struct, which is used in a number of components to set visibility, was renamed to [`Visibility`]. Additionally, the field `is_transparent` was removed from the struct. For 3D, transparency can be set using the `alpha_mode` field on a material. Transparency is now automatically enabled for all objects in 2D. ```rust // 0.5 @@ -342,3 +376,6 @@ commands.spawn_bundle(PbrBundle { ..Default::default() }); ``` + +[`Visible`]: https://docs.rs/bevy/0.5.0/bevy/prelude/struct.Visible.html +[`Visibility`]: https://docs.rs/bevy/0.6.0/bevy/prelude/struct.Visibility.html# \ No newline at end of file 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): diff --git a/content/news/2020-08-10-introducing-bevy/index.md b/content/news/2020-08-10-introducing-bevy/index.md index fc0dfb2aaf..db645e52a6 100644 --- a/content/news/2020-08-10-introducing-bevy/index.md +++ b/content/news/2020-08-10-introducing-bevy/index.md @@ -52,10 +52,11 @@ That being said, Bevy is still in the very early stages. I consider it to be in Hopefully at this point you are either (1) jazzed about Bevy or (2) not reading anymore. If you want to dive in right now, [The Bevy Book](https://bevyengine.org/learn/book/introduction/) is the best place to get started. You can also keep reading to find out what the current state of Bevy is and where we'd like to take it. -**Quick note to the reader**: in this article you will find text formatted like this: {{rust_type(type="struct" crate="bevy_render" version="0.1.0" mod="texture" name="Texture" no_mod=true)}} +**Quick note to the reader**: in this article you will find text formatted like this: [`Texture`] This formatting indicates that the text is a Rust type that links to API documentation. I encourage you to click on anything that seems interesting to you! - + +[`Texture`]: https://docs.rs/bevy/0.1.0/bevy/prelude/struct.Texture.html ## Bevy Apps @@ -79,9 +80,9 @@ fn main() { } ``` -{{rust_type(type="trait", crate="bevy" version="0.1.0" name="AddDefaultPlugins" method="add_default_plugins" no_mod=true no_struct=true)}} adds all of the features you probably expect from a game engine: a 2D / 3D renderer, asset loading, a UI system, windows, input, etc +[`AddDefaultPlugins::add_default_plugins`] adds all of the features you probably expect from a game engine: a 2D / 3D renderer, asset loading, a UI system, windows, input, etc -You can also register the default {{rust_type(type="trait" name="Plugin" crate="bevy_app" version="0.1.0" plural=true)}} manually like this: +You can also register the default [`Plugins`] manually like this: ```rs fn main() { @@ -96,7 +97,11 @@ fn main() { } ``` -And of course you can also create your own plugins. In fact, all engine and game logic is built using plugins. Hopefully now you understand what we mean by modular: you are free to add/remove plugins based on your project's unique needs. However I expect that most people will stick to {{rust_type(type="trait" crate="bevy" version="0.1.0" name="AddDefaultPlugins" method="add_default_plugins" no_mod=true no_struct=true)}} for simplicity, at least initially. +And of course you can also create your own plugins. In fact, all engine and game logic is built using plugins. Hopefully now you understand what we mean by modular: you are free to add/remove plugins based on your project's unique needs. However I expect that most people will stick to +[`AddDefaultPlugins::add_default_plugins`] for simplicity, at least initially. + +[`AddDefaultPlugins::add_default_plugins`]: https://docs.rs/bevy/0.1.0/bevy/trait.AddDefaultPlugins.html#tymethod.add_default_plugins +[`Plugins`]: https://docs.rs/bevy/0.1.0/bevy/prelude/trait.Plugin.html ## Bevy ECS @@ -336,12 +341,13 @@ fn main() { } ``` -The `.system()` call takes the `some_system` function pointer and converts it to a `Box`. This works because we implement the {{rust_type(type="trait" crate="bevy_ecs" version="0.1.0" name="IntoQuerySystem")}} trait for all functions that match a certain set of function signatures. +The `.system()` call takes the `some_system` function pointer and converts it to a `Box`. This works because we implement the [`IntoQuerySystem`] trait for all functions that match a certain set of function signatures. +[`IntoQuerySystem`]: https://docs.rs/bevy/0.1.0/bevy/prelude/trait.IntoQuerySystem.html ### Good Bones -Bevy ECS actually uses a heavily forked version of the minimalist [Hecs ECS](https://github.com/Ralith/hecs). Hecs is an efficient single-threaded archetypal ECS. It provides the core {{rust_type(type="struct" crate="bevy_ecs" version="0.1.0" name="World")}}, {{rust_type(type="struct" crate="bevy_ecs" version="0.1.0" name="Archetype")}}, and internal {{rust_type(type="trait" crate="bevy_ecs" version="0.1.0" name="Query")}} data structures. Bevy ECS adds the following on top: +Bevy ECS actually uses a heavily forked version of the minimalist [Hecs ECS](https://github.com/Ralith/hecs). Hecs is an efficient single-threaded archetypal ECS. It provides the core [`World`], [`Archetype`], and internal [`Query`] data structures. Bevy ECS adds the following on top: * Function Systems: Hecs actually has no concept of a "system" at all. You just run queries directly on the World. Bevy adds the ability to define portable, schedulable systems using normal Rust functions. * Resources: Hecs has no concept of unique/global data. When building games, this is often needed. Bevy adds a `Resource` collection and resource queries @@ -353,6 +359,10 @@ Bevy ECS actually uses a heavily forked version of the minimalist [Hecs ECS](htt In the near future I will file an issue on the Hecs git repo offering to upstream whatever changes they want from Bevy ECS. I have a feeling they won't want the "high level" stuff like function systems and parallel scheduling, but I guess we'll see! +[`World`]: https://docs.rs/bevy/0.1.0/bevy/prelude/struct.World.html +[`Archetype`]: https://docs.rs/bevy/0.1.0/bevy/prelude/struct.World.html#method.archetypes +[`Query`]: https://docs.rs/bevy/0.1.0/bevy/prelude/struct.Query.html + ## Bevy UI ![bevy ui](bevy_ui.png) @@ -367,7 +377,7 @@ We are still in the experimental stages and I expect some things to change, but ### Building Blocks -In Bevy, a UI element is just an ECS Entity with a {{rust_type(type="struct" name="Node" crate="bevy_ui" version="0.1.0")}} component. Nodes are rectangles with a width and height, and are positioned using the same {{rust_type(type="struct" name="Transform" crate="bevy_transform" version="0.1.0" mod="components" no_mod=true)}} component used elsewhere in Bevy. The {{rust_type(type="struct" name="Style" crate="bevy_ui" version="0.1.0" no_mod=true)}} component is used to determine how the Node is rendered, sized, and positioned. +In Bevy, a UI element is just an ECS Entity with a [`Node`] component. Nodes are rectangles with a width and height, and are positioned using the same [`Transform`] component used elsewhere in Bevy. The [`Style`] component is used to determine how the Node is rendered, sized, and positioned. The easiest way to add a new node (with all of the required components) is like this: @@ -375,11 +385,16 @@ The easiest way to add a new node (with all of the required components) is like commands.spawn(NodeComponents::default()) ``` -{{rust_type(type="struct" name="NodeComponents" crate="bevy_ui" version="0.1.0" mod="entity" no_mod=true)}} is a "component bundle", which Bevy uses to make spawning entities of various "types" easier. +[`NodeComponents`] is a "component bundle", which Bevy uses to make spawning entities of various "types" easier. + +[`Node`]: https://docs.rs/bevy/0.1.0/bevy/prelude/struct.Node.html +[`Style`]: https://docs.rs/bevy/0.1.0/bevy/prelude/struct.Style.html +[`Transform`]: https://docs.rs/bevy/0.1.0/bevy/prelude/struct.Transform.html +[`NodeComponents`]: https://docs.rs/bevy/0.1.0/bevy/prelude/struct.NodeComponents.html ### Layout -For layout, Bevy uses a fantastic 100% Rust flexbox implementation called [Stretch](https://github.com/vislyhq/stretch). Stretch provides the algorithms for positioning rectangles in 2D space according to the flexbox spec. Bevy exposes flex properties inside the {{rust_type(type="struct" name="Style" version="0.1.0" crate="bevy_ui")}} component mentioned above and renders rectangles with the positions and sizes that Stretch outputs. Bevy uses its own z-layering algorithm to "stack" elements on top of each other, but its basically the same one that HTML/CSS uses. +For layout, Bevy uses a fantastic 100% Rust flexbox implementation called [Stretch](https://github.com/vislyhq/stretch). Stretch provides the algorithms for positioning rectangles in 2D space according to the flexbox spec. Bevy exposes flex properties inside the [`Style`] component mentioned above and renders rectangles with the positions and sizes that Stretch outputs. Bevy uses its own z-layering algorithm to "stack" elements on top of each other, but its basically the same one that HTML/CSS uses. ### Relative Positioning @@ -541,7 +556,7 @@ commands ### Interaction Events -Nodes with the {{rust_type(type="enum" name="Interaction" crate="bevy_ui" version="0.1.0")}} component will track interaction state. You can easily build widgets like buttons this way: +Nodes with the [`Interaction`] component will track interaction state. You can easily build widgets like buttons this way: @@ -557,11 +572,13 @@ fn system(_button: &Button, interaction: Mutated) { } ``` +[`Interaction`]: https://docs.rs/bevy/0.1.0/bevy/prelude/enum.Interaction.html + ## 2D Features ### [Sprites](https://github.com/bevyengine/bevy/blob/1d68094f59b01e14f44ed7db8907dbd011b59973/examples/2d/sprite.rs) -You can use any {{rust_type(type="struct" name="Texture" crate="bevy_render" version="0.1.0" mod="texture" no_mod=true)}} asset as a sprite directly: +You can use any [`Texture`] asset as a sprite directly: ![sprite](sprite.png) @@ -573,6 +590,8 @@ commands.spawn(SpriteComponents { }); ``` +[`Texture`]: https://docs.rs/bevy/0.1.0/bevy/prelude/struct.Texture.html + ### [Sprite Sheets](https://github.com/bevyengine/bevy/blob/1d68094f59b01e14f44ed7db8907dbd011b59973/examples/2d/sprite_sheet.rs) Sprite sheets (also known as texture atlases) can be used for animations, tile sets, or just for optimized sprite rendering. @@ -663,7 +682,7 @@ app.add_resource(Msaa { samples: 8 }) ## Scenes -Scenes are a way to compose pieces of your game/app ahead of time. In Bevy, Scenes are simply a collection of entities and components. A Scene can be "spawned" into a `World` any number of times. "Spawning" copies the Scene's entities and components into the given `World`. +Scenes are a way to compose pieces of your game/app ahead of time. In Bevy, Scenes are simply a collection of entities and components. A Scene can be "spawned" into a [`World`] any number of times. "Spawning" copies the Scene's entities and components into the given [`World`]. Scenes can also be saved to and loaded from "scene files". One of the primary goals of the future "Bevy Editor" will be to make it easy to compose scene files visually. @@ -702,7 +721,7 @@ The numbers assigned to the `entity` fields are entity's id, which are completel ### Loading and Instancing -Scenes can be added to a `World` using the {{rust_type(type="struct" name="SceneSpawner" crate="bevy_scene" version="0.1.0" no_mod=true)}} resource. Spawning can be done with either {{rust_type(type="struct" name="SceneSpawner" method="load" crate="bevy_scene" version="0.1.0" no_mod=true)}} or {{rust_type(type="struct" name="SceneSpawner" method="instance" crate="bevy_scene" version="0.1.0" no_mod=true)}}. "Loading" a Scene preserves the entity IDs in it. This is useful for something like a save file where you want entity ids to be constant and changes to be applied on top of entities already in the world. "Instancing" adds entities to the `World` with brand-new IDs, which allows multiple "instances" of a scene to exist in the same World. +Scenes can be added to a [`World`] using the [`SceneSpawner`] resource. Spawning can be done with either [`SceneSpawner::load`] or [`SceneSpawner::instance`]. "Loading" a Scene preserves the entity IDs in it. This is useful for something like a save file where you want entity ids to be constant and changes to be applied on top of entities already in the world. "Instancing" adds entities to the [`World`] with brand-new IDs, which allows multiple "instances" of a scene to exist in the same [`World`]. ```rs fn load_scene_system(asset_server: Res, mut scene_spawner: ResMut) { @@ -715,9 +734,13 @@ fn load_scene_system(asset_server: Res, mut scene_spawner: ResMut, my_events: Res>) { } ``` -`app.add_event::()` adds a new {{rust_type(type="struct", crate="bevy_app" version="0.1.0" name="Events")}} resource for MyEvent and a system that swaps the ```Events``` buffers every update. {{rust_type(type="struct" crate="bevy_app" version="0.1.0" name="EventReader" plural=true)}} are very cheap to create. They are essentially just an array index that tracks the last event that has been read. +`app.add_event::()` adds a new [`Events`] resource for MyEvent and a system that swaps the ```Events``` buffers every update. [`EventReaders`] are very cheap to create. They are essentially just an array index that tracks the last event that has been read. Events are used in Bevy for features like window resizing, assets, and input. The tradeoff for being both allocation and cpu efficient is that each system only has one chance to receive an event, otherwise it will be lost on the next update. I believe this is the correct tradeoff for apps that run in a loop (ex: games). +[`Events`]: https://docs.rs/bevy/0.1.0/bevy/prelude/struct.Events.html +[`EventReaders`]: https://docs.rs/bevy/0.1.0/bevy/prelude/struct.EventReader.html + ## Assets -Bevy {{rust_type(type="struct" crate="bevy_asset" version="0.1.0" name="Assets")}} are just typed data that can be referenced using asset {{rust_type(type="struct" crate="bevy_asset" version="0.1.0" name="Handle" plural=true)}} . For example, 3d meshes, textures, fonts, materials, scenes, and sounds are assets. `Assets` is a generic collection of assets of type `T`. In general asset usage looks like this: +Bevy [`Assets`] are just typed data that can be referenced using asset [`Handles`]. For example, 3d meshes, textures, fonts, materials, scenes, and sounds are assets. `Assets` is a generic collection of assets of type `T`. In general asset usage looks like this: + +[`Assets`]: https://docs.rs/bevy/0.1.0/bevy/prelude/struct.Assets.html +[`Handles`]: https://docs.rs/bevy/0.1.0/bevy/prelude/struct.Handle.html #### Asset Creation ```rs @@ -842,7 +871,7 @@ fn read_texture_system(textures: Res>, texture_handle: &Handle` collection is basically just a map from `Handle` to `T` that records created, modified, and removed `Events`. These events can also be consumed as a system resource, just like any other `Events`: +The `Assets` collection is basically just a map from `Handle` to `T` that records created, modified, and removed [`Events`]. These events can also be consumed as a system resource, just like any other [`Events`]: ```rs fn system(mut state: Local, texture_events: Res>) { for event in state.reader.iter(&texture_events) { @@ -855,7 +884,7 @@ fn system(mut state: Local, texture_events: Res>) { #### Asset Server -The ```Assets``` collection doesn't know anything about filesystems or multi-threading. This is the responsibility of the {{rust_type(type="struct" crate="bevy_asset" version="0.1.0" name="AssetServer" no_mod=true)}} resource: +The ```Assets``` collection doesn't know anything about filesystems or multi-threading. This is the responsibility of the [`AssetServer`] resource: ```rs fn system(mut commands: Commands, asset_server: Res, mut textures: ResMut>) { @@ -884,6 +913,8 @@ fn system(mut commands: Commands, asset_server: Res, mut textures: } ``` +[`AssetServer`]: https://docs.rs/bevy/0.1.0/bevy/prelude/struct.AssetServer.html + #### Hot Reloading You can enable asset change detection by calling: @@ -895,7 +926,7 @@ This will load new versions of assets whenever their files have changed. #### Adding New Asset Types -To add a new asset type, implement the {{rust_type(type="trait" crate="bevy_asset" version="0.1.0" name="AssetLoader" no_mod=true)}} trait. This tells Bevy what file formats to look for and how to translate the file bytes into the given asset type. +To add a new asset type, implement the [`AssetLoader`] trait. This tells Bevy what file formats to look for and how to translate the file bytes into the given asset type. Once you have implemented `AssetLoader` for `MyAssetLoader` you can register your new loader like this: ```rs @@ -904,6 +935,8 @@ app.add_asset_loader::(); Then you can access the `Assets` resource, listen for change events, and call `asset_server.load("something.my_asset")` +[`AssetLoader`]: https://docs.rs/bevy_asset/0.1.0/bevy_asset/trait.AssetLoader.html + ## Sound You can currently load and play sounds like this: @@ -924,15 +957,15 @@ We plan on extending the audio system with more control and features in the futu ## Render Graph -All render logic is built on top of Bevy's {{rust_type(type="struct" crate="bevy_render" version="0.1.0" mod="render_graph" name="RenderGraph" no_mod=true)}}. The Render Graph is a way to encode atomic units of render logic. For example, you might create graph nodes for a 2D pass, UI pass, cameras, texture copies, swap chains, etc. Connecting a node to another node indicates that there is a dependency of some kind between them. By encoding render logic this way, the Bevy renderer is able to analyze dependencies and render the graph in parallel. It also has the benefit of encouraging developers to write modular render logic. +All render logic is built on top of Bevy's [`RenderGraph`]. The Render Graph is a way to encode atomic units of render logic. For example, you might create graph nodes for a 2D pass, UI pass, cameras, texture copies, swap chains, etc. Connecting a node to another node indicates that there is a dependency of some kind between them. By encoding render logic this way, the Bevy renderer is able to analyze dependencies and render the graph in parallel. It also has the benefit of encouraging developers to write modular render logic. Bevy includes a number of nodes by default: `CameraNode`, `PassNode`, `RenderResourcesNode`, `SharedBuffersNode`, `TextureCopyNode`, `WindowSwapChainNode`, and `WindowTextureNode`. It also provides subgraphs for 2d rendering, 3d rendering, and UI rendering. But you are welcome to create your own nodes, your own graphs, or extend the included graphs! ### [Data Driven Shaders](https://github.com/bevyengine/bevy/blob/1d68094f59b01e14f44ed7db8907dbd011b59973/examples/shader/shader_custom_material.rs) -Components and Assets can derive the {{rust_type(type="trait" crate="bevy_render" version="0.1.0" mod="renderer" name="RenderResources" no_mod=true)}} trait, which enables them to be directly copied to GPU resources and used as shader uniforms. +Components and Assets can derive the [`RenderResources`] trait, which enables them to be directly copied to GPU resources and used as shader uniforms. -Binding uniforms to a custom shader is literally as simple as deriving `RenderResources` on your component or asset: +Binding uniforms to a custom shader is literally as simple as deriving [`RenderResources`] on your component or asset: ```rs #[derive(RenderResources, Default)] @@ -960,6 +993,9 @@ layout(set = 1, binding = 1) uniform MyMaterial_color { I think the simplicity of the [fully self-contained custom shader example](https://github.com/bevyengine/bevy/blob/1d68094f59b01e14f44ed7db8907dbd011b59973/examples/shader/shader_custom_material.rs) speaks for itself. +[`RenderGraph`]: https://docs.rs/bevy_render/0.1.0/bevy_render/render_graph/struct.RenderGraph.html +[`RenderResources`]: https://docs.rs/bevy_render/0.1.0/bevy_render/renderer/trait.RenderResources.html + ### [Shader Defs](https://github.com/bevyengine/bevy/blob/1d68094f59b01e14f44ed7db8907dbd011b59973/examples/shader/shader_defs.rs) Components and Assets can also add "shader defs" to selectively enable shader code on a per-entity basis: diff --git a/content/news/2020-12-19-bevy-0.4/index.md b/content/news/2020-12-19-bevy-0.4/index.md index 868301f737..83f0b22308 100644 --- a/content/news/2020-12-19-bevy-0.4/index.md +++ b/content/news/2020-12-19-bevy-0.4/index.md @@ -165,7 +165,7 @@ fn error_handler_system(In(result): In>, error_handler: Res @@ -176,6 +176,8 @@ System We use this feature in our new Schedule implementation. +[`System`]: https://docs.rs/bevy/0.4.0/bevy/prelude/trait.System.html + ### Schedule V2 Bevy's old Schedule was nice. System registrations were easy to read and easy to compose. But it also had significant limitations: @@ -196,7 +198,7 @@ app.add_system(my_system.system()) #### Stage Trait -Stages are now a trait. You can now implement your own {{rust_type(type="trait" crate="bevy_ecs" version="0.4.0" name="Stage" no_mod=true)}} types! +Stages are now a trait. You can now implement your own [`Stage`] types! ```rust struct MyStage; @@ -209,7 +211,9 @@ impl Stage for MyStage { } ``` -#### Stage Type: {{rust_type(type="struct" crate="bevy_ecs" version="0.4.0" name="SystemStage" no_mod=true)}} +[`Stage`]: https://docs.rs/bevy/0.4.0/bevy/ecs/trait.Stage.html + +#### Stage Type: [`SystemStage`] This is basically a "normal" stage. You can add systems to it and you can decide how those systems will be executed (parallel, serial, or custom logic) @@ -233,9 +237,11 @@ let custom_executor_stage = .with_system(b.system()); ``` -#### Stage Type: {{rust_type(type="struct" crate="bevy_ecs" version="0.4.0" name="Schedule" no_mod=true)}} +[`SystemStage`]: https://docs.rs/bevy/0.4.0/bevy/ecs/struct.SystemStage.html -You read that right! {{rust_type(type="struct" crate="bevy_ecs" version="0.4.0" name="Schedule" no_mod=true)}} now implements the {{rust_type(type="trait" crate="bevy_ecs" version="0.4.0" name="Stage" no_mod=true)}} trait, which means you can nest Schedules within other schedules: +#### Stage Type: [`Schedule`] + +You read that right! [`Schedule`] now implements the [`Stage`] trait, which means you can nest Schedules within other schedules: ```rust let schedule = Schedule::default() @@ -250,9 +256,11 @@ let schedule = Schedule::default() ); ``` +[`Schedule`](https://docs.rs/bevy/0.4.0/bevy/ecs/struct.Schedule.html) + #### Run Criteria -You can add "run criteria" to any {{rust_type(type="struct" crate="bevy_ecs" version="0.4.0" name="SystemStage" no_mod=true)}} or {{rust_type(type="struct" crate="bevy_ecs" version="0.4.0" name="Schedule" no_mod=true)}}. +You can add "run criteria" to any [`SystemStage`] or [`Schedule`]. ```rust // A "run criteria" is just a system that returns a `ShouldRun` result @@ -277,6 +285,8 @@ app ) ``` +[`SystemStage`]: https://docs.rs/bevy/0.4.0/bevy/ecs/struct.SystemStage.html + #### Fixed Timestep You can now run stages on a "fixed timestep". @@ -296,7 +306,7 @@ Check out the excellent ["Fix Your Timestep!"](https://gafferongames.com/post/fi #### Typed Stage Builders -Now that stages can be any type, we need a way for {{rust_type(type="trait" crate="bevy_app" version="0.4.0" name="Plugin" no_mod=true plural=true)}} to interact with arbitrary stage types: +Now that stages can be any type, we need a way for [`Plugin`] to interact with arbitrary stage types: ```rust app @@ -312,6 +322,8 @@ app ) ``` +[`Plugin`]: https://docs.rs/bevy/0.4.0/bevy/app/trait.Plugin.html + ### Deprecated For-Each Systems Prior versions of Bevy supported "for-each" systems, which looked like this: @@ -368,7 +380,7 @@ You then add them to your app as a resource like this: app.add_resource(State::new(AppState::Loading)) ``` -To run systems according to the current state, add a {{rust_type(type="struct" crate="bevy_ecs" version="0.4.0" name="StateStage" no_mod=true)}}: +To run systems according to the current state, add a [`StateStage`]: ```rust app.add_stage_after(stage::UPDATE, STAGE, StateStage::::default()) @@ -399,7 +411,9 @@ fn system(mut state: ResMut>) { } ``` -Queued state changes get applied at the end of the StateStage. If you change state within a StateStage, the lifecycle events will occur in the same update/frame. You can do this any number of times (aka it will continue running state lifecycle systems until no more changes are queued). This ensures that multiple state changes can be applied within the same frame. +Queued state changes get applied at the end of the [`StateStage`]. If you change state within a [`StateStage`], the lifecycle events will occur in the same update/frame. You can do this any number of times (aka it will continue running state lifecycle systems until no more changes are queued). This ensures that multiple state changes can be applied within the same frame. + +[`StateStage`]: https://docs.rs/bevy/0.4.0/bevy/ecs/struct.StateStage.html ## GLTF Improvements @@ -527,15 +541,15 @@ Bevy now uses wgpu's "mailbox vsync" by default. This reduces input latency on p Rust has a pretty big "reflection" gap. For those who aren't aware, "reflection" is a class of language feature that enables you to interact with language constructs at runtime. They add a form of "dynamic-ness" to what are traditionally static language concepts. -We have bits and pieces of reflection in Rust, such as {{rust_type(type="struct" crate="std", mod="any", name="TypeId")}} and {{rust_type(type="fn" crate="std", mod="any", name="type_name")}}. But when it comes to interacting with datatypes ... we don't have anything yet. This is unfortunate because some problems are inherently dynamic in nature. +We have bits and pieces of reflection in Rust, such as [`TypeId`] and [`type_name`]. But when it comes to interacting with datatypes ... we don't have anything yet. This is unfortunate because some problems are inherently dynamic in nature. When I was first building Bevy, I decided that the engine would benefit from such features. Reflection is a good foundation for scene systems, Godot-like (or Unity-like) property animation systems, and editor inspection tools. I built the `bevy_property` and `bevy_type_registry` crates to fill these needs. They got the job done, but they were custom-tailored to Bevy's needs, were full of custom jargon (rather than reflecting Rust language constructs directly), didn't handle traits, and had a number of fundamental restrictions on how data could be accessed. -In this release we replaced the old `bevy_property` and `bevy_type_registry` crates with a new {{rust_mod(crate="bevy_reflect" version="0.4.0")}} crate. Bevy Reflect is intended to be a "generic" Rust reflection crate. I'm hoping it will be as useful for non-Bevy projects as it is for Bevy. We now use it for our Scene system, but in the future we will use it for animating Component fields and auto-generating Bevy Editor inspector widgets. +In this release we replaced the old `bevy_property` and `bevy_type_registry` crates with a new [`bevy_reflect`] crate. Bevy Reflect is intended to be a "generic" Rust reflection crate. I'm hoping it will be as useful for non-Bevy projects as it is for Bevy. We now use it for our Scene system, but in the future we will use it for animating Component fields and auto-generating Bevy Editor inspector widgets. -Bevy Reflect enables you to dynamically interact with Rust types by deriving the {{rust_type(type="trait" crate="bevy_reflect" version="0.4.0" name="Reflect" no_mod=true)}} trait: +Bevy Reflect enables you to dynamically interact with Rust types by deriving the [`Reflect`] trait: ```rust #[derive(Reflect)] @@ -558,6 +572,11 @@ let mut foo = Foo { }; ``` +[`TypeId`]: https://doc.rust-lang.org/stable/std/any/struct.TypeId.html +[`type_name`]: https://doc.rust-lang.org/std/any/fn.type_name.html +[`bevy_reflect`]: https://docs.rs/bevy/0.4.0/bevy/reflect/index.html +[`Reflect`]: https://docs.rs/bevy/0.4.0/bevy/reflect/trait.Reflect.html + ### Interact with Fields Using Their Names ```rust @@ -684,10 +703,12 @@ The Texture asset now has support for 3D textures. The new `array_texture.rs` ex
authors: @superdump, @cart
-Bevy finally has built in logging, which is now enabled by default via the new {{rust_type(type="struct" crate="bevy_log" version="0.4.0" name="LogPlugin" no_mod=true)}}. We evaluated various logging libraries and eventually landed on the new `tracing` crate. `tracing` is a structured logger that handles async / parallel logging well (perfect for an engine like Bevy), and enables profiling in addition to "normal" logging. +Bevy finally has built in logging, which is now enabled by default via the new [`LogPlugin`]. We evaluated various logging libraries and eventually landed on the new [`tracing`] crate. `tracing` is a structured logger that handles async / parallel logging well (perfect for an engine like Bevy), and enables profiling in addition to "normal" logging. -The {{rust_type(type="struct" crate="bevy_log" version="0.4.0" name="LogPlugin" no_mod=true)}} configures each platform to log to the appropriate backend by default: the terminal on desktop, the console on web, and Android Logs / logcat on Android. We built a new Android `tracing` backend because one didn't exist yet. +The [`LogPlugin`] configures each platform to log to the appropriate backend by default: the terminal on desktop, the console on web, and Android Logs / logcat on Android. We built a new Android `tracing` backend because one didn't exist yet. +[`LogPlugin`]: https://docs.rs/bevy/0.4.0/bevy/log/struct.LogPlugin.html +[`tracing`]: https://docs.rs/tracing/latest/tracing/ ### Logging diff --git a/content/news/2021-04-06-bevy-0.5/index.md b/content/news/2021-04-06-bevy-0.5/index.md index 69e9419a87..1d3aca9c79 100644 --- a/content/news/2021-04-06-bevy-0.5/index.md +++ b/content/news/2021-04-06-bevy-0.5/index.md @@ -29,12 +29,14 @@ Here are some of the highlights from this release: Bevy now uses PBR shaders when rendering. PBR is a semi-standard approach to rendering that attempts to use approximations of real-world "physically based" lighting and material properties. We largely use techniques from the [Filament](https://github.com/google/filament/) PBR implementation, but we also incorporate some ideas from [Unreal](https://www.unrealengine.com/en-US/blog/physically-based-shading-on-mobile) and [Disney](https://google.github.io/filament/Filament.html#citation-burley12). -Bevy's `StandardMaterial` now has `base_color`, `roughness`, `metallic`, `reflection`, and `emissive` properties. It also now supports textures for `base_color`, `normal_map`, `metallic_roughness`, `emissive`, and `occlusion` properties. +Bevy's [`StandardMaterial`] now has `base_color`, `roughness`, `metallic`, `reflection`, and `emissive` properties. It also now supports textures for `base_color`, `normal_map`, `metallic_roughness`, `emissive`, and `occlusion` properties. The new PBR example helps visualize these new material properties: ![pbr](pbr.png) +[`StandardMaterial`]: https://docs.rs/bevy/0.5.0/bevy/pbr/prelude/struct.StandardMaterial.html + ## GLTF Improvements ### PBR Textures @@ -49,7 +51,7 @@ The GLTF loader now supports normal maps, metallic/roughness, occlusion, and emi
authors: @mockersf
-Previously it was hard to interact with GLTF assets because scenes / meshes / textures / and materials were only loaded as "sub assets". Thanks to the new top level {{rust_type(type="struct" crate="bevy_gltf" version="0.5.0" name="Gltf" no_mod=true)}} asset type, it is now possible to navigate the contents of the GLTF asset: +Previously it was hard to interact with GLTF assets because scenes / meshes / textures / and materials were only loaded as "sub assets". Thanks to the new top level [`Gltf`] asset type, it is now possible to navigate the contents of the GLTF asset: ```rust // load GLTF asset on startup @@ -66,6 +68,8 @@ fn system(handle: Res>, gltfs: Res>, materials: Res(); @@ -167,9 +171,12 @@ for (a, mut b) in query.iter_mut(&mut world) { } ``` -However for {{rust_type(type="trait" crate="bevy_ecs" mod="system" version="0.5.0" name="System" no_mod=true plural=true)}} this is a non-breaking change. Query state management is done internally by the relevant SystemParam. +However for systems this is a non-breaking change. Query state management is done internally by the relevant [`SystemParam`]. + +We have achieved some pretty significant performance wins as a result of the new [`Query`] system. -We have achieved some pretty significant performance wins as a result of the new Query system. +[`World`]: https://docs.rs/bevy/0.5.0/bevy/ecs/world/struct.World.html +[`SystemParam`]: https://docs.rs/bevy/0.5.0/bevy/ecs/system/derive.SystemParam.html #### "Sparse" Fragmented Iterator Benchmark (in nanoseconds, less is better) @@ -190,7 +197,7 @@ The gains here compared to the last benchmark are smaller because there aren't a ### Uber Fast "for_each" Query Iterators -Developers now have the choice to use a fast {{rust_type(type="struct" crate="bevy_ecs" mod="system" version="0.5.0" name="Query" no_mod=true method="for_each")}} iterator, which yields ~1.5-3x iteration speed improvements for "fragmented iteration", and minor ~1.2x iteration speed improvements for unfragmented iteration. +Developers now have the choice to use a fast [`Query::for_each`] iterator, which yields ~1.5-3x iteration speed improvements for "fragmented iteration", and minor ~1.2x iteration speed improvements for unfragmented iteration. ```rust fn system(query: Query<(&A, &mut B)>) { @@ -206,6 +213,8 @@ fn system(query: Query<(&A, &mut B)>) { We will continue to encourage "normal" iterators as they are more flexible and more "rust idiomatic". But when that extra "oomf" is needed, `for_each` will be there ... waiting for you :) +[`Query::for_each`]: https://docs.rs/bevy/0.5.0/bevy/ecs/system/struct.Query.html#method.for_each + ## New Parallel System Executor
authors: @Ratysz
@@ -225,7 +234,7 @@ Fortunately @Ratysz has been [doing](https://ratysz.github.io/article/scheduling
authors: @Ratysz, @TheRawMeatball
-Systems can now be assigned one or more {{rust_type(type="trait" crate="bevy_ecs" mod="schedule" version="0.5.0" name="SystemLabel" no_mod=true plural=true)}}. These labels can then be referenced by other systems (within a stage) to run before or after systems with that label: +Systems can now be assigned one or more [`SystemLabels`]. These labels can then be referenced by other systems (within a stage) to run before or after systems with that label: ```rust app @@ -243,7 +252,7 @@ app .add_system(movement.system().label("movement")); ``` -Any type that implements the {{rust_type(type="trait" crate="bevy_ecs" mod="schedule" version="0.5.0" name="SystemLabel" no_mod=true)}} trait can be used. In most cases we recommend defining custom types and deriving {{rust_type(type="trait" crate="bevy_ecs" mod="schedule" version="0.5.0" name="SystemLabel" no_mod=true)}} for them. This prevents typos, allows for encapsulation (when needed), and allows IDEs to autocomplete labels: +Any type that implements the [`SystemLabel`] trait can be used. In most cases we recommend defining custom types and deriving [`SystemLabel`] for them. This prevents typos, allows for encapsulation (when needed), and allows IDEs to autocomplete labels: ```rust #[derive(Debug, Hash, PartialEq, Eq, Clone, SystemLabel)] @@ -260,6 +269,9 @@ app ); ``` +[`SystemLabels`]: https://docs.rs/bevy/0.5.0/bevy/ecs/schedule/trait.SystemLabel.html +[`SystemLabel`]: https://docs.rs/bevy/0.5.0/bevy/ecs/schedule/trait.SystemLabel.html + ### Many-to-Many System Labels Many-to-many labels is a powerful concept that makes it easy to take a dependency on many systems that produce a given behavior/outcome. For example, if you have a system that needs to run after all "physics" has finished updating (see the example above), you could label all "physics systems" with the same `Physics` label: @@ -291,7 +303,7 @@ Bevy plugin authors should export labels like this in their public APIs to enabl ### System Sets -{{rust_type(type="struct" crate="bevy_ecs" mod="schedule" version="0.5.0" name="SystemSet" no_mod=true plural=true)}} are a new way to apply the same configuration to a group of systems, which significantly cuts down on boilerplate. The "physics" example above could be rephrased like this: +[`SystemSets`] are a new way to apply the same configuration to a group of systems, which significantly cuts down on boilerplate. The "physics" example above could be rephrased like this: ```rust app @@ -308,7 +320,7 @@ app SystemSets can also use `before(Label)` and `after(Label)` to run all systems in the set before/after the given label. -This is also very useful for groups of systems that need to run with the same {{rust_type(type="struct" crate="bevy_ecs" mod="schedule" version="0.5.0" name="RunCriteria" no_mod=true)}}. +This is also very useful for groups of systems that need to run with the same [`RunCriteria`]. ```rust app @@ -320,6 +332,9 @@ app ) ``` +[`SystemSets`]: https://docs.rs/bevy/0.5.0/bevy/ecs/schedule/struct.SystemSet.html +[`RunCriteria`]: https://docs.rs/bevy/0.5.0/bevy/ecs/schedule/struct.RunCriteria.html + ### Improved Run Criteria Run Criteria are now decoupled from systems and will be re-used when possible. For example, the FixedTimestep criteria in the example above will only be run once per stage run. The executor will re-use the criteria's result for both the `foo` and `bar` system. @@ -461,7 +476,7 @@ The [last Bevy release](https://bevyengine.org/news/bevy-0-4) added States, whic The old implementation largely worked, but it had a number of quirks and limitations. First and foremost, it required adding a new `StateStage`, which cut down on parallelism, increased boilerplate, and forced ordering where it wasn't required. Additionally, some of the lifecycle events didn't always behave as expected. -The new {{rust_type(type="struct" crate="bevy_ecs" mod="schedule" version="0.5.0" name="State" no_mod=true)}} implementation is built on top of the new parallel executor's SystemSet and RunCriteria features, for a much more natural, flexible, and parallel api that builds on existing concepts instead of creating new ones: +The new [`State`] implementation is built on top of the new parallel executor's SystemSet and RunCriteria features, for a much more natural, flexible, and parallel api that builds on existing concepts instead of creating new ones: ```rust #[derive(Debug, Clone, Eq, PartialEq, Hash)] @@ -509,6 +524,8 @@ fn system(mut state: ResMut>) { Just like the old implementation, state changes are applied in the same frame. This means it is possible to transition from states `A->B->C` and run the relevant state lifecycle events without skipping frames. This builds on top of "looping run criteria", which we also use for our "fixed timestep" implementation (and which you can use for your own run criteria logic). +[`State`]: https://docs.rs/bevy/0.5.0/bevy/ecs/schedule/struct.State.html + ## Event Ergonomics
authors: @TheRawMeatball
@@ -649,9 +666,9 @@ layout(set = 0, binding = 1) uniform CameraPosition {
authors: @schell
-Sometimes you don't want a camera to draw everything in a scene, or you want to temporarily hide a set of things in the scene. **Bevy 0.5** adds a `RenderLayer` system, which gives developers the ability to add entities to layers by adding the `RenderLayers` component. +Sometimes you don't want a camera to draw everything in a scene, or you want to temporarily hide a set of things in the scene. **Bevy 0.5** adds a `RenderLayer` system, which gives developers the ability to add entities to layers by adding the [`RenderLayers`] component. -Cameras can also have a {{rust_type(type="struct" crate="bevy_render" mod="camera" version="0.5.0" name="RenderLayers" no_mod=true)}} component, which determines what layers they can see. +Cameras can also have a [`RenderLayers`] component, which determines what layers they can see. ```rust // spawn a sprite on layer 0 @@ -676,6 +693,8 @@ commands .insert(RenderLayers::layer(1)); ``` +[`RenderLayers`]: https://docs.rs/bevy/0.5.0/bevy/render/camera/struct.RenderLayers.html + ## Sprite Flipping
authors: @zicklag
@@ -708,7 +727,7 @@ commands.spawn_bundle(SpriteBundle {
authors: @mockersf
-{{rust_type(type="enum" crate="bevy_render" mod="color" version="0.5.0" name="Color" no_mod=true)}} is now internally represented as an enum, which enables lossless (and correct) color representation. This is a significant improvement over the previous implementation, which internally converted all colors to linear sRGB (which could cause precision issues). Colors are now only converted to linear sRGB when they are sent to the GPU. We also took this opportunity to fix some incorrect color constants defined in the wrong color space. +[`Color`] is now internally represented as an enum, which enables lossless (and correct) color representation. This is a significant improvement over the previous implementation, which internally converted all colors to linear sRGB (which could cause precision issues). Colors are now only converted to linear sRGB when they are sent to the GPU. We also took this opportunity to fix some incorrect color constants defined in the wrong color space. ```rust pub enum Color { @@ -748,6 +767,8 @@ pub enum Color { } ``` +[`Color`]: https://docs.rs/bevy/0.5.0/bevy/render/color/enum.Color.html + ## Wireframes
authors: @Neo-Zhixing
@@ -770,7 +791,7 @@ This example serves as a quick introduction to building 3D games in Bevy. It sho
authors: @kokounet
-The {{rust_type(type="struct" crate="bevy_core" version="0.5.0" name="Timer" no_mod=true)}} struct now internally uses {{rust_type(type="struct" crate="std" mod="time" name="Duration" no_mod=true plural=true)}} instead of using `f32` representations of seconds. This both increases precision and makes the api a bit nicer to look at. +The [`Timer`] struct now internally uses [`Duration`] instead of using `f32` representations of seconds. This both increases precision and makes the api a bit nicer to look at. ```rust fn system(mut timer: ResMut, time: Res