Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Remove Rust doc shortcodes from new book #272

Merged
merged 16 commits into from
Feb 12, 2022
Merged

Remove Rust doc shortcodes from new book #272

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
ee2c91e
Exterminate Rust-doc linking shortcodes
alice-i-cecile Jan 13, 2022
6342b98
Remove all shortcodes
alice-i-cecile Jan 13, 2022
6c6e1c3
Relink 0.6 news post
alice-i-cecile Jan 18, 2022
ebc7fb1
Relink 0.4 to 0.5 migration guide
alice-i-cecile Jan 18, 2022
4d2a3ea
Relink 0.5 to 0.6 migration guide
alice-i-cecile Jan 18, 2022
416d945
Port links for 0.1 announcement
alice-i-cecile Jan 18, 2022
21f57a4
Relink 0.4 release announcement
alice-i-cecile Jan 18, 2022
b9cc49f
Relink 0.5 announcement
alice-i-cecile Jan 19, 2022
1bd12aa
Relink 1st Birthday post
alice-i-cecile Jan 19, 2022
3d85203
Fix links for 0.5 to 0.6 migration guide
alice-i-cecile Feb 11, 2022
075d057
Repair links in 0.1 announcement
alice-i-cecile Feb 11, 2022
82dcb2b
Fix links in 0.4 announcement
alice-i-cecile Feb 11, 2022
392fd01
More links for Bevy 0.5
alice-i-cecile Feb 11, 2022
edbd9f3
More links for Bevy 0.6
alice-i-cecile Feb 11, 2022
09810af
Replace shortcodes in Welcome chapter
alice-i-cecile Feb 11, 2022
db45cd9
Actually fix missing links in 0.1 announcement
alice-i-cecile Feb 12, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 12 additions & 7 deletions content/learn/book/migration-guides/0.4-0.5/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down
85 changes: 61 additions & 24 deletions content/learn/book/migration-guides/0.5-0.6/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -168,6 +176,11 @@ fn player_system_fallible(query: Query<&Transform, With<Player>>) {
}
```

[`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
Expand All @@ -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.

<!-- TODO: Remove this comment if https://github.com/bevyengine/bevy/pull/2367 is merged.
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.

In addition the {{rust_type(type="struct" crate="bevy_pbr" mod="" version="0.6.0" name="DirectionalLight" no_mod=true)}} and {{rust_type(type="struct" crate="bevy_pbr" mod="" version="0.6.0" name="DirectionalLightBundle" no_mod=true)}} were introduced with `0.6`.

-->
[`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
Expand All @@ -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

<!-- Adapt for ParamSet instead, if https://github.com/bevyengine/bevy/pull/2765 is merged -->
### 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
Expand All @@ -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\<T\>.update()" is renamed to "Input\<T\>.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

<!-- TODO: Link to entry for SystemState in the release blog post. -->

### 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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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#
21 changes: 13 additions & 8 deletions content/learn/book/welcome/apps/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,12 @@ template = "book-section.html"
page_template = "book-section.html"
+++

Bevy programs store and execute all of their game logic and data with a single {{rust_type(type="struct" crate="bevy" mod = "app" name="App" no_mod = "true")}} data structure.
Bevy programs store and execute all of their game logic and data with a single [`App`] data structure.

Let's make a trivial Hello World app to demonstrate how that works in practice.
The process is straightforward: we first create a new {{rust_type(type="struct" crate="bevy" mod = "app" name="App" no_mod = "true")}}.
The process is straightforward: we first create a new [`App`].
Then, we add a simple system, which prints "Hello, Bevy!" when it is run.
Finally once we're done configuring the app, we call {{rust_type(type="struct" crate="bevy" mod = "app" name="App" method="run" no_mod = "true")}} to actually make our app *do things*.
Finally once we're done configuring the app, we call [`App`] to actually make our app *do things*.

```rust
use bevy::prelude::*;
Expand All @@ -28,18 +28,18 @@ fn hello(){

## What makes an App?

So, what sort of data does our {{rust_type(type="struct" crate="bevy" mod = "app" name="App" no_mod = "true")}} really store?
So, what sort of data does our [`App`] really store?
Looking at the docs linked, we find three fields: `world`, `schedule` and `runner`.
The `world` field stores all of our game's data, the `schedule` holds the systems that operate on this data (and the order in which they do so) and the `runner` interprets the schedule to control the broad execution strategy.
You can read more about these by exploring the reference documentation linked just above.

Generally, you'll be operating at a more granular level than these basic primitives: controlling data in terms of specific resources or components and adding systems to an existing schedule.
To do so, customize your own {{rust_type(type="struct" crate="bevy" mod = "app" name="App" no_mod = "true")}} by chaining its methods with the [builder pattern](https://doc.rust-lang.org/1.0.0/style/ownership/builders.html).
To do so, customize your own [`App`] by chaining its methods with the [builder pattern](https://doc.rust-lang.org/1.0.0/style/ownership/builders.html).
The most basic tools are:

1. Initializing resources in the {{rust_type(type="struct" crate="bevy" mod = "ecs/world" name="World" no_mod = "true")}} to store globally available data that we only need a single copy of.
2. Adding systems to our {{rust_type(type="struct" crate="bevy" mod = "ecs/schedule" name="Schedule" no_mod = "true")}}, which can read and modify resources and our entities' components, according to our game logic.
3. Importing other blocks of {{rust_type(type="struct" crate="bevy" mod = "app" name="App" no_mod = "true")}}-modifying code using plugins.
1. Initializing resources in the [`World`] to store globally available data that we only need a single copy of.
2. Adding systems to our [`Schedule`], which can read and modify resources and our entities' components, according to our game logic.
3. Importing other blocks of [`App`]-modifying code using [`Plugins`].
Let's write a very simple demo that shows how those work.

```rust
Expand Down Expand Up @@ -68,3 +68,8 @@ fn read_message(message: Res<Message>) {
println!(message.string);
}
```

[`App`]: https://docs.rs/bevy/latest/bevy/app/struct.App.html
[`World`]: https://docs.rs/bevy/latest/bevy/ecs/world/struct.World.html
[`Schedule`]: https://docs.rs/bevy/latest/bevy/ecs/schedule/struct.Schedule.html
[`Plugins`]: https://docs.rs/bevy/latest/bevy/app/trait.Plugin.html
Loading