From ee2c91e7698ee9ab519bdf016d1afe822f6c8b55 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Wed, 12 Jan 2022 23:03:17 -0500 Subject: [PATCH 01/16] Exterminate Rust-doc linking shortcodes --- templates/shortcodes/rust_mod.html | 24 ------------------------ templates/shortcodes/rust_type.html | 25 ------------------------- 2 files changed, 49 deletions(-) delete mode 100644 templates/shortcodes/rust_mod.html delete mode 100644 templates/shortcodes/rust_type.html diff --git a/templates/shortcodes/rust_mod.html b/templates/shortcodes/rust_mod.html deleted file mode 100644 index 37958705a2..0000000000 --- a/templates/shortcodes/rust_mod.html +++ /dev/null @@ -1,24 +0,0 @@ - -{% if not crate %} -{% set crate = "std" %} -{% endif %} - -{% if not version %} -{% set version = "latest" %} -{% endif %} - -{% if mod %} -{% set mod_path = "/" ~ mod | replace(from="::", to="/") %} -{% else %} -{% set mod_path = "" %} -{% endif %} - -{% if crate == "std" %} -{% set url = "https://doc.rust-lang.org" %} -{% set path = "stable/" ~ crate %} -{% else %} -{% set url = "https://docs.rs" %} -{% set path = crate ~ "/" ~ version ~ "/" ~ crate %} -{% endif %} - -{% if not no_crate and crate%}{{crate}}{% if not no_mod and mod%}::{{mod}}{% endif %}{% elif not no_mod and mod%}{{mod}}{% endif %} diff --git a/templates/shortcodes/rust_type.html b/templates/shortcodes/rust_type.html deleted file mode 100644 index 008a9aa7eb..0000000000 --- a/templates/shortcodes/rust_type.html +++ /dev/null @@ -1,25 +0,0 @@ -{% if not crate %} -{% set crate = "std" %} -{% endif %} - -{% if not version %} -{% set version = "latest" %} -{% endif %} - -{% if not mod %} -{% set mod_path = "" %} -{% set mod = "" %} -{% else %} -{% set mod_path = "/" ~ mod | replace(from="::", to="/") %} -{% endif %} - -{% if crate == "std" %} -{% set url = "https://doc.rust-lang.org" %} -{% set path = "stable/" ~ crate %} -{% else %} -{% set url = "https://docs.rs" %} -{% set path = crate ~ "/" ~ version ~ "/" ~ crate %} -{% endif %} - -{% if not no_crate and crate and not no_mod and mod %}{{crate}}::{% if not no_mod and mod%}{{mod}}::{% endif %}{% elif not no_mod and mod%}{{mod}}::{% endif %}{% if not no_struct %}{{name}}{% if plural %}s{% endif %}{% endif %}{% if method %}{% if not no_struct %}::{% endif %}{{method}}(){% endif %} - From 6342b983081ed86cf15c1337429a3a06cc65f895 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Thu, 13 Jan 2022 00:04:08 -0500 Subject: [PATCH 02/16] Remove all shortcodes --- .../book/migration-guides/0.4-0.5/_index.md | 10 ++--- .../book/migration-guides/0.5-0.6/_index.md | 42 ++++++++----------- .../news/2020-08-10-introducing-bevy/index.md | 37 ++++++++-------- content/news/2020-12-19-bevy-0.4/index.md | 26 ++++++------ content/news/2021-04-06-bevy-0.5/index.md | 28 ++++++------- .../2021-08-10-bevys-first-birthday/index.md | 4 +- content/news/2022-01-08-bevy-0.6/index.md | 22 +++++----- 7 files changed, 81 insertions(+), 88 deletions(-) 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..28aab4ce4d 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,15 @@ 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 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,7 +97,7 @@ 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)}} +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 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..7f9aa10689 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 @@ -63,7 +63,7 @@ impl Plugin for SomePlugin { ### 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 @@ -84,7 +84,7 @@ struct Cooldown(std::time::Duration); ### 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 +145,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 @@ -194,18 +194,12 @@ 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. - - +The `Light` and `LightBundle` types were renamed to `PointLight` and `PointLightBundle` to more clearly communicate the behavior of the Light Source. +At the same time the `fov` and `depth` fields were removed from `PointLight` as they were unused. ### 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 @@ -231,9 +225,7 @@ struct SystemParamDerive<'w, 's> { ### 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), `ParamSet` system parameters now need to specify their Queries with `QueryState` instead of `Query`. ```rust // 0.5 @@ -249,19 +241,19 @@ fn query_set(mut queries: QuerySet<(QueryState<&mut Transform>, QueryState<&Tran ### "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`. ### "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 `SystemState` struct, 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. ### 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 @@ -275,11 +267,11 @@ let xyz: IVec3 = xyz.as_ivec3(); ### 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`. ### 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 @@ -309,7 +301,7 @@ SpriteBundle { ``` ### 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 diff --git a/content/news/2020-08-10-introducing-bevy/index.md b/content/news/2020-08-10-introducing-bevy/index.md index fc0dfb2aaf..3d52b04ff6 100644 --- a/content/news/2020-08-10-introducing-bevy/index.md +++ b/content/news/2020-08-10-introducing-bevy/index.md @@ -52,7 +52,7 @@ 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! @@ -79,9 +79,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 +96,8 @@ 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. ## Bevy ECS @@ -336,12 +337,12 @@ 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. ### 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 @@ -367,7 +368,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 +376,11 @@ 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. ### 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 +542,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: @@ -561,7 +562,7 @@ fn system(_button: &Button, interaction: Mutated) { ### [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) @@ -702,7 +703,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) { @@ -816,14 +817,14 @@ fn event_consumer(mut state: Local, 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). ## 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: #### Asset Creation ```rs @@ -855,7 +856,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>) { @@ -895,7 +896,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 @@ -924,13 +925,13 @@ 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: 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..38c07b9683 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 @@ -196,7 +196,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 +209,7 @@ impl Stage for MyStage { } ``` -#### Stage Type: {{rust_type(type="struct" crate="bevy_ecs" version="0.4.0" name="SystemStage" no_mod=true)}} +#### 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 +233,9 @@ 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)}} +#### Stage Type: `Schedule` -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: +You read that right! `Schedule` now implements the `Stage` trait, which means you can nest Schedules within other schedules: ```rust let schedule = Schedule::default() @@ -252,7 +252,7 @@ let schedule = Schedule::default() #### 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 @@ -296,7 +296,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 @@ -368,7 +368,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()) @@ -527,15 +527,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)] @@ -684,9 +684,9 @@ 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. ### 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..79d7bf4aee 100644 --- a/content/news/2021-04-06-bevy-0.5/index.md +++ b/content/news/2021-04-06-bevy-0.5/index.md @@ -49,7 +49,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 @@ -150,7 +150,7 @@ You may have noticed that **Bevy 0.5 (Table)** is also _way_ faster than **Bevy ### Stateful Queries and System Parameters -{{rust_type(type="struct" crate="bevy_ecs" mod="world" version="0.5.0" name="World" no_mod=true)}} queries (and other system parameters) are now stateful. This allows us to: +`World` queries (and other system parameters) are now stateful. This allows us to: 1. Cache archetype (and table) matches * This resolves another issue with (naive) archetypal ECS: query performance getting worse as the number of archetypes goes up (and fragmentation occurs). @@ -159,7 +159,7 @@ You may have noticed that **Bevy 0.5 (Table)** is also _way_ faster than **Bevy 3. Incrementally build up state * When new archetypes are added, we only process the new archetypes (no need to rebuild state for old archetypes) -As a result, the direct {{rust_type(type="struct" crate="bevy_ecs" mod="world" version="0.5.0" name="World" no_mod=true)}} query api now looks like this: +As a result, the direct `World` query api now looks like this: ```rust let mut query = world.query::<(&A, &mut B)>(); @@ -167,7 +167,7 @@ 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. @@ -190,7 +190,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)>) { @@ -225,7 +225,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 +243,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)] @@ -291,7 +291,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 +308,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 @@ -461,7 +461,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)] @@ -651,7 +651,7 @@ layout(set = 0, binding = 1) uniform CameraPosition { 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 @@ -708,7 +708,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 { @@ -770,7 +770,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