diff --git a/content/learn/book/contributing/docs/_index.md b/content/learn/book/contributing/docs/_index.md index 8e2570c281..76b77d970e 100644 --- a/content/learn/book/contributing/docs/_index.md +++ b/content/learn/book/contributing/docs/_index.md @@ -30,25 +30,28 @@ A local server should start and you should be able to access a local version of ### Rust API Doc Syntax -We made an extension to the markdown syntax that makes linking to Rust API docs nicer. It also gives the links special formatting. Here are some examples: +We made an extension to the markdown syntax that makes linking to Rust API docs easier and prettier. +Here are some example links and the associated shortcodes: -* Full Type Path: {{rust_type(type="struct" crate="std", mod="collections", name="HashMap")}} +- {{rust_docs(type="struct" crate="std" mod="collections" name="HashMap")}}: ???. This is the standard invocation. +- {{rust_docs(type="struct" mod="ecs::system" name="Commands" method = "spawn")}}: ???. We can specify which method, field, variant or trait implementation we're referring to using the `method`, `field`,`variant` or `impl` arguments. +- {{rust_docs(type="trait" crate="bevy_ecs" mod="system" name="Command" method = "write")}}: ???. Change the `type` argument to link to enums, traits or keywords. +- {{rust_docs(type="struct" crate="std" mod="result" name="Result" show_mod=true)}}: ???. By using `show_mod`, we can see the full path. +- {{rust_docs(crate="std" mod="collections")}}: ???. By omitting `type` and `name`, we can link to the crate or module itself. - ```{{curly_open()}}{rust_type(type="struct" crate="std" mod="collections" name="HashMap")}{{curly_close()}}``` -* Short Type: {{rust_type(type="struct", crate="std" mod="collections", name="HashMap", no_mod=true)}} +By default, the `crate` argument is set to "bevy", as almost all of the linked docs are part of the Bevy umbrella. +For example, you can use `mod = "ecs"` or so to link to the items within the `bevy_ecs` crate correctly. - ```{{curly_open()}}{rust_type(type="struct" crate="std" mod="collections" name="HashMap" no_mod=true)}{{curly_close()}}``` -* Plural Type: {{rust_type(type="struct" crate="std" mod="collections" name="HashMap" no_mod=true plural=true)}} +There are several options available, toggled by adding the following arguments (separating each argument with a space) within the curly braces: - ```{{curly_open()}}{rust_type(type="struct" crate="std" mod="collections" name="HashMap" no_mod=true, plural=true)}{{curly_close()}}``` -* Function: {{rust_type(type="struct" crate="std" mod="collections" name="HashMap" no_mod=true method="insert")}} +- `show_crate`: shows the originating crate in the path +- `show_mod`: shows the originating module in the path +- `args`: adds the string as function arguments, wrapped in parentheses. +- `type_args`: adds the string as generic type arguments, wrapped in angle brackets +- `plural`: adds an "s" at the end of the link's name +- `possesive`: adds an "'s" as the end of the link's name - ```{{curly_open()}}{rust_type(type="struct" crate="std" mod="collections" name="HashMap" no_mod=true method="insert")}{{curly_close()}}``` -* Module: {{rust_mod(crate="std" mod="collections")}} - - ```{{curly_open()}}{rust_mod(crate="std" mod="collections")}{{curly_close()}}``` - -Modules from {{rust_mod(crate="std")}} will link to [https://doc.rust-lang.org](https://doc.rust-lang.org/std/index.html). Other modules (like {{rust_mod(crate="bevy_render" mod="render_graph")}} ) will link to [https://docs.rs](https://docs.rs). +Modules from {{rust_docs(crate="std")}} will link to [doc.rust-lang.org](https://doc.rust-lang.org/std/index.html). Other modules (like {{rust_docs(crate="bevy_render" mod="render_graph")}} ) will link to [docs.rs](https://docs.rs). ## Rust API Docs diff --git a/content/learn/book/getting-started/apps/_index.md b/content/learn/book/getting-started/apps/_index.md index 6f0b290fd3..222a4fdbb7 100644 --- a/content/learn/book/getting-started/apps/_index.md +++ b/content/learn/book/getting-started/apps/_index.md @@ -6,7 +6,7 @@ template = "book-section.html" page_template = "book-section.html" +++ -Bevy programs are referred to as {{rust_type(type="struct", crate="bevy_app", name="App", no_mod=true, plural=true)}}. The simplest Bevy app looks like this: +Bevy programs are referred to as {{rust_docs(type="struct", crate="bevy_app", name="App", plural=true)}}. The simplest Bevy app looks like this: ```rs use bevy::prelude::*; diff --git a/content/learn/book/getting-started/ecs/_index.md b/content/learn/book/getting-started/ecs/_index.md index 9a5df83218..c9a7ad6aa3 100644 --- a/content/learn/book/getting-started/ecs/_index.md +++ b/content/learn/book/getting-started/ecs/_index.md @@ -54,9 +54,9 @@ fn main() { } ``` -Note the `hello_world.system()` function call. This is a "trait extension method" that converts the `hello_world` function into the {{rust_type(type="trait" crate="bevy_ecs" mod="system" no_mod=true name="System")}} type. +Note the `hello_world.system()` function call. This is a "trait extension method" that converts the `hello_world` function into the {{rust_docs(type="trait" crate="bevy_ecs" mod="system" name="System")}} type. -The {{rust_type(type="struct" crate="bevy_app", name="AppBuilder" method="add_system" no_struct=true)}} function adds the system to your App's {{rust_type(type="struct", crate="bevy_ecs", mod="schedule" no_mod=true name="Schedule")}}, but we'll cover that more later. +The {{rust_docs(type="struct" crate="bevy_app", name="AppBuilder" method="add_system" no_struct=true)}} function adds the system to your App's {{rust_docs(type="struct", crate="bevy_ecs", mod="schedule" name="Schedule")}}, but we'll cover that more later. Now run your App again using `cargo run`. You should see `hello world!` printed once in your terminal. @@ -76,7 +76,7 @@ But what if we want our people to have a name? In a more traditional design, we struct Name(String); ``` -We can then add `People` to our {{rust_type(type="struct" crate="bevy_ecs" mod="world" no_mod=true name="World")}} using a "startup system". Startup systems are just like normal systems, but they run exactly once, before all other systems, right when our app starts. Let's use {{rust_type(type="struct" crate="bevy_ecs" mod="system" no_mod=true name="Commands")}} to spawn some entities into our {{rust_type(type="struct" crate="bevy_ecs" mod="world" no_mod=true name="World")}}: +We can then add `People` to our {{rust_docs(type="struct" crate="bevy_ecs" mod="world" name="World")}} using a "startup system". Startup systems are just like normal systems, but they run exactly once, before all other systems, right when our app starts. Let's use {{rust_docs(type="struct" crate="bevy_ecs" mod="system" name="Commands")}} to spawn some entities into our {{rust_docs(type="struct" crate="bevy_ecs" mod="world" name="World")}}: ```rs fn add_people(mut commands: Commands) { @@ -97,7 +97,7 @@ fn main() { } ``` -We could run this App now and the `add_people` system would run first, followed by `hello_world`. But our new people don't have anything to do yet! Let's make a system that properly greets the new citizens of our {{rust_type(type="struct" crate="bevy_ecs" mod="world" no_mod=true name="World")}}: +We could run this App now and the `add_people` system would run first, followed by `hello_world`. But our new people don't have anything to do yet! Let's make a system that properly greets the new citizens of our {{rust_docs(type="struct" crate="bevy_ecs" mod="world" name="World")}}: ```rs fn greet_people(query: Query<&Name, With>) { diff --git a/content/learn/book/getting-started/plugins/_index.md b/content/learn/book/getting-started/plugins/_index.md index f69b6c4a53..59eab311a3 100644 --- a/content/learn/book/getting-started/plugins/_index.md +++ b/content/learn/book/getting-started/plugins/_index.md @@ -6,9 +6,9 @@ template = "book-section.html" page_template = "book-section.html" +++ -One of Bevy's core principles is modularity. All Bevy engine features are implemented as plugins. This includes internal features like the renderer, but games themselves are also implemented as plugins! This empowers developers to pick and choose which features they want. Don't need a UI? Don't register the {{rust_type(type="struct" crate="bevy_ui", name="UiPlugin")}}. Want to build a headless server? Don't register the {{rust_type(type="struct" crate="bevy_render" name="RenderPlugin")}}. +One of Bevy's core principles is modularity. All Bevy engine features are implemented as plugins. This includes internal features like the renderer, but games themselves are also implemented as plugins! This empowers developers to pick and choose which features they want. Don't need a UI? Don't register the {{rust_docs(type="struct" crate="bevy_ui", name="UiPlugin")}}. Want to build a headless server? Don't register the {{rust_docs(type="struct" crate="bevy_render" name="RenderPlugin")}}. -This also means you are free to replace any components you don't like. If you feel the need, you are welcome to build your own {{rust_type(type="struct" crate="bevy_ui" name="UiPlugin")}}, but consider [contributing it back to Bevy](/learn/book/contributing) if you think it would be useful! +This also means you are free to replace any components you don't like. If you feel the need, you are welcome to build your own {{rust_docs(type="struct" crate="bevy_ui" name="UiPlugin")}}, but consider [contributing it back to Bevy](/learn/book/contributing) if you think it would be useful! However, most developers don't need a custom experience and just want the "full engine" experience with no hassle. For this, Bevy provides a set of "default plugins". @@ -31,8 +31,8 @@ fn main() { Once again run `cargo run`. You should hopefully notice two things: -* **A window should pop up**. This is because we now have {{rust_type(type="struct" crate="bevy_window" name="WindowPlugin")}}, which defines the window interface (but doesn't actually know how to make windows), and {{rust_type(type="struct" crate="bevy_winit" name="WinitPlugin")}} which uses the [winit library](https://github.com/rust-windowing/winit) to create a window using your OS's native window api. -* **Your console is now full of "hello" messages**: This is because {{rust_type(type="struct" crate="bevy" name="DefaultPlugins")}} adds an "event loop" to our application. Our App's ECS Schedule now runs in a loop once per "frame". We will resolve the console spam in a moment. +* **A window should pop up**. This is because we now have {{rust_docs(type="struct" crate="bevy_window" name="WindowPlugin")}}, which defines the window interface (but doesn't actually know how to make windows), and {{rust_docs(type="struct" crate="bevy_winit" name="WinitPlugin")}} which uses the [winit library](https://github.com/rust-windowing/winit) to create a window using your OS's native window api. +* **Your console is now full of "hello" messages**: This is because {{rust_docs(type="struct" name="DefaultPlugins")}} adds an "event loop" to our application. Our App's ECS Schedule now runs in a loop once per "frame". We will resolve the console spam in a moment. Note that `add_plugins(DefaultPlugins)` is equivalent to the following: ```rs @@ -50,7 +50,7 @@ You are free to use whatever approach suits you! ## Creating your first plugin -For better organization, let's move all of our "hello" logic to a plugin. To create a plugin we just need to implement the {{rust_type(type="trait" name="Plugin" crate="bevy_app" no_mod=true)}} interface. Add the following code to your `main.rs` file: +For better organization, let's move all of our "hello" logic to a plugin. To create a plugin we just need to implement the {{rust_docs(type="trait" name="Plugin" crate="bevy_app")}} interface. Add the following code to your `main.rs` file: ```rs pub struct HelloPlugin; diff --git a/content/learn/book/getting-started/resources/_index.md b/content/learn/book/getting-started/resources/_index.md index 4e3ec86903..519008f456 100644 --- a/content/learn/book/getting-started/resources/_index.md +++ b/content/learn/book/getting-started/resources/_index.md @@ -15,7 +15,7 @@ Here are some examples of data that could be encoded as **Resources**: ## Tracking Time with Resources -Let's solve our App's "hello spam" problem by only printing "hello" once every two seconds. We'll do this by using the {{rust_type(type="struct" crate="bevy_core" name="Time")}} resource, which is automatically added to our App via `add_plugins(DefaultPlugins)`. +Let's solve our App's "hello spam" problem by only printing "hello" once every two seconds. We'll do this by using the {{rust_docs(type="struct" crate="bevy_core" name="Time")}} resource, which is automatically added to our App via `add_plugins(DefaultPlugins)`. For simplicity, remove the `hello_world` system from your App. This way we only need to adapt the `greet_people` system. 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..2e1ce1ccfe 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 {{rust_docs(type="struct" crate="bevy_ecs" mod="system" version="0.5.0" name="Commands")}} +now holds an internal {{rust_docs(type="struct" crate="bevy_ecs" mod="world" version="0.5.0" name="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 {{rust_docs(type="struct" crate="bevy_ecs" mod="world" version="0.5.0" name="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 {{rust_docs(type="struct" crate="bevy_ecs" version="0.5.0" mod="system" name="Commands")}} API has been completely reworked for consistency with the {{rust_docs(type="struct" crate="bevy_ecs" mod="world" version="0.5.0" name="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 {{rust_docs(type="struct" crate="bevy_core" version="0.5.0" name="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/news/2020-08-10-introducing-bevy/index.md b/content/news/2020-08-10-introducing-bevy/index.md index ebe5ad6c7c..24396af0cf 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: {{rust_docs(type="struct" crate="bevy_render" version="0.1.0" mod="texture" name="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 +{{rust_docs(type="trait" version="0.1.0" name="AddDefaultPlugins" method="add_default_plugins" 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 -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 {{rust_docs(type="trait" name="Plugin" crate="bevy_app" version="0.1.0" plural=true)}} manually like this: ```rs fn main() { @@ -96,7 +96,7 @@ 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 {{rust_docs(type="trait" version="0.1.0" name="AddDefaultPlugins" method="add_default_plugins" no_struct=true)}} for simplicity, at least initially. ## Bevy ECS @@ -336,12 +336,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 {{rust_docs(type="trait" crate="bevy_ecs" version="0.1.0" name="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 {{rust_docs(type="struct" crate="bevy_ecs" version="0.1.0" name="World")}}, {{rust_docs(type="struct" crate="bevy_ecs" version="0.1.0" name="Archetype")}}, and internal {{rust_docs(type="trait" crate="bevy_ecs" version="0.1.0" name="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 +367,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 {{rust_docs(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_docs(type="struct" name="Transform" crate="bevy_transform" version="0.1.0" mod="components")}} component used elsewhere in Bevy. The {{rust_docs(type="struct" name="Style" crate="bevy_ui" version="0.1.0")}} 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 +375,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. +{{rust_docs(type="struct" name="NodeComponents" crate="bevy_ui" version="0.1.0" mod="entity")}} 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 {{rust_docs(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. ### Relative Positioning @@ -541,7 +541,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 {{rust_docs(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: @@ -561,7 +561,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 {{rust_docs(type="struct" name="Texture" crate="bevy_render" version="0.1.0" mod="texture")}} asset as a sprite directly: ![sprite](sprite.png) @@ -702,7 +702,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 {{rust_docs(type="struct" name="SceneSpawner" crate="bevy_scene" version="0.1.0")}} resource. Spawning can be done with either {{rust_docs(type="struct" name="SceneSpawner" method="load" crate="bevy_scene" version="0.1.0")}} or {{rust_docs(type="struct" name="SceneSpawner" method="instance" crate="bevy_scene" version="0.1.0")}}. "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 +816,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 {{rust_docs(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_docs(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. 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 {{rust_docs(type="struct" crate="bevy_asset" version="0.1.0" name="Assets")}} are just typed data that can be referenced using asset {{rust_docs(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: #### Asset Creation ```rs @@ -855,7 +855,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 {{rust_docs(type="struct" crate="bevy_asset" version="0.1.0" name="AssetServer")}} resource: ```rs fn system(mut commands: Commands, asset_server: Res, mut textures: ResMut>) { @@ -895,7 +895,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 {{rust_docs(type="trait" crate="bevy_asset" version="0.1.0" name="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 +924,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 {{rust_docs(type="struct" crate="bevy_render" version="0.1.0" mod="render_graph" name="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 {{rust_docs(type="trait" crate="bevy_render" version="0.1.0" mod="renderer" name="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..682bab3a6e 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 {{rust_docs(type="trait" crate="bevy_ecs" version="0.4.0" name="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: {{rust_docs(type="struct" crate="bevy_ecs" version="0.4.0" name="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: {{rust_docs(type="struct" crate="bevy_ecs" version="0.4.0" name="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! {{rust_docs(type="struct" crate="bevy_ecs" version="0.4.0" name="Schedule")}} now implements the {{rust_docs(type="trait" crate="bevy_ecs" version="0.4.0" name="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 {{rust_docs(type="struct" crate="bevy_ecs" version="0.4.0" name="SystemStage")}} or {{rust_docs(type="struct" crate="bevy_ecs" version="0.4.0" name="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 {{rust_docs(type="trait" crate="bevy_app" version="0.4.0" name="Plugin" plural=true)}} 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 {{rust_docs(type="struct" crate="bevy_ecs" version="0.4.0" name="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 {{rust_docs(type="struct" crate="std", mod="any", name="TypeId")}} and {{rust_docs(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. 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 {{rust_docs(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. -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 {{rust_docs(type="trait" crate="bevy_reflect" version="0.4.0" name="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 {{rust_docs(type="struct" crate="bevy_log" version="0.4.0" name="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 {{rust_docs(type="struct" crate="bevy_log" version="0.4.0" name="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..e44d8b08d2 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 {{rust_docs(type="struct" crate="bevy_gltf" version="0.5.0" name="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: +{{rust_docs(type="struct" crate="bevy_ecs" mod="world" version="0.5.0" name="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 {{rust_docs(type="struct" crate="bevy_ecs" mod="world" version="0.5.0" name="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 {{rust_docs(type="trait" crate="bevy_ecs" mod="system" version="0.5.0" name="System" plural=true)}} 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 {{rust_docs(type="struct" crate="bevy_ecs" mod="system" version="0.5.0" name="Query" 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. ```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 {{rust_docs(type="trait" crate="bevy_ecs" mod="schedule" version="0.5.0" name="SystemLabel" plural=true)}}. 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 {{rust_docs(type="trait" crate="bevy_ecs" mod="schedule" version="0.5.0" name="SystemLabel")}} trait can be used. In most cases we recommend defining custom types and deriving {{rust_docs(type="trait" crate="bevy_ecs" mod="schedule" version="0.5.0" name="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: +{{rust_docs(type="struct" crate="bevy_ecs" mod="schedule" version="0.5.0" name="SystemSet" 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: ```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 {{rust_docs(type="struct" crate="bevy_ecs" mod="schedule" version="0.5.0" name="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 {{rust_docs(type="struct" crate="bevy_ecs" mod="schedule" version="0.5.0" name="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 {{rust_docs(type="struct" crate="bevy_render" mod="camera" version="0.5.0" name="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. +{{rust_docs(type="enum" crate="bevy_render" mod="color" version="0.5.0" name="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 {{rust_docs(type="struct" crate="bevy_core" version="0.5.0" name="Timer")}} struct now internally uses {{rust_docs(type="struct" crate="std" mod="time" name="Duration" plural=true)}} 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