Mirrors/bevy
2
0
Fork 0
mirror of https://github.com/bevyengine/bevy synced 2024-11-24 13:43:04 +00:00
Code Issues Projects Releases Packages Wiki Activity
bevy/Cargo.toml

3882 lines
101 KiB
TOML
Raw Permalink Normal View History

initial commit
2019-11-13 03:36:02 +00:00
[package]
name = "bevy"
Bump Version after Release (#14219) Bump version after release This PR has been auto-generated Co-authored-by: Bevy Auto Releaser <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: François Mockers <mockersf@gmail.com>
2024-07-08 12:54:08 +00:00
version = "0.15.0-dev"
Update to edition 2021 on master (#3028) Objective During work on #3009 I've found that not all jobs use actions-rs, and therefore, an previous version of Rust is used for them. So while compilation and other stuff can pass, checking markup and Android build may fail with compilation errors. Solution This PR adds `action-rs` for any job running cargo, and updates the edition to 2021.
2021-10-27 00:12:14 +00:00
edition = "2021"
Add bevy_dylib to force dynamic linking of bevy (#808) This easily improve compilation time by 2x
2020-11-10 03:26:08 +00:00
categories = ["game-engines", "graphics", "gui", "rendering"]
add crate metadata
2020-08-10 00:24:27 +00:00
description = "A refreshingly simple data-driven game engine and app framework"
Do not bundle the assets from wasm example in the crate (#4895) # Objective - Fix #4881 ## Solution - Do not bundle the assets from wasm example in the crate; tested with `cargo package` to check the produced crate
2022-06-01 23:05:30 +00:00
exclude = ["assets/", "tools/", ".github/", "crates/", "examples/wasm/assets/"]
add crate metadata
2020-08-10 00:24:27 +00:00
homepage = "https://bevyengine.org"
keywords = ["game", "engine", "gamedev", "graphics", "bevy"]
Relicense Bevy under the dual MIT or Apache-2.0 license (#2509) This relicenses Bevy under the dual MIT or Apache-2.0 license. For rationale, see #2373. * Changes the LICENSE file to describe the dual license. Moved the MIT license to docs/LICENSE-MIT. Added the Apache-2.0 license to docs/LICENSE-APACHE. I opted for this approach over dumping both license files at the root (the more common approach) for a number of reasons: * Github links to the "first" license file (LICENSE-APACHE) in its license links (you can see this in the wgpu and rust-analyzer repos). People clicking these links might erroneously think that the apache license is the only option. Rust and Amethyst both use COPYRIGHT or COPYING files to solve this problem, but this creates more file noise (if you do everything at the root) and the naming feels way less intuitive. * People have a reflex to look for a LICENSE file. By providing a single license file at the root, we make it easy for them to understand our licensing approach. * I like keeping the root clean and noise free * There is precedent for putting the apache and mit license text in sub folders (amethyst) * Removed the `Copyright (c) 2020 Carter Anderson` copyright notice from the MIT license. I don't care about this attribution, it might make license compliance more difficult in some cases, and it didn't properly attribute other contributors. We shoudn't replace it with something like "Copyright (c) 2021 Bevy Contributors" because "Bevy Contributors" is not a legal entity. Instead, we just won't include the copyright line (which has precedent ... Rust also uses this approach). * Updates crates to use the new "MIT OR Apache-2.0" license value * Removes the old legion-transform license file from bevy_transform. bevy_transform has been its own, fully custom implementation for a long time and that license no longer applies. * Added a License section to the main readme * Updated our Bevy Plugin licensing guidelines. As a follow-up we should update the website to properly describe the new license. Closes #2373
2021-07-23 21:11:51 +00:00
license = "MIT OR Apache-2.0"
Add bevy_dylib to force dynamic linking of bevy (#808) This easily improve compilation time by 2x
2020-11-10 03:26:08 +00:00
repository = "https://github.com/bevyengine/bevy"
Add docs link to root `Cargo.toml` (#10998) The `documentation` key was missing from the root `Cargo.toml`, which means crates.io doesn't display a documentation link from the search page. <img width="523" alt="image" src="https://github.com/bevyengine/bevy/assets/6706944/96247a72-168f-47f4-ab35-287c06bb9b30">
2023-12-16 22:51:35 +00:00
documentation = "https://docs.rs/bevy"
Make some associated functions of `Color` const (#16091) # Objective Make the following functions `const` that will be useful to define colors as constants. - `Color::srgb_from_array` - `Color::srgba_u8` - `Color::srgb_u8` The last two require Rust 1.82.0. ## Solution - Make them `const` - Change MSRV to 1.82.0 ## Testing I tested bevy_color only. My machine does not have enough RAM capacity to test the whole bevy. `cargo test -p bevy_color`
2024-10-28 03:26:35 +00:00
rust-version = "1.82.0"
Add bevy_dylib to force dynamic linking of bevy (#808) This easily improve compilation time by 2x
2020-11-10 03:26:08 +00:00
[workspace]
Make ktx2 and zstd default features (#7696) # Objective - Environment maps use these formats, and in the future rendering LUTs will need textures loaded by default in the engine ## Solution - Make ktx2 and zstd part of the default feature - Let examples assume these features are enabled --- ## Changelog - `ktx2` and `zstd` are now party of bevy's default enabled features ## Migration Guide - If you used the `ktx2` or `zstd` features, you no longer need to explicitly enable them, as they are now part of bevy's default enabled features
2023-02-17 01:00:07 +00:00
exclude = [
"benches",
Move compile fail tests (#13196) # Objective - Follow-up of #13184 :) - We use `ui_test` to test compiler errors for our custom macros. - There are four crates related to compile fail tests - `bevy_ecs_compile_fail_tests`, `bevy_macros_compile_fail_tests`, and `bevy_reflect_compile_fail_tests`, which actually test the macros. - [`bevy_compile_test_utils`](https://github.com/bevyengine/bevy/tree/64c1c65783938facc59d9b36cbaa6deba435d84e/crates/bevy_compile_test_utils), which provides helpers and common patterns for these tests. - All of these crates reside within the `crates` directory. - This can be confusing, especially for newcomers. All of the other folders in `crates` are actual published libraries, except for these 4. ## Solution - Move all compile fail tests to a `compile_fail` folder under their corresponding crate. - E.g. `crates/bevy_ecs_compile_fail_tests` would be moved to `crates/bevy_ecs/compile_fail`. - Move `bevy_compile_test_utils` to `tools/compile_fail_utils`. There are a few benefits to this approach: 1. An internal testing detail is less intrusive (and confusing) for those who just want to browse the public Bevy interface. 2. Follows a pre-existing approach of organizing related crates inside a larger crate's folder. - See `bevy_gizmos/macros` for an example. 4. Makes consistent the terms `compile_test`, `compile_fail`, and `compile_fail_test` in code. It's all just `compile_fail` now, because we are specifically testing the error messages on compiler failures. - To be clear it can still be referred to by these terms in comments and speech, just the names of the crates and the CI command are now consistent. ## Testing Run the compile fail CI command: ```shell cargo run -p ci -- compile-fail ``` If it still passes, then my refactor was successful.
2024-05-03 13:35:21 +00:00
"crates/bevy_derive/compile_fail",
"crates/bevy_ecs/compile_fail",
"crates/bevy_reflect/compile_fail",
Update compile test to use ui_test 0.23 (#13245) # Objective Closes #13241 ## Solution Update test utils to use `ui_test` 0.23.0. ## Testing - Run compile tests for bevy_ecs. cc @BD103
2024-05-05 22:17:56 +00:00
"tools/compile_fail_utils",
Make ktx2 and zstd default features (#7696) # Objective - Environment maps use these formats, and in the future rendering LUTs will need textures loaded by default in the engine ## Solution - Make ktx2 and zstd part of the default feature - Let examples assume these features are enabled --- ## Changelog - `ktx2` and `zstd` are now party of bevy's default enabled features ## Migration Guide - If you used the `ktx2` or `zstd` features, you no longer need to explicitly enable them, as they are now part of bevy's default enabled features
2023-02-17 01:00:07 +00:00
]
add a 3d lines example (#5319) # Objective - Showcase how to use a `Material` and `Mesh` to spawn 3d lines ![image](https://user-images.githubusercontent.com/8348954/179034236-ebc07f90-3eb5-46cc-8fc1-be7e6bf983fb.png) ## Solution - Add an example using a simple `Material` and `Mesh` definition to draw a 3d line - Shows how to use `LineList` and `LineStrip` in combination with a specialized `Material` ## Notes This isn't just a primitive shape because it needs a special Material, but I think it's a good showcase of the power of the `Material` and `AsBindGroup` abstractions. All of this is easy to figure out when you know these options are a thing, but I think they are hard to discover which is why I think this should be an example and not shipped with bevy. Co-authored-by: Charles <IceSentry@users.noreply.github.com>
2022-07-15 22:37:05 +00:00
members = [
"crates/*",
IOS, Android... same thing (#7493) # Objective - Merge the examples on iOS and Android - Make sure they both work from the same code ## Solution - don't create window when not in an active state (from #6830) - exit on suspend on Android (from #6830) - automatically enable dependency feature of bevy_audio on android so that it works out of the box - don't inverse y position of touch events - reuse the same example for both Android and iOS Fixes #4616 Fixes #4103 Fixes #3648 Fixes #3458 Fixes #3249 Fixes #86
2023-02-06 18:08:49 +00:00
"examples/mobile",
add a 3d lines example (#5319) # Objective - Showcase how to use a `Material` and `Mesh` to spawn 3d lines ![image](https://user-images.githubusercontent.com/8348954/179034236-ebc07f90-3eb5-46cc-8fc1-be7e6bf983fb.png) ## Solution - Add an example using a simple `Material` and `Mesh` definition to draw a 3d line - Shows how to use `LineList` and `LineStrip` in combination with a specialized `Material` ## Notes This isn't just a primitive shape because it needs a special Material, but I think it's a good showcase of the power of the `Material` and `AsBindGroup` abstractions. All of this is easy to figure out when you know these options are a thing, but I think they are hard to discover which is why I think this should be an example and not shipped with bevy. Co-authored-by: Charles <IceSentry@users.noreply.github.com>
2022-07-15 22:37:05 +00:00
"tools/ci",
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
"tools/build-templated-pages",
add a 3d lines example (#5319) # Objective - Showcase how to use a `Material` and `Mesh` to spawn 3d lines ![image](https://user-images.githubusercontent.com/8348954/179034236-ebc07f90-3eb5-46cc-8fc1-be7e6bf983fb.png) ## Solution - Add an example using a simple `Material` and `Mesh` definition to draw a 3d line - Shows how to use `LineList` and `LineStrip` in combination with a specialized `Material` ## Notes This isn't just a primitive shape because it needs a special Material, but I think it's a good showcase of the power of the `Material` and `AsBindGroup` abstractions. All of this is easy to figure out when you know these options are a thing, but I think they are hard to discover which is why I think this should be an example and not shipped with bevy. Co-authored-by: Charles <IceSentry@users.noreply.github.com>
2022-07-15 22:37:05 +00:00
"tools/build-wasm-example",
new example showcase tool (#8561) # Objective - Replace the `example_showcase.sh` script - Helper tool to prepare the example page on the website ## Solution - Have a command to run all the examples: `cargo run -p example-showcase -- run` - Have a command to take screenshots of all examples: `cargo run -p example-showcase -- run --screenshot` - Have a command to build the markdown files for the website: `cargo run -p example-showcase -- build-website-list --content-folder content` - Have a command to build all the examples in wasm/WebGPU: `cargo run -p example-showcase -- build-web-gpu-examples --content-folder webgpus` (with `--website-hacks` to enable the hacks for the Bevy website: canvas id, resizing and loading bar) This is the first step to an improved example page (all examples marked as wasm, uses the card layout, has screenshots, reuse name, category and description from the metadata). As one of the goal is to have a page with WebGPU examples before the official release, this is not touching the example page for now but targeting a new one. <img width="1912" alt="Screenshot 2023-05-06 at 17 16 25" src="https://user-images.githubusercontent.com/8672791/236632744-4372c95f-c50a-4168-973f-349412548f33.png">
2023-05-08 19:02:06 +00:00
"tools/example-showcase",
add a 3d lines example (#5319) # Objective - Showcase how to use a `Material` and `Mesh` to spawn 3d lines ![image](https://user-images.githubusercontent.com/8348954/179034236-ebc07f90-3eb5-46cc-8fc1-be7e6bf983fb.png) ## Solution - Add an example using a simple `Material` and `Mesh` definition to draw a 3d line - Shows how to use `LineList` and `LineStrip` in combination with a specialized `Material` ## Notes This isn't just a primitive shape because it needs a special Material, but I think it's a good showcase of the power of the `Material` and `AsBindGroup` abstractions. All of this is easy to figure out when you know these options are a thing, but I think they are hard to discover which is why I think this should be an example and not shipped with bevy. Co-authored-by: Charles <IceSentry@users.noreply.github.com>
2022-07-15 22:37:05 +00:00
"errors",
]
initial commit
2019-11-13 03:36:02 +00:00
Add [lints] table, fix adding `#![allow(clippy::type_complexity)]` everywhere (#10011) # Objective - Fix adding `#![allow(clippy::type_complexity)]` everywhere. like #9796 ## Solution - Use the new [lints] table that will land in 1.74 (https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#lints) - inherit lint to the workspace, crates and examples. ``` [lints] workspace = true ``` ## Changelog - Bump rust version to 1.74 - Enable lints table for the workspace ```toml [workspace.lints.clippy] type_complexity = "allow" ``` - Allow type complexity for all crates and examples ```toml [lints] workspace = true ``` --------- Co-authored-by: Martín Maita <47983254+mnmaita@users.noreply.github.com>
2023-11-18 20:58:48 +00:00
[workspace.lints.clippy]
Add doc_markdown clippy linting config to cargo workspace (#10640) # Objective Partially Addresses #10612 fix: add clippy::doc_markdown linting to cargo workspace Rather than do all the warnings in `tools/ci/src/main.rs` in one-shot, just wanted to have an initial pr adding the first one to get the form correct as some may trigger build errors and require changes to get merged more easily. ## Solution - adding the doc_markdown and removing it from the ci check as it'll now be a build error during normal compilation. --------- Co-authored-by: François <mockersf@gmail.com>
2023-11-21 01:17:11 +00:00
doc_markdown = "warn"
Add `clippy::manual_let_else` at warn level to lints (#10684) # Objective Related to #10612. Enable the [`clippy::manual_let_else`](https://rust-lang.github.io/rust-clippy/master/#manual_let_else) lint as a warning. The `let else` form seems more idiomatic to me than a `match`/`if else` that either match a pattern or diverge, and from the clippy doc, the lint doesn't seem to have any possible false positive. ## Solution Add the lint as warning in `Cargo.toml`, refactor places where the lint triggers.
2023-11-28 04:15:27 +00:00
manual_let_else = "warn"
Move remaining clippy lint definitions to Cargo.toml (#10672) # Objective Partially addresses #10612 After moving the initial docs_markdown warning, this is a PR that moves the rest of the CI clippy lint definitions to the cargo.toml. ## Solution - the `tools/ci/src/main.rs` clippy lints removed and just the warning flag remains. - the warnings moved to the root cargo workspace toml.
2023-11-28 04:12:48 +00:00
match_same_arms = "warn"
Apply Clippy lints regarding lazy evaluation and closures (#14015) # Objective - Lazily evaluate [default](https://rust-lang.github.io/rust-clippy/master/index.html#/unwrap_or_default)~~/[or](https://rust-lang.github.io/rust-clippy/master/index.html#/or_fun_call)~~ values where it makes sense - ~~`unwrap_or(foo())` -> `unwrap_or_else(|| foo())`~~ - `unwrap_or(Default::default())` -> `unwrap_or_default()` - etc. - Avoid creating [redundant closures](https://rust-lang.github.io/rust-clippy/master/index.html#/redundant_closure), even for [method calls](https://rust-lang.github.io/rust-clippy/master/index.html#/redundant_closure_for_method_calls) - `map(|something| something.into())` -> `map(Into:into)` ## Solution - Apply Clippy lints: - ~~[or_fun_call](https://rust-lang.github.io/rust-clippy/master/index.html#/or_fun_call)~~ - [unwrap_or_default](https://rust-lang.github.io/rust-clippy/master/index.html#/unwrap_or_default) - [redundant_closure_for_method_calls](https://rust-lang.github.io/rust-clippy/master/index.html#/redundant_closure_for_method_calls) ([redundant closures](https://rust-lang.github.io/rust-clippy/master/index.html#/redundant_closure) is already enabled) ## Testing - Tested on Windows 11 (`stable-x86_64-pc-windows-gnu`, 1.79.0) - Bevy compiles without errors or warnings and examples seem to work as intended - `cargo clippy` ✅ - `cargo run -p ci -- compile` ✅ --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2024-07-01 15:54:40 +00:00
redundant_closure_for_method_calls = "warn"
Apply unused_qualifications lint (#14828) # Objective Fixes #14782 ## Solution Enable the lint and fix all upcoming hints (`--fix`). Also tried to figure out the false-positive (see review comment). Maybe split this PR up into multiple parts where only the last one enables the lint, so some can already be merged resulting in less many files touched / less potential for merge conflicts? Currently, there are some cases where it might be easier to read the code with the qualifier, so perhaps remove the import of it and adapt its cases? In the current stage it's just a plain adoption of the suggestions in order to have a base to discuss. ## Testing `cargo clippy` and `cargo run -p ci` are happy.
2024-08-21 12:29:33 +00:00
redundant_else = "warn"
semicolon_if_nothing_returned = "warn"
type_complexity = "allow"
undocumented_unsafe_blocks = "warn"
Apply Clippy lints regarding lazy evaluation and closures (#14015) # Objective - Lazily evaluate [default](https://rust-lang.github.io/rust-clippy/master/index.html#/unwrap_or_default)~~/[or](https://rust-lang.github.io/rust-clippy/master/index.html#/or_fun_call)~~ values where it makes sense - ~~`unwrap_or(foo())` -> `unwrap_or_else(|| foo())`~~ - `unwrap_or(Default::default())` -> `unwrap_or_default()` - etc. - Avoid creating [redundant closures](https://rust-lang.github.io/rust-clippy/master/index.html#/redundant_closure), even for [method calls](https://rust-lang.github.io/rust-clippy/master/index.html#/redundant_closure_for_method_calls) - `map(|something| something.into())` -> `map(Into:into)` ## Solution - Apply Clippy lints: - ~~[or_fun_call](https://rust-lang.github.io/rust-clippy/master/index.html#/or_fun_call)~~ - [unwrap_or_default](https://rust-lang.github.io/rust-clippy/master/index.html#/unwrap_or_default) - [redundant_closure_for_method_calls](https://rust-lang.github.io/rust-clippy/master/index.html#/redundant_closure_for_method_calls) ([redundant closures](https://rust-lang.github.io/rust-clippy/master/index.html#/redundant_closure) is already enabled) ## Testing - Tested on Windows 11 (`stable-x86_64-pc-windows-gnu`, 1.79.0) - Bevy compiles without errors or warnings and examples seem to work as intended - `cargo clippy` ✅ - `cargo run -p ci -- compile` ✅ --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2024-07-01 15:54:40 +00:00
unwrap_or_default = "warn"
Disable lint that interferes with rust beta CI compatibility (#16199) # Objective Fix our CI with rust beta ## Solution Disable new lint ## Testing Ran `cargo +nightly clippy`.
2024-11-10 14:42:29 +00:00
needless_lifetimes = "allow"
Add [lints] table, fix adding `#![allow(clippy::type_complexity)]` everywhere (#10011) # Objective - Fix adding `#![allow(clippy::type_complexity)]` everywhere. like #9796 ## Solution - Use the new [lints] table that will land in 1.74 (https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#lints) - inherit lint to the workspace, crates and examples. ``` [lints] workspace = true ``` ## Changelog - Bump rust version to 1.74 - Enable lints table for the workspace ```toml [workspace.lints.clippy] type_complexity = "allow" ``` - Allow type complexity for all crates and examples ```toml [lints] workspace = true ``` --------- Co-authored-by: Martín Maita <47983254+mnmaita@users.noreply.github.com>
2023-11-18 20:58:48 +00:00
Replace pointer castings (`as`) by their API equivalent (#11818) # Objective Since rust `1.76`, [`ptr::from_ref`](https://doc.rust-lang.org/stable/std/ptr/fn.from_ref.html) and [`ptr::from_mut`](https://doc.rust-lang.org/stable/std/ptr/fn.from_mut.html) are stable. This PR replaces code that use `as` casting by one of `ptr::from_ref`, `ptr::from_mut`, `cast_mut`, `cast_const`, or `cast` methods, which are less error-prone. ## Solution - Bump MSRV to `1.76.0` - Enables the following clippy lints: - [`ptr_as_ptr`](https://rust-lang.github.io/rust-clippy/master/index.html#/ptr_as_ptr) - [`ptr_cast_constness`](https://rust-lang.github.io/rust-clippy/master/index.html#/ptr_cast_constness) - [`ref_as_ptr`](https://rust-lang.github.io/rust-clippy/master/index.html#/ref_as_ptr) (I fix all warnings for this one, but it requires rust 1.77 to be enabled) - Fix the lints mentioned above
2024-02-11 23:19:36 +00:00
ptr_as_ptr = "warn"
ptr_cast_constness = "warn"
Enable `clippy::ref_as_ptr` (#12918) # Objective - [`clippy::ref_as_ptr`](https://rust-lang.github.io/rust-clippy/master/index.html#/ref_as_ptr) prevents you from directly casting references to pointers, requiring you to use `std::ptr::from_ref` instead. This prevents you from accidentally converting an immutable reference into a mutable pointer (`&x as *mut T`). - Follow up to #11818, now that our [`rust-version` is 1.77](https://github.com/bevyengine/bevy/blob/11817f4ba4cca8e956c50f6d919e38f601ecc5cf/Cargo.toml#L14). ## Solution - Enable lint and fix all warnings.
2024-04-10 20:16:48 +00:00
ref_as_ptr = "warn"
Replace pointer castings (`as`) by their API equivalent (#11818) # Objective Since rust `1.76`, [`ptr::from_ref`](https://doc.rust-lang.org/stable/std/ptr/fn.from_ref.html) and [`ptr::from_mut`](https://doc.rust-lang.org/stable/std/ptr/fn.from_mut.html) are stable. This PR replaces code that use `as` casting by one of `ptr::from_ref`, `ptr::from_mut`, `cast_mut`, `cast_const`, or `cast` methods, which are less error-prone. ## Solution - Bump MSRV to `1.76.0` - Enables the following clippy lints: - [`ptr_as_ptr`](https://rust-lang.github.io/rust-clippy/master/index.html#/ptr_as_ptr) - [`ptr_cast_constness`](https://rust-lang.github.io/rust-clippy/master/index.html#/ptr_cast_constness) - [`ref_as_ptr`](https://rust-lang.github.io/rust-clippy/master/index.html#/ref_as_ptr) (I fix all warnings for this one, but it requires rust 1.77 to be enabled) - Fix the lints mentioned above
2024-02-11 23:19:36 +00:00
Simpler lint fixes: makes `ci lints` work but disables a lint for now (#15376) Takes the first two commits from #15375 and adds suggestions from this comment: https://github.com/bevyengine/bevy/pull/15375#issuecomment-2366968300 See #15375 for more reasoning/motivation. ## Rebasing (rerunning) ```rust git switch simpler-lint-fixes git reset --hard main cargo fmt --all -- --unstable-features --config normalize_comments=true,imports_granularity=Crate cargo fmt --all git add --update git commit --message "rustfmt" cargo clippy --workspace --all-targets --all-features --fix cargo fmt --all -- --unstable-features --config normalize_comments=true,imports_granularity=Crate cargo fmt --all git add --update git commit --message "clippy" git cherry-pick e6c0b94f6795222310fb812fa5c4512661fc7887 ```
2024-09-24 11:42:59 +00:00
# see: https://github.com/bevyengine/bevy/pull/15375#issuecomment-2366966219
too_long_first_doc_paragraph = "allow"
Add `core` and `alloc` over `std` Lints (#15281) # Objective - Fixes #6370 - Closes #6581 ## Solution - Added the following lints to the workspace: - `std_instead_of_core` - `std_instead_of_alloc` - `alloc_instead_of_core` - Used `cargo +nightly fmt` with [item level use formatting](https://rust-lang.github.io/rustfmt/?version=v1.6.0&search=#Item%5C%3A) to split all `use` statements into single items. - Used `cargo clippy --workspace --all-targets --all-features --fix --allow-dirty` to _attempt_ to resolve the new linting issues, and intervened where the lint was unable to resolve the issue automatically (usually due to needing an `extern crate alloc;` statement in a crate root). - Manually removed certain uses of `std` where negative feature gating prevented `--all-features` from finding the offending uses. - Used `cargo +nightly fmt` with [crate level use formatting](https://rust-lang.github.io/rustfmt/?version=v1.6.0&search=#Crate%5C%3A) to re-merge all `use` statements matching Bevy's previous styling. - Manually fixed cases where the `fmt` tool could not re-merge `use` statements due to conditional compilation attributes. ## Testing - Ran CI locally ## Migration Guide The MSRV is now 1.81. Please update to this version or higher. ## Notes - This is a _massive_ change to try and push through, which is why I've outlined the semi-automatic steps I used to create this PR, in case this fails and someone else tries again in the future. - Making this change has no impact on user code, but does mean Bevy contributors will be warned to use `core` and `alloc` instead of `std` where possible. - This lint is a critical first step towards investigating `no_std` options for Bevy. --------- Co-authored-by: François Mockers <francois.mockers@vleue.com>
2024-09-27 00:59:59 +00:00
std_instead_of_core = "warn"
std_instead_of_alloc = "warn"
alloc_instead_of_core = "warn"
Enable the `unsafe_op_in_unsafe_fn` lint (#11591) # Objective - Partial fix of #11590 ## Solution - Enable `unsafe_op_in_unsafe_fn` at workspace level - Fix the lint for most of the crates
2024-01-28 23:18:11 +00:00
[workspace.lints.rust]
Inverse `missing_docs` logic (#11676) # Objective Currently the `missing_docs` lint is allowed-by-default and enabled at crate level when their documentations is complete (see #3492). This PR proposes to inverse this logic by making `missing_docs` warn-by-default and mark crates with imcomplete docs allowed. ## Solution Makes `missing_docs` warn at workspace level and allowed at crate level when the docs is imcomplete.
2024-02-03 21:40:55 +00:00
missing_docs = "warn"
Use `#[doc(fake_variadic)]` to improve docs readability (#14703) # Objective - Fixes #14697 ## Solution This PR modifies the existing `all_tuples!` macro to optionally accept a `#[doc(fake_variadic)]` attribute in its input. If the attribute is present, each invocation of the impl macro gets the correct attributes (i.e. the first impl receives `#[doc(fake_variadic)]` while the other impls are hidden using `#[doc(hidden)]`. Impls for the empty tuple (unit type) are left untouched (that's what the [standard library](https://doc.rust-lang.org/std/cmp/trait.PartialEq.html#impl-PartialEq-for-()) and [serde](https://docs.rs/serde/latest/serde/trait.Serialize.html#impl-Serialize-for-()) do). To work around https://github.com/rust-lang/cargo/issues/8811 and to get impls on re-exports to correctly show up as variadic, `--cfg docsrs_dep` is passed when building the docs for the toplevel `bevy` crate. `#[doc(fake_variadic)]` only works on tuples and fn pointers, so impls for structs like `AnyOf<(T1, T2, ..., Tn)>` are unchanged. ## Testing I built the docs locally using `RUSTDOCFLAGS='--cfg docsrs' RUSTFLAGS='--cfg docsrs_dep' cargo +nightly doc --no-deps --workspace` and checked the documentation page of a trait both in its original crate and the re-exported version in `bevy`. The description should correctly mention for how many tuple items the trait is implemented. I added `rustc-args` for docs.rs to the `bevy` crate, I hope there aren't any other notable crates that re-export `#[doc(fake_variadic)]` traits. --- ## Showcase `bevy_ecs::query::QueryData`: <img width="1015" alt="Screenshot 2024-08-12 at 16 41 28" src="https://github.com/user-attachments/assets/d40136ed-6731-475f-91a0-9df255cd24e3"> `bevy::ecs::query::QueryData` (re-export): <img width="1005" alt="Screenshot 2024-08-12 at 16 42 57" src="https://github.com/user-attachments/assets/71d44cf0-0ab0-48b0-9a51-5ce332594e12"> ## Original Description <details> Resolves #14697 Submitting as a draft for now, very WIP. Unfortunately, the docs don't show the variadics nicely when looking at reexported items. For example: `bevy_ecs::bundle::Bundle` correctly shows the variadic impl: ![image](https://github.com/user-attachments/assets/90bf8af1-1d1f-4714-9143-cdd3d0199998) while `bevy::ecs::bundle::Bundle` (the reexport) shows all the impls (not good): ![image](https://github.com/user-attachments/assets/439c428e-f712-465b-bec2-481f7bf5870b) Built using `RUSTDOCFLAGS='--cfg docsrs' cargo +nightly doc --workspace --no-deps` (`--no-deps` because of wgpu-core). Maybe I missed something or this is a limitation in the *totally not private* `#[doc(fake_variadic)]` thingy. In any case I desperately need some sleep now :)) </details>
2024-08-12 18:54:33 +00:00
unexpected_cfgs = { level = "warn", check-cfg = ['cfg(docsrs_dep)'] }
Apply unused_qualifications lint (#14828) # Objective Fixes #14782 ## Solution Enable the lint and fix all upcoming hints (`--fix`). Also tried to figure out the false-positive (see review comment). Maybe split this PR up into multiple parts where only the last one enables the lint, so some can already be merged resulting in less many files touched / less potential for merge conflicts? Currently, there are some cases where it might be easier to read the code with the qualifier, so perhaps remove the import of it and adapt its cases? In the current stage it's just a plain adoption of the suggestions in order to have a base to discuss. ## Testing `cargo clippy` and `cargo run -p ci` are happy.
2024-08-21 12:29:33 +00:00
unsafe_code = "deny"
unsafe_op_in_unsafe_fn = "warn"
unused_qualifications = "warn"
Enable the `unsafe_op_in_unsafe_fn` lint (#11591) # Objective - Partial fix of #11590 ## Solution - Enable `unsafe_op_in_unsafe_fn` at workspace level - Fix the lint for most of the crates
2024-01-28 23:18:11 +00:00
Add `core` and `alloc` over `std` Lints (#15281) # Objective - Fixes #6370 - Closes #6581 ## Solution - Added the following lints to the workspace: - `std_instead_of_core` - `std_instead_of_alloc` - `alloc_instead_of_core` - Used `cargo +nightly fmt` with [item level use formatting](https://rust-lang.github.io/rustfmt/?version=v1.6.0&search=#Item%5C%3A) to split all `use` statements into single items. - Used `cargo clippy --workspace --all-targets --all-features --fix --allow-dirty` to _attempt_ to resolve the new linting issues, and intervened where the lint was unable to resolve the issue automatically (usually due to needing an `extern crate alloc;` statement in a crate root). - Manually removed certain uses of `std` where negative feature gating prevented `--all-features` from finding the offending uses. - Used `cargo +nightly fmt` with [crate level use formatting](https://rust-lang.github.io/rustfmt/?version=v1.6.0&search=#Crate%5C%3A) to re-merge all `use` statements matching Bevy's previous styling. - Manually fixed cases where the `fmt` tool could not re-merge `use` statements due to conditional compilation attributes. ## Testing - Ran CI locally ## Migration Guide The MSRV is now 1.81. Please update to this version or higher. ## Notes - This is a _massive_ change to try and push through, which is why I've outlined the semi-automatic steps I used to create this PR, in case this fails and someone else tries again in the future. - Making this change has no impact on user code, but does mean Bevy contributors will be warned to use `core` and `alloc` instead of `std` where possible. - This lint is a critical first step towards investigating `no_std` options for Bevy. --------- Co-authored-by: François Mockers <francois.mockers@vleue.com>
2024-09-27 00:59:59 +00:00
# Unfortunately, cargo does not currently support overriding workspace lints
# inside a particular crate. See https://github.com/rust-lang/cargo/issues/13157
#
# We require an override for cases like `std_instead_of_core`, which are intended
# for the library contributors and not for how users should consume Bevy.
# To ensure examples aren't subject to these lints, below is a duplication of the
# workspace lints, with the "overrides" applied.
#
# [lints]
# workspace = true
[lints.clippy]
doc_markdown = "warn"
manual_let_else = "warn"
match_same_arms = "warn"
redundant_closure_for_method_calls = "warn"
redundant_else = "warn"
semicolon_if_nothing_returned = "warn"
type_complexity = "allow"
undocumented_unsafe_blocks = "warn"
unwrap_or_default = "warn"
Disable lint that interferes with rust beta CI compatibility (#16199) # Objective Fix our CI with rust beta ## Solution Disable new lint ## Testing Ran `cargo +nightly clippy`.
2024-11-10 14:42:29 +00:00
needless_lifetimes = "allow"
Add `core` and `alloc` over `std` Lints (#15281) # Objective - Fixes #6370 - Closes #6581 ## Solution - Added the following lints to the workspace: - `std_instead_of_core` - `std_instead_of_alloc` - `alloc_instead_of_core` - Used `cargo +nightly fmt` with [item level use formatting](https://rust-lang.github.io/rustfmt/?version=v1.6.0&search=#Item%5C%3A) to split all `use` statements into single items. - Used `cargo clippy --workspace --all-targets --all-features --fix --allow-dirty` to _attempt_ to resolve the new linting issues, and intervened where the lint was unable to resolve the issue automatically (usually due to needing an `extern crate alloc;` statement in a crate root). - Manually removed certain uses of `std` where negative feature gating prevented `--all-features` from finding the offending uses. - Used `cargo +nightly fmt` with [crate level use formatting](https://rust-lang.github.io/rustfmt/?version=v1.6.0&search=#Crate%5C%3A) to re-merge all `use` statements matching Bevy's previous styling. - Manually fixed cases where the `fmt` tool could not re-merge `use` statements due to conditional compilation attributes. ## Testing - Ran CI locally ## Migration Guide The MSRV is now 1.81. Please update to this version or higher. ## Notes - This is a _massive_ change to try and push through, which is why I've outlined the semi-automatic steps I used to create this PR, in case this fails and someone else tries again in the future. - Making this change has no impact on user code, but does mean Bevy contributors will be warned to use `core` and `alloc` instead of `std` where possible. - This lint is a critical first step towards investigating `no_std` options for Bevy. --------- Co-authored-by: François Mockers <francois.mockers@vleue.com>
2024-09-27 00:59:59 +00:00
ptr_as_ptr = "warn"
ptr_cast_constness = "warn"
ref_as_ptr = "warn"
too_long_first_doc_paragraph = "allow"
std_instead_of_core = "allow"
std_instead_of_alloc = "allow"
alloc_instead_of_core = "allow"
[lints.rust]
missing_docs = "warn"
unexpected_cfgs = { level = "warn", check-cfg = ['cfg(docsrs_dep)'] }
unsafe_code = "deny"
unsafe_op_in_unsafe_fn = "warn"
unused_qualifications = "warn"
Add [lints] table, fix adding `#![allow(clippy::type_complexity)]` everywhere (#10011) # Objective - Fix adding `#![allow(clippy::type_complexity)]` everywhere. like #9796 ## Solution - Use the new [lints] table that will land in 1.74 (https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#lints) - inherit lint to the workspace, crates and examples. ``` [lints] workspace = true ``` ## Changelog - Bump rust version to 1.74 - Enable lints table for the workspace ```toml [workspace.lints.clippy] type_complexity = "allow" ``` - Allow type complexity for all crates and examples ```toml [lints] workspace = true ``` --------- Co-authored-by: Martín Maita <47983254+mnmaita@users.noreply.github.com>
2023-11-18 20:58:48 +00:00
make wgpu renderer optional
2020-03-11 05:20:49 +00:00
[features]
Feature to disable libloading (#363) esp. helpful for wasm target Made default only for `bevy` crate
2020-09-02 00:02:11 +00:00
default = [
Feature-gate all image formats (#15586) # Objective Bevy supports feature gates for each format it supports, but several formats that it loads via the `image` crate do not have feature gates. Additionally, the QOI format is supported by the `image` crate and wasn't available at all. This fixes that. ## Solution The following feature gates are added: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `qoi` * `tiff` None of these formats are enabled by default, despite the fact that all these formats appeared to be enabled by default before. Since `default-features` was disabled for the `image` crate, it's likely that using any of these formats would have errored by default before this change, although this probably needs additional testing. ## Testing The changes seemed minimal enough that a compile test would be sufficient. ## Migration guide Image formats that previously weren't feature-gated are now feature-gated, meaning they will have to be enabled if you use them: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `tiff` Additionally, the `qoi` feature has been added to support loading QOI format images. Previously, these formats appeared in the enum by default, but weren't actually enabled via the `image` crate, potentially resulting in weird bugs. Now, you should be able to add these features to your projects to support them properly.
2024-10-07 16:37:45 +00:00
"android-game-activity",
"android-game-activity",
"android_shared_stdcxx",
animation player (#4375) # Objective - Add a basic animation player - Single track - Not generic, can only animate `Transform`s - With plenty of possible optimisations available - Close-ish to https://github.com/bevyengine/rfcs/pull/49 - https://discord.com/channels/691052431525675048/774027865020039209/958820063148929064 ## Solution - Can play animations - looping or not - Can pause animations - Can seek in animation - Can alter speed of animation - I also removed the previous gltf animation example https://user-images.githubusercontent.com/8672791/161051887-e79283f0-9803-448a-93d0-5f7a62acb02d.mp4
2022-04-02 22:36:02 +00:00
"animation",
Lighter no default features (#5447) # Objective - Even though it's marked as optional, it is no longer possible to not depend on `bevy_render` as it's a dependency of `bevy_scene` ## Solution - Make `bevy_scene` optional - For the minimalist among us, also make `bevy_asset` optional
2022-07-25 15:48:14 +00:00
"bevy_asset",
Add bevy_dylib to force dynamic linking of bevy (#808) This easily improve compilation time by 2x
2020-11-10 03:26:08 +00:00
"bevy_audio",
Define a prelude for bevy_color, and add it to bevy_internal (#12158) # Objective As we start to migrate to `bevy_color` in earnest (#12056), we should make it visible to Bevy users, and usable in examples. ## Solution 1. Add a prelude to `bevy_color`: I've only excluded the rarely used `ColorRange` type and the testing-focused color distance module. I definitely think that some color spaces are less useful than others to end users, but at the same time the types used there are very unlikely to conflict with user-facing types. 2. Add `bevy_color` to `bevy_internal` as an optional crate. 3. Re-export `bevy_color`'s prelude as part of `bevy::prelude`. --------- Co-authored-by: Alice Cecile <alice.i.cecil@gmail.com>
2024-02-27 17:04:56 +00:00
"bevy_color",
Remove `render` feature group (#6912) # Objective The feature doesn't have any use case in libraries or applications and many users use this feature incorrectly. See the issue for details. Closes #5753. ## Solution Remove it. --- ## Changelog ### Removed - `render` feature group. ## Migration Guide Instead of using `render` feature group use dependencies directly. This group consisted of `bevy_core_pipeline`, `bevy_pbr`, `bevy_gltf`, `bevy_render`, `bevy_sprite`, `bevy_text` and `bevy_ui`. You probably want to check if you need all of them.
2022-12-11 18:46:46 +00:00
"bevy_core_pipeline",
Feature-gate all image formats (#15586) # Objective Bevy supports feature gates for each format it supports, but several formats that it loads via the `image` crate do not have feature gates. Additionally, the QOI format is supported by the `image` crate and wasn't available at all. This fixes that. ## Solution The following feature gates are added: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `qoi` * `tiff` None of these formats are enabled by default, despite the fact that all these formats appeared to be enabled by default before. Since `default-features` was disabled for the `image` crate, it's likely that using any of these formats would have errored by default before this change, although this probably needs additional testing. ## Testing The changes seemed minimal enough that a compile test would be sufficient. ## Migration guide Image formats that previously weren't feature-gated are now feature-gated, meaning they will have to be enabled if you use them: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `tiff` Additionally, the `qoi` feature has been added to support loading QOI format images. Previously, these formats appeared in the enum by default, but weren't actually enabled via the `image` crate, potentially resulting in weird bugs. Now, you should be able to add these features to your projects to support them properly.
2024-10-07 16:37:45 +00:00
"bevy_gilrs",
"bevy_gizmos",
"bevy_gltf",
Add mesh picking backend and `MeshRayCast` system parameter (#15800) # Objective Closes #15545. `bevy_picking` supports UI and sprite picking, but not mesh picking. Being able to pick meshes would be extremely useful for various games, tools, and our own examples, as well as scene editors and inspectors. So, we need a mesh picking backend! Luckily, [`bevy_mod_picking`](https://github.com/aevyrie/bevy_mod_picking) (which `bevy_picking` is based on) by @aevyrie already has a [backend for it](https://github.com/aevyrie/bevy_mod_picking/blob/74f0c3c0fbc8048632ba46fd8f14e26aaea9c76c/backends/bevy_picking_raycast/src/lib.rs) using [`bevy_mod_raycast`](https://github.com/aevyrie/bevy_mod_raycast). As a side product of adding mesh picking, we also get support for performing ray casts on meshes! ## Solution Upstream a large chunk of the immediate-mode ray casting functionality from `bevy_mod_raycast`, and add a mesh picking backend based on `bevy_mod_picking`. Huge thanks to @aevyrie who did all the hard work on these incredible crates! All meshes are pickable by default. Picking can be disabled for individual entities by adding `PickingBehavior::IGNORE`, like normal. Or, if you want mesh picking to be entirely opt-in, you can set `MeshPickingBackendSettings::require_markers` to `true` and add a `RayCastPickable` component to the desired camera and target entities. You can also use the new `MeshRayCast` system parameter to cast rays into the world manually: ```rust fn ray_cast_system(mut ray_cast: MeshRayCast, foo_query: Query<(), With<Foo>>) { let ray = Ray3d::new(Vec3::ZERO, Dir3::X); // Only ray cast against entities with the `Foo` component. let filter = |entity| foo_query.contains(entity); // Never early-exit. Note that you can change behavior per-entity. let early_exit_test = |_entity| false; // Ignore the visibility of entities. This allows ray casting hidden entities. let visibility = RayCastVisibility::Any; let settings = RayCastSettings::default() .with_filter(&filter) .with_early_exit_test(&early_exit_test) .with_visibility(visibility); // Cast the ray with the settings, returning a list of intersections. let hits = ray_cast.cast_ray(ray, &settings); } ``` This is largely a direct port, but I did make several changes to match our APIs better, remove things we don't need or that I think are unnecessary, and do some general improvements to code quality and documentation. ### Changes Relative to `bevy_mod_raycast` and `bevy_mod_picking` - Every `Raycast` and "raycast" has been renamed to `RayCast` and "ray cast" (similar reasoning as the "Naming" section in #15724) - `Raycast` system param has been renamed to `MeshRayCast` to avoid naming conflicts and to be explicit that it is not for colliders - `RaycastBackend` has been renamed to `MeshPickingBackend` - `RayCastVisibility` variants are now `Any`, `Visible`, and `VisibleInView` instead of `Ignore`, `MustBeVisible`, and `MustBeVisibleAndInView` - `NoBackfaceCulling` has been renamed to `RayCastBackfaces`, to avoid implying that it affects the rendering of backfaces for meshes (it doesn't) - `SimplifiedMesh` and `RayCastBackfaces` live near other ray casting API types, not in their own 10 LoC module - All intersection logic and types are in the same `intersections` module, not split across several modules - Some intersection types have been renamed to be clearer and more consistent - `IntersectionData` -> `RayMeshHit` - `RayHit` -> `RayTriangleHit` - General documentation and code quality improvements ### Removed / Not Ported - Removed unused ray helpers and types, like `PrimitiveIntersection` - Removed getters on intersection types, and made their properties public - There is no `2d` feature, and `Raycast::mesh_query` and `Raycast::mesh2d_query` have been merged into `MeshRayCast::mesh_query`, which handles both 2D and 3D - I assume this existed previously because `Mesh2dHandle` used to be in `bevy_sprite`. Now both the 2D and 3D mesh are in `bevy_render`. - There is no `debug` feature or ray debug rendering - There is no deferred API (`RaycastSource`) - There is no `CursorRayPlugin` (the picking backend handles this) ### Note for Reviewers In case it's helpful, the [first commit](https://github.com/bevyengine/bevy/commit/281638ef10ebd25f783bee2533509fdf756f7ab4) here is essentially a one-to-one port. The rest of the commits are primarily refactoring and cleaning things up in the ways listed earlier, as well as changes to the module structure. It may also be useful to compare the original [picking backend](https://github.com/aevyrie/bevy_mod_picking/blob/74f0c3c0fbc8048632ba46fd8f14e26aaea9c76c/backends/bevy_picking_raycast/src/lib.rs) and [`bevy_mod_raycast`](https://github.com/aevyrie/bevy_mod_raycast) to this PR. Feel free to mention if there are any changes that I should revert or something I should not include in this PR. ## Testing I tested mesh picking and relevant components in some examples, for both 2D and 3D meshes, and added a new `mesh_picking` example. I also ~~stole~~ ported over the [ray-mesh intersection benchmark](https://github.com/aevyrie/bevy_mod_raycast/blob/dbc5ef32fe48997a1a7eeec7434d9dd8b829e52e/benches/ray_mesh_intersection.rs) from `bevy_mod_raycast`. --- ## Showcase Below is a version of the `2d_shapes` example modified to demonstrate 2D mesh picking. This is not included in this PR. https://github.com/user-attachments/assets/7742528c-8630-4c00-bacd-81576ac432bf And below is the new `mesh_picking` example: https://github.com/user-attachments/assets/b65c7a5a-fa3a-4c2d-8bbd-e7a2c772986e There is also a really cool new `mesh_ray_cast` example ported over from `bevy_mod_raycast`: https://github.com/user-attachments/assets/3c5eb6c0-bd94-4fb0-bec6-8a85668a06c9 --------- Co-authored-by: Aevyrie <aevyrie@gmail.com> Co-authored-by: Trent <2771466+tbillington@users.noreply.github.com> Co-authored-by: François Mockers <mockersf@gmail.com>
2024-10-13 17:24:19 +00:00
"bevy_mesh_picking_backend",
Remove `render` feature group (#6912) # Objective The feature doesn't have any use case in libraries or applications and many users use this feature incorrectly. See the issue for details. Closes #5753. ## Solution Remove it. --- ## Changelog ### Removed - `render` feature group. ## Migration Guide Instead of using `render` feature group use dependencies directly. This group consisted of `bevy_core_pipeline`, `bevy_pbr`, `bevy_gltf`, `bevy_render`, `bevy_sprite`, `bevy_text` and `bevy_ui`. You probably want to check if you need all of them.
2022-12-11 18:46:46 +00:00
"bevy_pbr",
Upstream `CorePlugin` from `bevy_mod_picking` (#13677) # Objective This is the first of a series of PRs intended to begin the upstreaming process for `bevy_mod_picking`. The purpose of this PR is to: + Create the new `bevy_picking` crate + Upstream `CorePlugin` as `PickingPlugin` + Upstream the core pointer and backend abstractions. This code has been ported verbatim from the corresponding files in [bevy_picking_core](https://github.com/aevyrie/bevy_mod_picking/tree/main/crates/bevy_picking_core/src) with a few tiny naming and docs tweaks. The work here is only an initial foothold to get the up-streaming process started in earnest. We can do refactoring and improvements once this is in-tree. --------- Co-authored-by: Aevyrie <aevyrie@gmail.com> Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2024-06-15 11:59:57 +00:00
"bevy_picking",
Feature-gate all image formats (#15586) # Objective Bevy supports feature gates for each format it supports, but several formats that it loads via the `image` crate do not have feature gates. Additionally, the QOI format is supported by the `image` crate and wasn't available at all. This fixes that. ## Solution The following feature gates are added: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `qoi` * `tiff` None of these formats are enabled by default, despite the fact that all these formats appeared to be enabled by default before. Since `default-features` was disabled for the `image` crate, it's likely that using any of these formats would have errored by default before this change, although this probably needs additional testing. ## Testing The changes seemed minimal enough that a compile test would be sufficient. ## Migration guide Image formats that previously weren't feature-gated are now feature-gated, meaning they will have to be enabled if you use them: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `tiff` Additionally, the `qoi` feature has been added to support loading QOI format images. Previously, these formats appeared in the enum by default, but weren't actually enabled via the `image` crate, potentially resulting in weird bugs. Now, you should be able to add these features to your projects to support them properly.
2024-10-07 16:37:45 +00:00
"bevy_remote",
Remove `render` feature group (#6912) # Objective The feature doesn't have any use case in libraries or applications and many users use this feature incorrectly. See the issue for details. Closes #5753. ## Solution Remove it. --- ## Changelog ### Removed - `render` feature group. ## Migration Guide Instead of using `render` feature group use dependencies directly. This group consisted of `bevy_core_pipeline`, `bevy_pbr`, `bevy_gltf`, `bevy_render`, `bevy_sprite`, `bevy_text` and `bevy_ui`. You probably want to check if you need all of them.
2022-12-11 18:46:46 +00:00
"bevy_render",
Feature-gate all image formats (#15586) # Objective Bevy supports feature gates for each format it supports, but several formats that it loads via the `image` crate do not have feature gates. Additionally, the QOI format is supported by the `image` crate and wasn't available at all. This fixes that. ## Solution The following feature gates are added: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `qoi` * `tiff` None of these formats are enabled by default, despite the fact that all these formats appeared to be enabled by default before. Since `default-features` was disabled for the `image` crate, it's likely that using any of these formats would have errored by default before this change, although this probably needs additional testing. ## Testing The changes seemed minimal enough that a compile test would be sufficient. ## Migration guide Image formats that previously weren't feature-gated are now feature-gated, meaning they will have to be enabled if you use them: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `tiff` Additionally, the `qoi` feature has been added to support loading QOI format images. Previously, these formats appeared in the enum by default, but weren't actually enabled via the `image` crate, potentially resulting in weird bugs. Now, you should be able to add these features to your projects to support them properly.
2024-10-07 16:37:45 +00:00
"bevy_scene",
Remove `render` feature group (#6912) # Objective The feature doesn't have any use case in libraries or applications and many users use this feature incorrectly. See the issue for details. Closes #5753. ## Solution Remove it. --- ## Changelog ### Removed - `render` feature group. ## Migration Guide Instead of using `render` feature group use dependencies directly. This group consisted of `bevy_core_pipeline`, `bevy_pbr`, `bevy_gltf`, `bevy_render`, `bevy_sprite`, `bevy_text` and `bevy_ui`. You probably want to check if you need all of them.
2022-12-11 18:46:46 +00:00
"bevy_sprite",
Feature-gate all image formats (#15586) # Objective Bevy supports feature gates for each format it supports, but several formats that it loads via the `image` crate do not have feature gates. Additionally, the QOI format is supported by the `image` crate and wasn't available at all. This fixes that. ## Solution The following feature gates are added: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `qoi` * `tiff` None of these formats are enabled by default, despite the fact that all these formats appeared to be enabled by default before. Since `default-features` was disabled for the `image` crate, it's likely that using any of these formats would have errored by default before this change, although this probably needs additional testing. ## Testing The changes seemed minimal enough that a compile test would be sufficient. ## Migration guide Image formats that previously weren't feature-gated are now feature-gated, meaning they will have to be enabled if you use them: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `tiff` Additionally, the `qoi` feature has been added to support loading QOI format images. Previously, these formats appeared in the enum by default, but weren't actually enabled via the `image` crate, potentially resulting in weird bugs. Now, you should be able to add these features to your projects to support them properly.
2024-10-07 16:37:45 +00:00
"bevy_sprite_picking_backend",
"bevy_state",
Remove `render` feature group (#6912) # Objective The feature doesn't have any use case in libraries or applications and many users use this feature incorrectly. See the issue for details. Closes #5753. ## Solution Remove it. --- ## Changelog ### Removed - `render` feature group. ## Migration Guide Instead of using `render` feature group use dependencies directly. This group consisted of `bevy_core_pipeline`, `bevy_pbr`, `bevy_gltf`, `bevy_render`, `bevy_sprite`, `bevy_text` and `bevy_ui`. You probably want to check if you need all of them.
2022-12-11 18:46:46 +00:00
"bevy_text",
"bevy_ui",
Feature-gate all image formats (#15586) # Objective Bevy supports feature gates for each format it supports, but several formats that it loads via the `image` crate do not have feature gates. Additionally, the QOI format is supported by the `image` crate and wasn't available at all. This fixes that. ## Solution The following feature gates are added: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `qoi` * `tiff` None of these formats are enabled by default, despite the fact that all these formats appeared to be enabled by default before. Since `default-features` was disabled for the `image` crate, it's likely that using any of these formats would have errored by default before this change, although this probably needs additional testing. ## Testing The changes seemed minimal enough that a compile test would be sufficient. ## Migration guide Image formats that previously weren't feature-gated are now feature-gated, meaning they will have to be enabled if you use them: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `tiff` Additionally, the `qoi` feature has been added to support loading QOI format images. Previously, these formats appeared in the enum by default, but weren't actually enabled via the `image` crate, potentially resulting in weird bugs. Now, you should be able to add these features to your projects to support them properly.
2024-10-07 16:37:45 +00:00
"bevy_ui_picking_backend",
Headless by features (#16401) # Objective - Fixes #16152 ## Solution - Put `bevy_window` and `bevy_a11y` behind the `bevy_window` feature. they were the only difference - Add `ScheduleRunnerPlugin` to the `DefaultPlugins` when `bevy_window` is disabled - Remove `HeadlessPlugins` - Update the `headless` example
2024-11-16 21:33:37 +00:00
"bevy_window",
Feature-gate all image formats (#15586) # Objective Bevy supports feature gates for each format it supports, but several formats that it loads via the `image` crate do not have feature gates. Additionally, the QOI format is supported by the `image` crate and wasn't available at all. This fixes that. ## Solution The following feature gates are added: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `qoi` * `tiff` None of these formats are enabled by default, despite the fact that all these formats appeared to be enabled by default before. Since `default-features` was disabled for the `image` crate, it's likely that using any of these formats would have errored by default before this change, although this probably needs additional testing. ## Testing The changes seemed minimal enough that a compile test would be sufficient. ## Migration guide Image formats that previously weren't feature-gated are now feature-gated, meaning they will have to be enabled if you use them: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `tiff` Additionally, the `qoi` feature has been added to support loading QOI format images. Previously, these formats appeared in the enum by default, but weren't actually enabled via the `image` crate, potentially resulting in weird bugs. Now, you should be able to add these features to your projects to support them properly.
2024-10-07 16:37:45 +00:00
"bevy_winit",
"custom_cursor",
"default_font",
"hdr",
multi_threaded feature rename (#12997) # Objective Fixes #12966 ## Solution Renaming multi_threaded feature to match snake case ## Migration Guide Bevy feature multi-threaded should be refered to multi_threaded from now on.
2024-05-06 20:49:32 +00:00
"multi_threaded",
Add bevy_dylib to force dynamic linking of bevy (#808) This easily improve compilation time by 2x
2020-11-10 03:26:08 +00:00
"png",
don't crash without features `bevy_pbr`, `ktx2`, `zstd` (#14020) # Objective - Fixes #13728 ## Solution - add a new feature `smaa_luts`. if enables, it also enables `ktx2` and `zstd`. if not, it doesn't load the files but use placeholders instead - adds all the resources needed in the same places that system that uses them are added.
2024-06-26 03:08:23 +00:00
"smaa_luts",
Make sysinfo diagnostic plugin optional (#12164) # Objective - Fixes https://github.com/bevyengine/bevy/issues/11929 - make sysinfo plugin optional ## Solution - added features to allow for conditional compilation --- ## Migration Guide - For users who disable default features of bevy and wish to enable the diagnostic plugin, add `sysinfo_plugin` to your bevy features list. --------- Co-authored-by: ebola <dev@axiomatic> Co-authored-by: François <mockersf@gmail.com>
2024-02-28 20:00:42 +00:00
"sysinfo_plugin",
Feature-gate all image formats (#15586) # Objective Bevy supports feature gates for each format it supports, but several formats that it loads via the `image` crate do not have feature gates. Additionally, the QOI format is supported by the `image` crate and wasn't available at all. This fixes that. ## Solution The following feature gates are added: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `qoi` * `tiff` None of these formats are enabled by default, despite the fact that all these formats appeared to be enabled by default before. Since `default-features` was disabled for the `image` crate, it's likely that using any of these formats would have errored by default before this change, although this probably needs additional testing. ## Testing The changes seemed minimal enough that a compile test would be sufficient. ## Migration guide Image formats that previously weren't feature-gated are now feature-gated, meaning they will have to be enabled if you use them: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `tiff` Additionally, the `qoi` feature has been added to support loading QOI format images. Previously, these formats appeared in the enum by default, but weren't actually enabled via the `image` crate, potentially resulting in weird bugs. Now, you should be able to add these features to your projects to support them properly.
2024-10-07 16:37:45 +00:00
"tonemapping_luts",
"vorbis",
"webgl2",
"x11",
Feature to disable libloading (#363) esp. helpful for wasm target Made default only for `bevy` crate
2020-09-02 00:02:11 +00:00
]
Use embedded glslang for runtime glsl-to-spirv and add Android example (#740) Use embedded glslang for runtime glsl-to-spirv and add Android example
2020-11-03 00:30:30 +00:00
Add mesh picking backend and `MeshRayCast` system parameter (#15800) # Objective Closes #15545. `bevy_picking` supports UI and sprite picking, but not mesh picking. Being able to pick meshes would be extremely useful for various games, tools, and our own examples, as well as scene editors and inspectors. So, we need a mesh picking backend! Luckily, [`bevy_mod_picking`](https://github.com/aevyrie/bevy_mod_picking) (which `bevy_picking` is based on) by @aevyrie already has a [backend for it](https://github.com/aevyrie/bevy_mod_picking/blob/74f0c3c0fbc8048632ba46fd8f14e26aaea9c76c/backends/bevy_picking_raycast/src/lib.rs) using [`bevy_mod_raycast`](https://github.com/aevyrie/bevy_mod_raycast). As a side product of adding mesh picking, we also get support for performing ray casts on meshes! ## Solution Upstream a large chunk of the immediate-mode ray casting functionality from `bevy_mod_raycast`, and add a mesh picking backend based on `bevy_mod_picking`. Huge thanks to @aevyrie who did all the hard work on these incredible crates! All meshes are pickable by default. Picking can be disabled for individual entities by adding `PickingBehavior::IGNORE`, like normal. Or, if you want mesh picking to be entirely opt-in, you can set `MeshPickingBackendSettings::require_markers` to `true` and add a `RayCastPickable` component to the desired camera and target entities. You can also use the new `MeshRayCast` system parameter to cast rays into the world manually: ```rust fn ray_cast_system(mut ray_cast: MeshRayCast, foo_query: Query<(), With<Foo>>) { let ray = Ray3d::new(Vec3::ZERO, Dir3::X); // Only ray cast against entities with the `Foo` component. let filter = |entity| foo_query.contains(entity); // Never early-exit. Note that you can change behavior per-entity. let early_exit_test = |_entity| false; // Ignore the visibility of entities. This allows ray casting hidden entities. let visibility = RayCastVisibility::Any; let settings = RayCastSettings::default() .with_filter(&filter) .with_early_exit_test(&early_exit_test) .with_visibility(visibility); // Cast the ray with the settings, returning a list of intersections. let hits = ray_cast.cast_ray(ray, &settings); } ``` This is largely a direct port, but I did make several changes to match our APIs better, remove things we don't need or that I think are unnecessary, and do some general improvements to code quality and documentation. ### Changes Relative to `bevy_mod_raycast` and `bevy_mod_picking` - Every `Raycast` and "raycast" has been renamed to `RayCast` and "ray cast" (similar reasoning as the "Naming" section in #15724) - `Raycast` system param has been renamed to `MeshRayCast` to avoid naming conflicts and to be explicit that it is not for colliders - `RaycastBackend` has been renamed to `MeshPickingBackend` - `RayCastVisibility` variants are now `Any`, `Visible`, and `VisibleInView` instead of `Ignore`, `MustBeVisible`, and `MustBeVisibleAndInView` - `NoBackfaceCulling` has been renamed to `RayCastBackfaces`, to avoid implying that it affects the rendering of backfaces for meshes (it doesn't) - `SimplifiedMesh` and `RayCastBackfaces` live near other ray casting API types, not in their own 10 LoC module - All intersection logic and types are in the same `intersections` module, not split across several modules - Some intersection types have been renamed to be clearer and more consistent - `IntersectionData` -> `RayMeshHit` - `RayHit` -> `RayTriangleHit` - General documentation and code quality improvements ### Removed / Not Ported - Removed unused ray helpers and types, like `PrimitiveIntersection` - Removed getters on intersection types, and made their properties public - There is no `2d` feature, and `Raycast::mesh_query` and `Raycast::mesh2d_query` have been merged into `MeshRayCast::mesh_query`, which handles both 2D and 3D - I assume this existed previously because `Mesh2dHandle` used to be in `bevy_sprite`. Now both the 2D and 3D mesh are in `bevy_render`. - There is no `debug` feature or ray debug rendering - There is no deferred API (`RaycastSource`) - There is no `CursorRayPlugin` (the picking backend handles this) ### Note for Reviewers In case it's helpful, the [first commit](https://github.com/bevyengine/bevy/commit/281638ef10ebd25f783bee2533509fdf756f7ab4) here is essentially a one-to-one port. The rest of the commits are primarily refactoring and cleaning things up in the ways listed earlier, as well as changes to the module structure. It may also be useful to compare the original [picking backend](https://github.com/aevyrie/bevy_mod_picking/blob/74f0c3c0fbc8048632ba46fd8f14e26aaea9c76c/backends/bevy_picking_raycast/src/lib.rs) and [`bevy_mod_raycast`](https://github.com/aevyrie/bevy_mod_raycast) to this PR. Feel free to mention if there are any changes that I should revert or something I should not include in this PR. ## Testing I tested mesh picking and relevant components in some examples, for both 2D and 3D meshes, and added a new `mesh_picking` example. I also ~~stole~~ ported over the [ray-mesh intersection benchmark](https://github.com/aevyrie/bevy_mod_raycast/blob/dbc5ef32fe48997a1a7eeec7434d9dd8b829e52e/benches/ray_mesh_intersection.rs) from `bevy_mod_raycast`. --- ## Showcase Below is a version of the `2d_shapes` example modified to demonstrate 2D mesh picking. This is not included in this PR. https://github.com/user-attachments/assets/7742528c-8630-4c00-bacd-81576ac432bf And below is the new `mesh_picking` example: https://github.com/user-attachments/assets/b65c7a5a-fa3a-4c2d-8bbd-e7a2c772986e There is also a really cool new `mesh_ray_cast` example ported over from `bevy_mod_raycast`: https://github.com/user-attachments/assets/3c5eb6c0-bd94-4fb0-bec6-8a85668a06c9 --------- Co-authored-by: Aevyrie <aevyrie@gmail.com> Co-authored-by: Trent <2771466+tbillington@users.noreply.github.com> Co-authored-by: François Mockers <mockersf@gmail.com>
2024-10-13 17:24:19 +00:00
# Provides an implementation for picking meshes
bevy_mesh_picking_backend = ["bevy_picking"]
feature gate picking backends (#15369) # Objective Fixes #15306 ## Solution - Add feature gate on the module and the place where each one is used - Declare the features and make them default ## Testing - CI
2024-09-22 19:35:15 +00:00
# Provides an implementation for picking sprites
bevy_sprite_picking_backend = ["bevy_picking"]
# Provides an implementation for picking ui
bevy_ui_picking_backend = ["bevy_picking"]
Add bevy_dylib to force dynamic linking of bevy (#808) This easily improve compilation time by 2x
2020-11-10 03:26:08 +00:00
# Force dynamic linking, which improves iterative compile times
Remove the bevy_dylib feature (#9516) # Objective There is a `bevy_dylib` feature that cargo automatically creates due to the bevy_dylib crate being optional. This can be a footgun as I think we want users to always use the `dynamic_linking` feature for this. For example `bevy_dylib` was used in [ridiculous_bevy_hot_reloading:lib.rs#L93](https://github.com/DGriffin91/ridiculous_bevy_hot_reloading/blob/400099bcc10f4ef974af491f55e8acefe273e4bc/src/lib.rs#L93) and since I was using dynamic_linking it ended up hot reloading with a slightly different configured library causing hot reloading to fail. ## Solution Use "dep:" syntax in the `dynamic_linking` feature to prevent bevy_dylib automatically becoming a cargo feature. This is documented here: https://doc.rust-lang.org/cargo/reference/features.html#optional-dependencies It will now raise this error when you try to compile with the bevy_dylib feature: > error: Package `bevy v0.12.0-dev (C:\Users\Paul\Projects\Rust\bevy)` does not have feature `bevy_dylib`. It has an optional dependency with that name, but that dependency uses the "dep:" syntax in the features table, so it does not have an implicit feature with that name. --- ## Changelog `bevy_dylib` is no longer a feature ## Migration Guide If you were using Bevy's `bevy_dylib` feature, use Bevy's `dynamic_linking` feature instead. ```shell # 0.11 cargo run --features bevy/bevy_dylib # 0.12 cargo run --features bevy/dynamic_linking ``` ```toml [dependencies] # 0.11 bevy = { version = "0.11", features = ["bevy_dylib"] } # 0.12 bevy = { version = "0.12", features = ["dynamic_linking"] } ```
2023-08-21 01:38:00 +00:00
dynamic_linking = ["dep:bevy_dylib", "bevy_internal/dynamic_linking"]
move dynamic plugin loading to its own optional crate (#544) move dynamic plugin loading to its own crate
2020-10-01 20:04:06 +00:00
Make sysinfo diagnostic plugin optional (#12164) # Objective - Fixes https://github.com/bevyengine/bevy/issues/11929 - make sysinfo plugin optional ## Solution - added features to allow for conditional compilation --- ## Migration Guide - For users who disable default features of bevy and wish to enable the diagnostic plugin, add `sysinfo_plugin` to your bevy features list. --------- Co-authored-by: ebola <dev@axiomatic> Co-authored-by: François <mockersf@gmail.com>
2024-02-28 20:00:42 +00:00
# Enables system information diagnostic plugin
sysinfo_plugin = ["bevy_internal/sysinfo_plugin"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# Provides animation functionality
Define a prelude for bevy_color, and add it to bevy_internal (#12158) # Objective As we start to migrate to `bevy_color` in earnest (#12056), we should make it visible to Bevy users, and usable in examples. ## Solution 1. Add a prelude to `bevy_color`: I've only excluded the rarely used `ColorRange` type and the testing-focused color distance module. I definitely think that some color spaces are less useful than others to end users, but at the same time the types used there are very unlikely to conflict with user-facing types. 2. Add `bevy_color` to `bevy_internal` as an optional crate. 3. Re-export `bevy_color`'s prelude as part of `bevy::prelude`. --------- Co-authored-by: Alice Cecile <alice.i.cecil@gmail.com>
2024-02-27 17:04:56 +00:00
bevy_animation = ["bevy_internal/bevy_animation", "bevy_color"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# Provides asset functionality
Lighter no default features (#5447) # Objective - Even though it's marked as optional, it is no longer possible to not depend on `bevy_render` as it's a dependency of `bevy_scene` ## Solution - Make `bevy_scene` optional - For the minimalist among us, also make `bevy_asset` optional
2022-07-25 15:48:14 +00:00
bevy_asset = ["bevy_internal/bevy_asset"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# Provides audio functionality
Add bevy_dylib to force dynamic linking of bevy (#808) This easily improve compilation time by 2x
2020-11-10 03:26:08 +00:00
bevy_audio = ["bevy_internal/bevy_audio"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
Define a prelude for bevy_color, and add it to bevy_internal (#12158) # Objective As we start to migrate to `bevy_color` in earnest (#12056), we should make it visible to Bevy users, and usable in examples. ## Solution 1. Add a prelude to `bevy_color`: I've only excluded the rarely used `ColorRange` type and the testing-focused color distance module. I definitely think that some color spaces are less useful than others to end users, but at the same time the types used there are very unlikely to conflict with user-facing types. 2. Add `bevy_color` to `bevy_internal` as an optional crate. 3. Re-export `bevy_color`'s prelude as part of `bevy::prelude`. --------- Co-authored-by: Alice Cecile <alice.i.cecil@gmail.com>
2024-02-27 17:04:56 +00:00
# Provides shared color types and operations
bevy_color = ["bevy_internal/bevy_color"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# Provides cameras and other basic render pipeline features
few fmt tweaks (#10264) few format tweaks, initially spotted working on https://github.com/bevyengine/bevy/pull/8745
2023-10-25 19:20:17 +00:00
bevy_core_pipeline = [
"bevy_internal/bevy_core_pipeline",
"bevy_asset",
"bevy_render",
]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# Adds gamepad support
Add bevy_dylib to force dynamic linking of bevy (#808) This easily improve compilation time by 2x
2020-11-10 03:26:08 +00:00
bevy_gilrs = ["bevy_internal/bevy_gilrs"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# [glTF](https://www.khronos.org/gltf/) support
Add depending bevy features for higher level one (#7855)
2023-03-14 14:10:50 +00:00
bevy_gltf = ["bevy_internal/bevy_gltf", "bevy_asset", "bevy_scene", "bevy_pbr"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# Adds PBR rendering
few fmt tweaks (#10264) few format tweaks, initially spotted working on https://github.com/bevyengine/bevy/pull/8745
2023-10-25 19:20:17 +00:00
bevy_pbr = [
"bevy_internal/bevy_pbr",
"bevy_asset",
"bevy_render",
"bevy_core_pipeline",
]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
Upstream `CorePlugin` from `bevy_mod_picking` (#13677) # Objective This is the first of a series of PRs intended to begin the upstreaming process for `bevy_mod_picking`. The purpose of this PR is to: + Create the new `bevy_picking` crate + Upstream `CorePlugin` as `PickingPlugin` + Upstream the core pointer and backend abstractions. This code has been ported verbatim from the corresponding files in [bevy_picking_core](https://github.com/aevyrie/bevy_mod_picking/tree/main/crates/bevy_picking_core/src) with a few tiny naming and docs tweaks. The work here is only an initial foothold to get the up-streaming process started in earnest. We can do refactoring and improvements once this is in-tree. --------- Co-authored-by: Aevyrie <aevyrie@gmail.com> Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2024-06-15 11:59:57 +00:00
# Provides picking functionality
bevy_picking = ["bevy_internal/bevy_picking"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# Provides rendering functionality
Define a prelude for bevy_color, and add it to bevy_internal (#12158) # Objective As we start to migrate to `bevy_color` in earnest (#12056), we should make it visible to Bevy users, and usable in examples. ## Solution 1. Add a prelude to `bevy_color`: I've only excluded the rarely used `ColorRange` type and the testing-focused color distance module. I definitely think that some color spaces are less useful than others to end users, but at the same time the types used there are very unlikely to conflict with user-facing types. 2. Add `bevy_color` to `bevy_internal` as an optional crate. 3. Re-export `bevy_color`'s prelude as part of `bevy::prelude`. --------- Co-authored-by: Alice Cecile <alice.i.cecil@gmail.com>
2024-02-27 17:04:56 +00:00
bevy_render = ["bevy_internal/bevy_render", "bevy_color"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# Provides scene functionality
Add depending bevy features for higher level one (#7855)
2023-03-14 14:10:50 +00:00
bevy_scene = ["bevy_internal/bevy_scene", "bevy_asset"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# Provides sprite functionality
Define a prelude for bevy_color, and add it to bevy_internal (#12158) # Objective As we start to migrate to `bevy_color` in earnest (#12056), we should make it visible to Bevy users, and usable in examples. ## Solution 1. Add a prelude to `bevy_color`: I've only excluded the rarely used `ColorRange` type and the testing-focused color distance module. I definitely think that some color spaces are less useful than others to end users, but at the same time the types used there are very unlikely to conflict with user-facing types. 2. Add `bevy_color` to `bevy_internal` as an optional crate. 3. Re-export `bevy_color`'s prelude as part of `bevy::prelude`. --------- Co-authored-by: Alice Cecile <alice.i.cecil@gmail.com>
2024-02-27 17:04:56 +00:00
bevy_sprite = [
"bevy_internal/bevy_sprite",
"bevy_render",
"bevy_core_pipeline",
"bevy_color",
feature gate picking backends (#15369) # Objective Fixes #15306 ## Solution - Add feature gate on the module and the place where each one is used - Declare the features and make them default ## Testing - CI
2024-09-22 19:35:15 +00:00
"bevy_sprite_picking_backend",
Define a prelude for bevy_color, and add it to bevy_internal (#12158) # Objective As we start to migrate to `bevy_color` in earnest (#12056), we should make it visible to Bevy users, and usable in examples. ## Solution 1. Add a prelude to `bevy_color`: I've only excluded the rarely used `ColorRange` type and the testing-focused color distance module. I definitely think that some color spaces are less useful than others to end users, but at the same time the types used there are very unlikely to conflict with user-facing types. 2. Add `bevy_color` to `bevy_internal` as an optional crate. 3. Re-export `bevy_color`'s prelude as part of `bevy::prelude`. --------- Co-authored-by: Alice Cecile <alice.i.cecil@gmail.com>
2024-02-27 17:04:56 +00:00
]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# Provides text functionality
Add missing dependencies to `bevy_text` feature (#8920) # Objective - Fixes #8918. - The app should not crash if only the `bevy_text` feature is enabled. ## Solution The `bevy_text` feature now depends on `bevy_asset` and `bevy_sprite`, because it uses resources from these crates.
2023-06-22 02:57:04 +00:00
bevy_text = ["bevy_internal/bevy_text", "bevy_asset", "bevy_sprite"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# A custom ECS-driven UI framework
few fmt tweaks (#10264) few format tweaks, initially spotted working on https://github.com/bevyengine/bevy/pull/8745
2023-10-25 19:20:17 +00:00
bevy_ui = [
"bevy_internal/bevy_ui",
"bevy_core_pipeline",
"bevy_text",
"bevy_sprite",
Define a prelude for bevy_color, and add it to bevy_internal (#12158) # Objective As we start to migrate to `bevy_color` in earnest (#12056), we should make it visible to Bevy users, and usable in examples. ## Solution 1. Add a prelude to `bevy_color`: I've only excluded the rarely used `ColorRange` type and the testing-focused color distance module. I definitely think that some color spaces are less useful than others to end users, but at the same time the types used there are very unlikely to conflict with user-facing types. 2. Add `bevy_color` to `bevy_internal` as an optional crate. 3. Re-export `bevy_color`'s prelude as part of `bevy::prelude`. --------- Co-authored-by: Alice Cecile <alice.i.cecil@gmail.com>
2024-02-27 17:04:56 +00:00
"bevy_color",
feature gate picking backends (#15369) # Objective Fixes #15306 ## Solution - Add feature gate on the module and the place where each one is used - Declare the features and make them default ## Testing - CI
2024-09-22 19:35:15 +00:00
"bevy_ui_picking_backend",
few fmt tweaks (#10264) few format tweaks, initially spotted working on https://github.com/bevyengine/bevy/pull/8745
2023-10-25 19:20:17 +00:00
]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
Headless by features (#16401) # Objective - Fixes #16152 ## Solution - Put `bevy_window` and `bevy_a11y` behind the `bevy_window` feature. they were the only difference - Add `ScheduleRunnerPlugin` to the `DefaultPlugins` when `bevy_window` is disabled - Remove `HeadlessPlugins` - Update the `headless` example
2024-11-16 21:33:37 +00:00
# Windowing layer
bevy_window = ["bevy_internal/bevy_window"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# winit window and input backend
Add bevy_dylib to force dynamic linking of bevy (#808) This easily improve compilation time by 2x
2020-11-10 03:26:08 +00:00
bevy_winit = ["bevy_internal/bevy_winit"]
Immediate Mode Line/Gizmo Drawing (#6529) # Objective Add a convenient immediate mode drawing API for visual debugging. Fixes #5619 Alternative to #1625 Partial alternative to #5734 Based off https://github.com/Toqozz/bevy_debug_lines with some changes: * Simultaneous support for 2D and 3D. * Methods for basic shapes; circles, spheres, rectangles, boxes, etc. * 2D methods. * Removed durations. Seemed niche, and can be handled by users. <details> <summary>Performance</summary> Stress tested using Bevy's recommended optimization settings for the dev profile with the following command. ```bash cargo run --example many_debug_lines \ --config "profile.dev.package.\"*\".opt-level=3" \ --config "profile.dev.opt-level=1" ``` I dipped to 65-70 FPS at 300,000 lines CPU: 3700x RAM Speed: 3200 Mhz GPU: 2070 super - probably not very relevant, mostly cpu/memory bound </details> <details> <summary>Fancy bloom screenshot</summary> ![Screenshot_20230207_155033](https://user-images.githubusercontent.com/29694403/217291980-f1e0500e-7a14-4131-8c96-eaaaf52596ae.png) </details> ## Changelog * Added `GizmoPlugin` * Added `Gizmos` system parameter for drawing lines and wireshapes. ### TODO - [ ] Update changelog - [x] Update performance numbers - [x] Add credit to PR description ### Future work - Cache rendering primitives instead of constructing them out of line segments each frame. - Support for drawing solid meshes - Interactions. (See [bevy_mod_gizmos](https://github.com/LiamGallagher737/bevy_mod_gizmos)) - Fancier line drawing. (See [bevy_polyline](https://github.com/ForesightMiningSoftwareCorporation/bevy_polyline)) - Support for `RenderLayers` - Display gizmos for a certain duration. Currently everything displays for one frame (ie. immediate mode) - Changing settings per drawn item like drawing on top or drawing to different `RenderLayers` Co-Authored By: @lassade <felipe.jorge.pereira@gmail.com> Co-Authored By: @The5-1 <agaku@hotmail.de> Co-Authored By: @Toqozz <toqoz@hotmail.com> Co-Authored By: @nicopap <nico@nicopap.ch> --------- Co-authored-by: Robert Swain <robert.swain@gmail.com> Co-authored-by: IceSentry <c.giguere42@gmail.com> Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-03-20 20:57:54 +00:00
# Adds support for rendering gizmos
Define a prelude for bevy_color, and add it to bevy_internal (#12158) # Objective As we start to migrate to `bevy_color` in earnest (#12056), we should make it visible to Bevy users, and usable in examples. ## Solution 1. Add a prelude to `bevy_color`: I've only excluded the rarely used `ColorRange` type and the testing-focused color distance module. I definitely think that some color spaces are less useful than others to end users, but at the same time the types used there are very unlikely to conflict with user-facing types. 2. Add `bevy_color` to `bevy_internal` as an optional crate. 3. Re-export `bevy_color`'s prelude as part of `bevy::prelude`. --------- Co-authored-by: Alice Cecile <alice.i.cecil@gmail.com>
2024-02-27 17:04:56 +00:00
bevy_gizmos = ["bevy_internal/bevy_gizmos", "bevy_color"]
Immediate Mode Line/Gizmo Drawing (#6529) # Objective Add a convenient immediate mode drawing API for visual debugging. Fixes #5619 Alternative to #1625 Partial alternative to #5734 Based off https://github.com/Toqozz/bevy_debug_lines with some changes: * Simultaneous support for 2D and 3D. * Methods for basic shapes; circles, spheres, rectangles, boxes, etc. * 2D methods. * Removed durations. Seemed niche, and can be handled by users. <details> <summary>Performance</summary> Stress tested using Bevy's recommended optimization settings for the dev profile with the following command. ```bash cargo run --example many_debug_lines \ --config "profile.dev.package.\"*\".opt-level=3" \ --config "profile.dev.opt-level=1" ``` I dipped to 65-70 FPS at 300,000 lines CPU: 3700x RAM Speed: 3200 Mhz GPU: 2070 super - probably not very relevant, mostly cpu/memory bound </details> <details> <summary>Fancy bloom screenshot</summary> ![Screenshot_20230207_155033](https://user-images.githubusercontent.com/29694403/217291980-f1e0500e-7a14-4131-8c96-eaaaf52596ae.png) </details> ## Changelog * Added `GizmoPlugin` * Added `Gizmos` system parameter for drawing lines and wireshapes. ### TODO - [ ] Update changelog - [x] Update performance numbers - [x] Add credit to PR description ### Future work - Cache rendering primitives instead of constructing them out of line segments each frame. - Support for drawing solid meshes - Interactions. (See [bevy_mod_gizmos](https://github.com/LiamGallagher737/bevy_mod_gizmos)) - Fancier line drawing. (See [bevy_polyline](https://github.com/ForesightMiningSoftwareCorporation/bevy_polyline)) - Support for `RenderLayers` - Display gizmos for a certain duration. Currently everything displays for one frame (ie. immediate mode) - Changing settings per drawn item like drawing on top or drawing to different `RenderLayers` Co-Authored By: @lassade <felipe.jorge.pereira@gmail.com> Co-Authored By: @The5-1 <agaku@hotmail.de> Co-Authored By: @Toqozz <toqoz@hotmail.com> Co-Authored By: @nicopap <nico@nicopap.ch> --------- Co-authored-by: Robert Swain <robert.swain@gmail.com> Co-authored-by: IceSentry <c.giguere42@gmail.com> Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-03-20 20:57:54 +00:00
Add bevy_dev_tools crate (#11341) # Objective - Resolves #11309 ## Solution - Add `bevy_dev_tools` crate as a default feature. - Add `DevToolsPlugin` and add it to an app if the `bevy_dev_tools` feature is enabled. `bevy_dev_tools` is reserved by @alice-i-cecile, should we wait until it gets transferred to cart before merging? --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: BD103 <59022059+BD103@users.noreply.github.com>
2024-03-06 20:33:05 +00:00
# Provides a collection of developer tools
bevy_dev_tools = ["bevy_internal/bevy_dev_tools"]
Initial implementation of the Bevy Remote Protocol (Adopted) (#14880) # Objective Adopted from #13563. The goal is to implement the Bevy Remote Protocol over HTTP/JSON, allowing the ECS to be interacted with remotely. ## Solution At a high level, there are really two separate things that have been undertaken here: 1. First, `RemotePlugin` has been created, which has the effect of embedding a [JSON-RPC](https://www.jsonrpc.org/specification) endpoint into a Bevy application. 2. Second, the [Bevy Remote Protocol verbs](https://gist.github.com/coreh/1baf6f255d7e86e4be29874d00137d1d#file-bevy-remote-protocol-md) (excluding `POLL`) have been implemented as remote methods for that JSON-RPC endpoint under a Bevy-exclusive namespace (e.g. `bevy/get`, `bevy/list`, etc.). To avoid some repetition, here is the crate-level documentation, which explains the request/response structure, built-in-methods, and custom method configuration: <details> <summary>Click to view crate-level docs</summary> ```rust //! An implementation of the Bevy Remote Protocol over HTTP and JSON, to allow //! for remote control of a Bevy app. //! //! Adding the [`RemotePlugin`] to your [`App`] causes Bevy to accept //! connections over HTTP (by default, on port 15702) while your app is running. //! These *remote clients* can inspect and alter the state of the //! entity-component system. Clients are expected to `POST` JSON requests to the //! root URL; see the `client` example for a trivial example of use. //! //! The Bevy Remote Protocol is based on the JSON-RPC 2.0 protocol. //! //! ## Request objects //! //! A typical client request might look like this: //! //! ```json //! { //! "method": "bevy/get", //! "id": 0, //! "params": { //! "entity": 4294967298, //! "components": [ //! "bevy_transform::components::transform::Transform" //! ] //! } //! } //! ``` //! //! The `id` and `method` fields are required. The `param` field may be omitted //! for certain methods: //! //! * `id` is arbitrary JSON data. The server completely ignores its contents, //! and the client may use it for any purpose. It will be copied via //! serialization and deserialization (so object property order, etc. can't be //! relied upon to be identical) and sent back to the client as part of the //! response. //! //! * `method` is a string that specifies one of the possible [`BrpRequest`] //! variants: `bevy/query`, `bevy/get`, `bevy/insert`, etc. It's case-sensitive. //! //! * `params` is parameter data specific to the request. //! //! For more information, see the documentation for [`BrpRequest`]. //! [`BrpRequest`] is serialized to JSON via `serde`, so [the `serde` //! documentation] may be useful to clarify the correspondence between the Rust //! structure and the JSON format. //! //! ## Response objects //! //! A response from the server to the client might look like this: //! //! ```json //! { //! "jsonrpc": "2.0", //! "id": 0, //! "result": { //! "bevy_transform::components::transform::Transform": { //! "rotation": { "x": 0.0, "y": 0.0, "z": 0.0, "w": 1.0 }, //! "scale": { "x": 1.0, "y": 1.0, "z": 1.0 }, //! "translation": { "x": 0.0, "y": 0.5, "z": 0.0 } //! } //! } //! } //! ``` //! //! The `id` field will always be present. The `result` field will be present if the //! request was successful. Otherwise, an `error` field will replace it. //! //! * `id` is the arbitrary JSON data that was sent as part of the request. It //! will be identical to the `id` data sent during the request, modulo //! serialization and deserialization. If there's an error reading the `id` field, //! it will be `null`. //! //! * `result` will be present if the request succeeded and will contain the response //! specific to the request. //! //! * `error` will be present if the request failed and will contain an error object //! with more information about the cause of failure. //! //! ## Error objects //! //! An error object might look like this: //! //! ```json //! { //! "code": -32602, //! "message": "Missing \"entity\" field" //! } //! ``` //! //! The `code` and `message` fields will always be present. There may also be a `data` field. //! //! * `code` is an integer representing the kind of an error that happened. Error codes documented //! in the [`error_codes`] module. //! //! * `message` is a short, one-sentence human-readable description of the error. //! //! * `data` is an optional field of arbitrary type containing additional information about the error. //! //! ## Built-in methods //! //! The Bevy Remote Protocol includes a number of built-in methods for accessing and modifying data //! in the ECS. Each of these methods uses the `bevy/` prefix, which is a namespace reserved for //! BRP built-in methods. //! //! ### bevy/get //! //! Retrieve the values of one or more components from an entity. //! //! `params`: //! - `entity`: The ID of the entity whose components will be fetched. //! - `components`: An array of fully-qualified type names of components to fetch. //! //! `result`: A map associating each type name to its value on the requested entity. //! //! ### bevy/query //! //! Perform a query over components in the ECS, returning all matching entities and their associated //! component values. //! //! All of the arrays that comprise this request are optional, and when they are not provided, they //! will be treated as if they were empty. //! //! `params`: //! `params`: //! - `data`: //! - `components` (optional): An array of fully-qualified type names of components to fetch. //! - `option` (optional): An array of fully-qualified type names of components to fetch optionally. //! - `has` (optional): An array of fully-qualified type names of components whose presence will be //! reported as boolean values. //! - `filter` (optional): //! - `with` (optional): An array of fully-qualified type names of components that must be present //! on entities in order for them to be included in results. //! - `without` (optional): An array of fully-qualified type names of components that must *not* be //! present on entities in order for them to be included in results. //! //! `result`: An array, each of which is an object containing: //! - `entity`: The ID of a query-matching entity. //! - `components`: A map associating each type name from `components`/`option` to its value on the matching //! entity if the component is present. //! - `has`: A map associating each type name from `has` to a boolean value indicating whether or not the //! entity has that component. If `has` was empty or omitted, this key will be omitted in the response. //! //! ### bevy/spawn //! //! Create a new entity with the provided components and return the resulting entity ID. //! //! `params`: //! - `components`: A map associating each component's fully-qualified type name with its value. //! //! `result`: //! - `entity`: The ID of the newly spawned entity. //! //! ### bevy/destroy //! //! Despawn the entity with the given ID. //! //! `params`: //! - `entity`: The ID of the entity to be despawned. //! //! `result`: null. //! //! ### bevy/remove //! //! Delete one or more components from an entity. //! //! `params`: //! - `entity`: The ID of the entity whose components should be removed. //! - `components`: An array of fully-qualified type names of components to be removed. //! //! `result`: null. //! //! ### bevy/insert //! //! Insert one or more components into an entity. //! //! `params`: //! - `entity`: The ID of the entity to insert components into. //! - `components`: A map associating each component's fully-qualified type name with its value. //! //! `result`: null. //! //! ### bevy/reparent //! //! Assign a new parent to one or more entities. //! //! `params`: //! - `entities`: An array of entity IDs of entities that will be made children of the `parent`. //! - `parent` (optional): The entity ID of the parent to which the child entities will be assigned. //! If excluded, the given entities will be removed from their parents. //! //! `result`: null. //! //! ### bevy/list //! //! List all registered components or all components present on an entity. //! //! When `params` is not provided, this lists all registered components. If `params` is provided, //! this lists only those components present on the provided entity. //! //! `params` (optional): //! - `entity`: The ID of the entity whose components will be listed. //! //! `result`: An array of fully-qualified type names of components. //! //! ## Custom methods //! //! In addition to the provided methods, the Bevy Remote Protocol can be extended to include custom //! methods. This is primarily done during the initialization of [`RemotePlugin`], although the //! methods may also be extended at runtime using the [`RemoteMethods`] resource. //! //! ### Example //! ```ignore //! fn main() { //! App::new() //! .add_plugins(DefaultPlugins) //! .add_plugins( //! // `default` adds all of the built-in methods, while `with_method` extends them //! RemotePlugin::default() //! .with_method("super_user/cool_method".to_owned(), path::to::my::cool::handler) //! // ... more methods can be added by chaining `with_method` //! ) //! .add_systems( //! // ... standard application setup //! ) //! .run(); //! } //! ``` //! //! The handler is expected to be a system-convertible function which takes optional JSON parameters //! as input and returns a [`BrpResult`]. This means that it should have a type signature which looks //! something like this: //! ``` //! # use serde_json::Value; //! # use bevy_ecs::prelude::{In, World}; //! # use bevy_remote::BrpResult; //! fn handler(In(params): In<Option<Value>>, world: &mut World) -> BrpResult { //! todo!() //! } //! ``` //! //! Arbitrary system parameters can be used in conjunction with the optional `Value` input. The //! handler system will always run with exclusive `World` access. //! //! [the `serde` documentation]: https://serde.rs/ ``` </details> ### Message lifecycle At a high level, the lifecycle of client-server interactions is something like this: 1. The client sends one or more `BrpRequest`s. The deserialized version of that is just the Rust representation of a JSON-RPC request, and it looks like this: ```rust pub struct BrpRequest { /// The action to be performed. Parsing is deferred for the sake of error reporting. pub method: Option<Value>, /// Arbitrary data that will be returned verbatim to the client as part of /// the response. pub id: Option<Value>, /// The parameters, specific to each method. /// /// These are passed as the first argument to the method handler. /// Sometimes params can be omitted. pub params: Option<Value>, } ``` 2. These requests are accumulated in a mailbox resource (small lie but close enough). 3. Each update, the mailbox is drained by a system `process_remote_requests`, where each request is processed according to its `method`, which has an associated handler. Each handler is a Bevy system that runs with exclusive world access and returns a result; e.g.: ```rust pub fn process_remote_get_request(In(params): In<Option<Value>>, world: &World) -> BrpResult { // ... } ``` 4. The result (or an error) is reported back to the client. ## Testing This can be tested by using the `server` and `client` examples. The `client` example is not particularly exhaustive at the moment (it only creates barebones `bevy/query` requests) but is still informative. Other queries can be made using `curl` with the `server` example running. For example, to make a `bevy/list` request and list all registered components: ```bash curl -X POST -d '{ "jsonrpc": "2.0", "id": 1, "method": "bevy/list" }' 127.0.0.1:15702 | jq . ``` --- ## Future direction There were a couple comments on BRP versioning while this was in draft. I agree that BRP versioning is a good idea, but I think that it requires some consensus on a couple fronts: - First of all, what does the version actually mean? Is it a version for the protocol itself or for the `bevy/*` methods implemented using it? Both? - Where does the version actually live? The most natural place is just where we have `"jsonrpc"` right now (at least if it's versioning the protocol itself), but this means we're not actually conforming to JSON-RPC any more (so, for example, any client library used to construct JSON-RPC requests would stop working). I'm not really against that, but it's at least a real decision. - What do we actually do when we encounter mismatched versions? Adding handling for this would be actual scope creep instead of just a little add-on in my opinion. Another thing that would be nice is making the internal structure of the implementation less JSON-specific. Right now, for example, component values that will appear in server responses are quite eagerly converted to JSON `Value`s, which prevents disentangling the handler logic from the communication medium, but it can probably be done in principle and I imagine it would enable more code reuse (e.g. for custom method handlers) in addition to making the internals more readily usable for other formats. --------- Co-authored-by: Patrick Walton <pcwalton@mimiga.net> Co-authored-by: DragonGamesStudios <margos.michal@gmail.com> Co-authored-by: Christopher Biscardi <chris@christopherbiscardi.com> Co-authored-by: Gino Valente <49806985+MrGVSV@users.noreply.github.com>
2024-09-23 18:36:16 +00:00
# Enable the Bevy Remote Protocol
bevy_remote = ["bevy_internal/bevy_remote"]
Spirv passthrough main (adopted, part deux) (#15352) **Note:** This is an adoption of @Shfty 's adoption (#8131) of #3996! All I've done is updated the branch and run the docs CI. > **Note:** This is an adoption of #3996, originally authored by @molikto > > # Objective > Allow use of `wgpu::Features::SPIRV_SHADER_PASSTHROUGH` and the corresponding `wgpu::Device::create_shader_module_spirv` for SPIR-V shader assets. > > This enables use-cases where naga is not sufficient to load a given (valid) SPIR-V module, i.e. cases where naga lacks support for a given SPIR-V feature employed by a third-party codegen backend like `rust-gpu`. > > ## Solution > * Reimplemented the changes from [Spirv shader bypass #3996](https://github.com/bevyengine/bevy/pull/3996), on account of the original branch having been deleted. > * Documented the new `spirv_shader_passthrough` feature flag with the appropriate platform support context from [wgpu's documentation](https://docs.rs/wgpu/latest/wgpu/struct.Features.html#associatedconstant.SPIRV_SHADER_PASSTHROUGH). > > ## Changelog > * Adds a `spirv_shader_passthrough` feature flag to the following crates: > > * `bevy` > * `bevy_internal` > * `bevy_render` > * Extends `RenderDevice::create_shader_module` with a conditional call to `wgpu::Device::create_shader_module_spirv` if `spirv_shader_passthrough` is enabled and `wgpu::Features::SPIRV_SHADER_PASSTHROUGH` is present for the current platform. > * Documents the relevant `wgpu` platform support in `docs/cargo_features.md` --------- Co-authored-by: Josh Palmer <1253239+Shfty@users.noreply.github.com> Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2024-09-22 14:51:14 +00:00
# Enable passthrough loading for SPIR-V shaders (Only supported on Vulkan, shader capabilities and extensions must agree with the platform implementation)
spirv_shader_passthrough = ["bevy_internal/spirv_shader_passthrough"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# Tracing support, saving a file in Chrome Tracing format
Enable trace feature for subfeatures using it (#3337) # Objective - It isn't very useful to be able to enable feature `trace_chrome` on its own ## Solution - Enable `trace` feature when enabling `trace_chrome` or `trace_tracy` Co-authored-by: François <8672791+mockersf@users.noreply.github.com>
2021-12-18 00:09:22 +00:00
trace_chrome = ["trace", "bevy_internal/trace_chrome"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# Tracing support, exposing a port for Tracy
Enable trace feature for subfeatures using it (#3337) # Objective - It isn't very useful to be able to enable feature `trace_chrome` on its own ## Solution - Enable `trace` feature when enabling `trace_chrome` or `trace_tracy` Co-authored-by: François <8672791+mockersf@users.noreply.github.com>
2021-12-18 00:09:22 +00:00
trace_tracy = ["trace", "bevy_internal/trace_tracy"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
add a feature for memory tracing with tracy (#8272) # Objective - Expose a feature for tracing with Tracy to profile memory (https://docs.rs/tracy-client/0.15.2/tracy_client/struct.ProfiledAllocator.html) - This is a separate feature than just tracing as it can have an additional cost <img width="1912" alt="Screenshot 2023-03-30 at 08 39 49" src="https://user-images.githubusercontent.com/8672791/228985566-dd62fff8-1cbf-4f59-8a10-80c796daba0c.png">
2023-04-17 16:04:46 +00:00
# Tracing support, with memory profiling, exposing a port for Tracy
few fmt tweaks (#10264) few format tweaks, initially spotted working on https://github.com/bevyengine/bevy/pull/8745
2023-10-25 19:20:17 +00:00
trace_tracy_memory = [
"trace",
"bevy_internal/trace_tracy",
"bevy_internal/trace_tracy_memory",
]
add a feature for memory tracing with tracy (#8272) # Objective - Expose a feature for tracing with Tracy to profile memory (https://docs.rs/tracy-client/0.15.2/tracy_client/struct.ProfiledAllocator.html) - This is a separate feature than just tracing as it can have an additional cost <img width="1912" alt="Screenshot 2023-03-30 at 08 39 49" src="https://user-images.githubusercontent.com/8672791/228985566-dd62fff8-1cbf-4f59-8a10-80c796daba0c.png">
2023-04-17 16:04:46 +00:00
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# Tracing support
Add tracing spans to schedules, stages, systems (#789) Add tracing spans to schedules, stages, systems
2020-11-11 02:49:49 +00:00
trace = ["bevy_internal/trace"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
Feature-gate all image formats (#15586) # Objective Bevy supports feature gates for each format it supports, but several formats that it loads via the `image` crate do not have feature gates. Additionally, the QOI format is supported by the `image` crate and wasn't available at all. This fixes that. ## Solution The following feature gates are added: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `qoi` * `tiff` None of these formats are enabled by default, despite the fact that all these formats appeared to be enabled by default before. Since `default-features` was disabled for the `image` crate, it's likely that using any of these formats would have errored by default before this change, although this probably needs additional testing. ## Testing The changes seemed minimal enough that a compile test would be sufficient. ## Migration guide Image formats that previously weren't feature-gated are now feature-gated, meaning they will have to be enabled if you use them: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `tiff` Additionally, the `qoi` feature has been added to support loading QOI format images. Previously, these formats appeared in the enum by default, but weren't actually enabled via the `image` crate, potentially resulting in weird bugs. Now, you should be able to add these features to your projects to support them properly.
2024-10-07 16:37:45 +00:00
# Basis Universal compressed texture support
basis-universal = ["bevy_internal/basis-universal"]
# BMP image format support
bmp = ["bevy_internal/bmp"]
# DDS compressed texture support
dds = ["bevy_internal/dds"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# EXR image format support
Initial tonemapping options (#7594) # Objective Splits tone mapping from https://github.com/bevyengine/bevy/pull/6677 into a separate PR. Address https://github.com/bevyengine/bevy/issues/2264. Adds tone mapping options: - None: Bypasses tonemapping for instances where users want colors output to match those set. - Reinhard - Reinhard Luminance: Bevy's exiting tonemapping - [ACES](https://github.com/TheRealMJP/BakingLab/blob/master/BakingLab/ACES.hlsl) (Fitted version, based on the same implementation that Godot 4 uses) see https://github.com/bevyengine/bevy/issues/2264 - [AgX](https://github.com/sobotka/AgX) - SomewhatBoringDisplayTransform - TonyMcMapface - Blender Filmic This PR also adds support for EXR images so they can be used to compare tonemapping options with reference images. ## Migration Guide - Tonemapping is now an enum with NONE and the various tonemappers. - The DebandDither is now a separate component. Co-authored-by: JMS55 <47158642+JMS55@users.noreply.github.com>
2023-02-19 20:38:13 +00:00
exr = ["bevy_internal/exr"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
Feature-gate all image formats (#15586) # Objective Bevy supports feature gates for each format it supports, but several formats that it loads via the `image` crate do not have feature gates. Additionally, the QOI format is supported by the `image` crate and wasn't available at all. This fixes that. ## Solution The following feature gates are added: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `qoi` * `tiff` None of these formats are enabled by default, despite the fact that all these formats appeared to be enabled by default before. Since `default-features` was disabled for the `image` crate, it's likely that using any of these formats would have errored by default before this change, although this probably needs additional testing. ## Testing The changes seemed minimal enough that a compile test would be sufficient. ## Migration guide Image formats that previously weren't feature-gated are now feature-gated, meaning they will have to be enabled if you use them: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `tiff` Additionally, the `qoi` feature has been added to support loading QOI format images. Previously, these formats appeared in the enum by default, but weren't actually enabled via the `image` crate, potentially resulting in weird bugs. Now, you should be able to add these features to your projects to support them properly.
2024-10-07 16:37:45 +00:00
# Farbfeld image format support
ff = ["bevy_internal/ff"]
# GIF image format support
gif = ["bevy_internal/gif"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# HDR image format support
Add bevy_dylib to force dynamic linking of bevy (#808) This easily improve compilation time by 2x
2020-11-10 03:26:08 +00:00
hdr = ["bevy_internal/hdr"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
Feature-gate all image formats (#15586) # Objective Bevy supports feature gates for each format it supports, but several formats that it loads via the `image` crate do not have feature gates. Additionally, the QOI format is supported by the `image` crate and wasn't available at all. This fixes that. ## Solution The following feature gates are added: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `qoi` * `tiff` None of these formats are enabled by default, despite the fact that all these formats appeared to be enabled by default before. Since `default-features` was disabled for the `image` crate, it's likely that using any of these formats would have errored by default before this change, although this probably needs additional testing. ## Testing The changes seemed minimal enough that a compile test would be sufficient. ## Migration guide Image formats that previously weren't feature-gated are now feature-gated, meaning they will have to be enabled if you use them: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `tiff` Additionally, the `qoi` feature has been added to support loading QOI format images. Previously, these formats appeared in the enum by default, but weren't actually enabled via the `image` crate, potentially resulting in weird bugs. Now, you should be able to add these features to your projects to support them properly.
2024-10-07 16:37:45 +00:00
# KTX2 compressed texture support
ktx2 = ["bevy_internal/ktx2"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
Feature-gate all image formats (#15586) # Objective Bevy supports feature gates for each format it supports, but several formats that it loads via the `image` crate do not have feature gates. Additionally, the QOI format is supported by the `image` crate and wasn't available at all. This fixes that. ## Solution The following feature gates are added: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `qoi` * `tiff` None of these formats are enabled by default, despite the fact that all these formats appeared to be enabled by default before. Since `default-features` was disabled for the `image` crate, it's likely that using any of these formats would have errored by default before this change, although this probably needs additional testing. ## Testing The changes seemed minimal enough that a compile test would be sufficient. ## Migration guide Image formats that previously weren't feature-gated are now feature-gated, meaning they will have to be enabled if you use them: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `tiff` Additionally, the `qoi` feature has been added to support loading QOI format images. Previously, these formats appeared in the enum by default, but weren't actually enabled via the `image` crate, potentially resulting in weird bugs. Now, you should be able to add these features to your projects to support them properly.
2024-10-07 16:37:45 +00:00
# ICO image format support
ico = ["bevy_internal/ico"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# JPEG image format support
add ability to load `.dds`, `.tga`, and `.jpeg` texture formats (#1038) add ability to load `.dds`, `.tga`, and `.jpeg` texture formats
2020-12-10 02:34:27 +00:00
jpeg = ["bevy_internal/jpeg"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
Feature-gate all image formats (#15586) # Objective Bevy supports feature gates for each format it supports, but several formats that it loads via the `image` crate do not have feature gates. Additionally, the QOI format is supported by the `image` crate and wasn't available at all. This fixes that. ## Solution The following feature gates are added: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `qoi` * `tiff` None of these formats are enabled by default, despite the fact that all these formats appeared to be enabled by default before. Since `default-features` was disabled for the `image` crate, it's likely that using any of these formats would have errored by default before this change, although this probably needs additional testing. ## Testing The changes seemed minimal enough that a compile test would be sufficient. ## Migration guide Image formats that previously weren't feature-gated are now feature-gated, meaning they will have to be enabled if you use them: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `tiff` Additionally, the `qoi` feature has been added to support loading QOI format images. Previously, these formats appeared in the enum by default, but weren't actually enabled via the `image` crate, potentially resulting in weird bugs. Now, you should be able to add these features to your projects to support them properly.
2024-10-07 16:37:45 +00:00
# PNG image format support
png = ["bevy_internal/png"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
Feature-gate all image formats (#15586) # Objective Bevy supports feature gates for each format it supports, but several formats that it loads via the `image` crate do not have feature gates. Additionally, the QOI format is supported by the `image` crate and wasn't available at all. This fixes that. ## Solution The following feature gates are added: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `qoi` * `tiff` None of these formats are enabled by default, despite the fact that all these formats appeared to be enabled by default before. Since `default-features` was disabled for the `image` crate, it's likely that using any of these formats would have errored by default before this change, although this probably needs additional testing. ## Testing The changes seemed minimal enough that a compile test would be sufficient. ## Migration guide Image formats that previously weren't feature-gated are now feature-gated, meaning they will have to be enabled if you use them: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `tiff` Additionally, the `qoi` feature has been added to support loading QOI format images. Previously, these formats appeared in the enum by default, but weren't actually enabled via the `image` crate, potentially resulting in weird bugs. Now, you should be able to add these features to your projects to support them properly.
2024-10-07 16:37:45 +00:00
# PNM image format support, includes pam, pbm, pgm and ppm
pnm = ["bevy_internal/pnm"]
Added `WebP` image format support (#8220) # Objective WebP is a modern image format developed by Google that offers a significant reduction in file size compared to other image formats such as PNG and JPEG, while still maintaining good image quality. This makes it particularly useful for games with large numbers of images, such as those with high-quality textures or detailed sprites, where file size and loading times can have a significant impact on performance. By adding support for WebP images in Bevy, game developers using this engine can now take advantage of this modern image format and reduce the memory usage and loading times of their games. This improvement can ultimately result in a better gaming experience for players. In summary, the objective of adding WebP image format support in Bevy is to enable game developers to use a modern image format that provides better compression rates and smaller file sizes, resulting in faster loading times and reduced memory usage for their games. ## Solution To add support for WebP images in Bevy, this pull request leverages the existing `image` crate support for WebP. This implementation is easily integrated into the existing Bevy asset-loading system. To maintain compatibility with existing Bevy projects, WebP image support is disabled by default, and developers can enable it by adding a feature flag to their project's `Cargo.toml` file. With this feature, Bevy becomes even more versatile for game developers and provides a valuable addition to the game engine. --- ## Changelog - Added support for WebP image format in Bevy game engine ## Migration Guide To enable WebP image support in your Bevy project, add the following line to your project's Cargo.toml file: ```toml bevy = { version = "*", features = ["webp"]} ```
2023-03-28 19:53:55 +00:00
Feature-gate all image formats (#15586) # Objective Bevy supports feature gates for each format it supports, but several formats that it loads via the `image` crate do not have feature gates. Additionally, the QOI format is supported by the `image` crate and wasn't available at all. This fixes that. ## Solution The following feature gates are added: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `qoi` * `tiff` None of these formats are enabled by default, despite the fact that all these formats appeared to be enabled by default before. Since `default-features` was disabled for the `image` crate, it's likely that using any of these formats would have errored by default before this change, although this probably needs additional testing. ## Testing The changes seemed minimal enough that a compile test would be sufficient. ## Migration guide Image formats that previously weren't feature-gated are now feature-gated, meaning they will have to be enabled if you use them: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `tiff` Additionally, the `qoi` feature has been added to support loading QOI format images. Previously, these formats appeared in the enum by default, but weren't actually enabled via the `image` crate, potentially resulting in weird bugs. Now, you should be able to add these features to your projects to support them properly.
2024-10-07 16:37:45 +00:00
# QOI image format support
qoi = ["bevy_internal/qoi"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
Feature-gate all image formats (#15586) # Objective Bevy supports feature gates for each format it supports, but several formats that it loads via the `image` crate do not have feature gates. Additionally, the QOI format is supported by the `image` crate and wasn't available at all. This fixes that. ## Solution The following feature gates are added: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `qoi` * `tiff` None of these formats are enabled by default, despite the fact that all these formats appeared to be enabled by default before. Since `default-features` was disabled for the `image` crate, it's likely that using any of these formats would have errored by default before this change, although this probably needs additional testing. ## Testing The changes seemed minimal enough that a compile test would be sufficient. ## Migration guide Image formats that previously weren't feature-gated are now feature-gated, meaning they will have to be enabled if you use them: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `tiff` Additionally, the `qoi` feature has been added to support loading QOI format images. Previously, these formats appeared in the enum by default, but weren't actually enabled via the `image` crate, potentially resulting in weird bugs. Now, you should be able to add these features to your projects to support them properly.
2024-10-07 16:37:45 +00:00
# TGA image format support
tga = ["bevy_internal/tga"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
Feature-gate all image formats (#15586) # Objective Bevy supports feature gates for each format it supports, but several formats that it loads via the `image` crate do not have feature gates. Additionally, the QOI format is supported by the `image` crate and wasn't available at all. This fixes that. ## Solution The following feature gates are added: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `qoi` * `tiff` None of these formats are enabled by default, despite the fact that all these formats appeared to be enabled by default before. Since `default-features` was disabled for the `image` crate, it's likely that using any of these formats would have errored by default before this change, although this probably needs additional testing. ## Testing The changes seemed minimal enough that a compile test would be sufficient. ## Migration guide Image formats that previously weren't feature-gated are now feature-gated, meaning they will have to be enabled if you use them: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `tiff` Additionally, the `qoi` feature has been added to support loading QOI format images. Previously, these formats appeared in the enum by default, but weren't actually enabled via the `image` crate, potentially resulting in weird bugs. Now, you should be able to add these features to your projects to support them properly.
2024-10-07 16:37:45 +00:00
# TIFF image format support
tiff = ["bevy_internal/tiff"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
Feature-gate all image formats (#15586) # Objective Bevy supports feature gates for each format it supports, but several formats that it loads via the `image` crate do not have feature gates. Additionally, the QOI format is supported by the `image` crate and wasn't available at all. This fixes that. ## Solution The following feature gates are added: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `qoi` * `tiff` None of these formats are enabled by default, despite the fact that all these formats appeared to be enabled by default before. Since `default-features` was disabled for the `image` crate, it's likely that using any of these formats would have errored by default before this change, although this probably needs additional testing. ## Testing The changes seemed minimal enough that a compile test would be sufficient. ## Migration guide Image formats that previously weren't feature-gated are now feature-gated, meaning they will have to be enabled if you use them: * `avif` * `ff` (Farbfeld) * `gif` * `ico` * `tiff` Additionally, the `qoi` feature has been added to support loading QOI format images. Previously, these formats appeared in the enum by default, but weren't actually enabled via the `image` crate, potentially resulting in weird bugs. Now, you should be able to add these features to your projects to support them properly.
2024-10-07 16:37:45 +00:00
# WebP image format support
webp = ["bevy_internal/webp"]
Add support for pnm textures (#8601) # Objective Add support for the [Netpbm](https://en.wikipedia.org/wiki/Netpbm) image formats, behind a `pnm` feature flag. My personal use case for this was robotics applications, with `pgm` being a popular format used in the field to represent world maps in robots. I chose the formats and feature name by checking the logic in [image.rs](https://github.com/bevyengine/bevy/blob/a35ed552fafaffce8a28c7d47b3e294d755ff096/crates/bevy_render/src/texture/image.rs#L76) ## Solution Quite straightforward, the `pnm` feature flag already exists in the `image` crate so it's just creating and exposing a `pnm` feature flag in the root `Cargo.toml` and forwarding it through `bevy_internal` and `bevy_render` all the way to the `image` crate. --- ## Changelog ### Added `pnm` feature to add support for `pam`, `pbm`, `pgm` and `ppm` image formats. --------- Signed-off-by: Luca Della Vedova <lucadv@intrinsic.ai>
2023-05-16 23:51:47 +00:00
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# For KTX2 supercompression
KTX2/DDS/.basis compressed texture support (#3884) # Objective - Support compressed textures including 'universal' formats (ETC1S, UASTC) and transcoding of them to - Support `.dds`, `.ktx2`, and `.basis` files ## Solution - Fixes https://github.com/bevyengine/bevy/issues/3608 Look there for more details. - Note that the functionality is all enabled through non-default features. If it is desirable to enable some by default, I can do that. - The `basis-universal` crate, used for `.basis` file support and for transcoding, is built on bindings against a C++ library. It's not feasible to rewrite in Rust in a short amount of time. There are no Rust alternatives of which I am aware and it's specialised code. In its current state it doesn't support the wasm target, but I don't know for sure. However, it is possible to build the upstream C++ library with emscripten, so there is perhaps a way to add support for web too with some shenanigans. - There's no support for transcoding from BasisLZ/ETC1S in KTX2 files as it was quite non-trivial to implement and didn't feel important given people could use `.basis` files for ETC1S.
2022-03-15 22:26:46 +00:00
zlib = ["bevy_internal/zlib"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# For KTX2 supercompression
KTX2/DDS/.basis compressed texture support (#3884) # Objective - Support compressed textures including 'universal' formats (ETC1S, UASTC) and transcoding of them to - Support `.dds`, `.ktx2`, and `.basis` files ## Solution - Fixes https://github.com/bevyengine/bevy/issues/3608 Look there for more details. - Note that the functionality is all enabled through non-default features. If it is desirable to enable some by default, I can do that. - The `basis-universal` crate, used for `.basis` file support and for transcoding, is built on bindings against a C++ library. It's not feasible to rewrite in Rust in a short amount of time. There are no Rust alternatives of which I am aware and it's specialised code. In its current state it doesn't support the wasm target, but I don't know for sure. However, it is possible to build the upstream C++ library with emscripten, so there is perhaps a way to add support for web too with some shenanigans. - There's no support for transcoding from BasisLZ/ETC1S in KTX2 files as it was quite non-trivial to implement and didn't feel important given people could use `.basis` files for ETC1S.
2022-03-15 22:26:46 +00:00
zstd = ["bevy_internal/zstd"]
Make audio/image dependencies optional through feature flags
2020-08-11 06:30:42 +00:00
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# FLAC audio format support
Add bevy_dylib to force dynamic linking of bevy (#808) This easily improve compilation time by 2x
2020-11-10 03:26:08 +00:00
flac = ["bevy_internal/flac"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# MP3 audio format support
Add bevy_dylib to force dynamic linking of bevy (#808) This easily improve compilation time by 2x
2020-11-10 03:26:08 +00:00
mp3 = ["bevy_internal/mp3"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# OGG/VORBIS audio format support
Add bevy_dylib to force dynamic linking of bevy (#808) This easily improve compilation time by 2x
2020-11-10 03:26:08 +00:00
vorbis = ["bevy_internal/vorbis"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# WAV audio format support
Add bevy_dylib to force dynamic linking of bevy (#808) This easily improve compilation time by 2x
2020-11-10 03:26:08 +00:00
wav = ["bevy_internal/wav"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
Remove redundant symphonia-mp3 feature (#7852) # Objective - Fixes https://github.com/bevyengine/bevy/issues/7848. ## Solution - remove the symphonia-mp3 feature and add a minimp3 feature instead.
2023-03-01 03:22:46 +00:00
# MP3 audio format support (through minimp3)
minimp3 = ["bevy_internal/minimp3"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# AAC audio format support (through symphonia)
Expose symphonia features from rodio in bevy_audio and bevy (#6388) # Objective Fix #6301 ## Solution Add new features in `bevy_audio` to use `symphonia` sound format from `rodio` Also add in `bevy`
2023-01-09 19:05:30 +00:00
symphonia-aac = ["bevy_internal/symphonia-aac"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# AAC, FLAC, MP3, MP4, OGG/VORBIS, and WAV audio formats support (through symphonia)
Expose symphonia features from rodio in bevy_audio and bevy (#6388) # Objective Fix #6301 ## Solution Add new features in `bevy_audio` to use `symphonia` sound format from `rodio` Also add in `bevy`
2023-01-09 19:05:30 +00:00
symphonia-all = ["bevy_internal/symphonia-all"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# FLAC audio format support (through symphonia)
Expose symphonia features from rodio in bevy_audio and bevy (#6388) # Objective Fix #6301 ## Solution Add new features in `bevy_audio` to use `symphonia` sound format from `rodio` Also add in `bevy`
2023-01-09 19:05:30 +00:00
symphonia-flac = ["bevy_internal/symphonia-flac"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# MP4 audio format support (through symphonia)
Expose symphonia features from rodio in bevy_audio and bevy (#6388) # Objective Fix #6301 ## Solution Add new features in `bevy_audio` to use `symphonia` sound format from `rodio` Also add in `bevy`
2023-01-09 19:05:30 +00:00
symphonia-isomp4 = ["bevy_internal/symphonia-isomp4"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# OGG/VORBIS audio format support (through symphonia)
Expose symphonia features from rodio in bevy_audio and bevy (#6388) # Objective Fix #6301 ## Solution Add new features in `bevy_audio` to use `symphonia` sound format from `rodio` Also add in `bevy`
2023-01-09 19:05:30 +00:00
symphonia-vorbis = ["bevy_internal/symphonia-vorbis"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# WAV audio format support (through symphonia)
Expose symphonia features from rodio in bevy_audio and bevy (#6388) # Objective Fix #6301 ## Solution Add new features in `bevy_audio` to use `symphonia` sound format from `rodio` Also add in `bevy`
2023-01-09 19:05:30 +00:00
symphonia-wav = ["bevy_internal/symphonia-wav"]
Make audio/image dependencies optional through feature flags
2020-08-11 06:30:42 +00:00
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# Enable serialization support through serde
Add bevy_dylib to force dynamic linking of bevy (#808) This easily improve compilation time by 2x
2020-11-10 03:26:08 +00:00
serialize = ["bevy_internal/serialize"]
Add serialize/deserialize to some input types (#281)
2020-08-22 01:13:50 +00:00
Add optional single-threaded feature to bevy_ecs/bevy_tasks (#6690) # Objective Fixes #6689. ## Solution Add `single-threaded` as an optional non-default feature to `bevy_ecs` and `bevy_tasks` that: - disable the `ParallelExecutor` as a default runner - disables the multi-threaded `TaskPool` - internally replace `QueryParIter::for_each` calls with `Query::for_each`. Removed the `Mutex` and `Arc` usage in the single-threaded task pool. ![image](https://user-images.githubusercontent.com/3137680/202833253-dd2d520f-75e6-4c7b-be2d-5ce1523cbd38.png) ## Future Work/TODO Create type aliases for `Mutex`, `Arc` that change to single-threaaded equivalents where possible. --- ## Changelog Added: Optional default feature `multi-theaded` to that enables multithreaded parallelism in the engine. Disabling it disables all multithreading in exchange for higher single threaded performance. Does nothing on WASM targets. --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-07-09 04:22:15 +00:00
# Enables multithreaded parallelism in the engine. Disabling it forces all engine tasks to run on a single thread.
multi_threaded feature rename (#12997) # Objective Fixes #12966 ## Solution Renaming multi_threaded feature to match snake case ## Migration Guide Bevy feature multi-threaded should be refered to multi_threaded from now on.
2024-05-06 20:49:32 +00:00
multi_threaded = ["bevy_internal/multi_threaded"]
Add optional single-threaded feature to bevy_ecs/bevy_tasks (#6690) # Objective Fixes #6689. ## Solution Add `single-threaded` as an optional non-default feature to `bevy_ecs` and `bevy_tasks` that: - disable the `ParallelExecutor` as a default runner - disables the multi-threaded `TaskPool` - internally replace `QueryParIter::for_each` calls with `Query::for_each`. Removed the `Mutex` and `Arc` usage in the single-threaded task pool. ![image](https://user-images.githubusercontent.com/3137680/202833253-dd2d520f-75e6-4c7b-be2d-5ce1523cbd38.png) ## Future Work/TODO Create type aliases for `Mutex`, `Arc` that change to single-threaaded equivalents where possible. --- ## Changelog Added: Optional default feature `multi-theaded` to that enables multithreaded parallelism in the engine. Disabling it disables all multithreading in exchange for higher single threaded performance. Does nothing on WASM targets. --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-07-09 04:22:15 +00:00
Allow using async_io::block_on in bevy_tasks (#9626) # Objective Fixes #9625 ## Solution Adds `async-io` as an optional dependency of `bevy_tasks`. When enabled, this causes calls to `futures_lite::future::block_on` to be replaced with calls to `async_io::block_on`. --- ## Changelog - Added a new `async-io` feature to `bevy_tasks`. When enabled, this causes `bevy_tasks` to use `async-io`'s implemention of `block_on` instead of `futures-lite`'s implementation. You should enable this if you use `async-io` in your application.
2023-09-25 19:59:50 +00:00
# Use async-io's implementation of block_on instead of futures-lite's implementation. This is preferred if your application uses async-io.
async-io = ["bevy_internal/async-io"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# Wayland display server support
Add bevy_dylib to force dynamic linking of bevy (#808) This easily improve compilation time by 2x
2020-11-10 03:26:08 +00:00
wayland = ["bevy_internal/wayland"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# X11 display server support
Add bevy_dylib to force dynamic linking of bevy (#808) This easily improve compilation time by 2x
2020-11-10 03:26:08 +00:00
x11 = ["bevy_internal/x11"]
cargo fmt
2020-05-06 01:44:32 +00:00
Add features to switch `NativeActivity` and `GameActivity` usage (#12095) # Objective Add two features to switch bevy to use `NativeActivity` or `GameActivity` on Android, use `GameActivity` by default. Also close #12058 and probably #12026 . ## Solution Add two features to the corresponding crates so you can toggle it, like what `winit` and `android-activity` crate did. --- ## Changelog Removed default `NativeActivity` feature implementation for Android, added two new features to enable `NativeActivity` and `GameActivity`, and use `GameActivity` by default. ## Migration Guide Because `cargo-apk` is not compatible with `GameActivity`, building/running using `cargo apk build/run -p bevy_mobile_example` is no longer possible. Users should follow the new workflow described in document. --------- Co-authored-by: François Mockers <francois.mockers@vleue.com> Co-authored-by: BD103 <59022059+BD103@users.noreply.github.com> Co-authored-by: Rich Churcher <rich.churcher@gmail.com>
2024-10-01 22:23:48 +00:00
# Android NativeActivity support. Legacy, should be avoided for most new Android games.
android-native-activity = ["bevy_internal/android-native-activity"]
# Android GameActivity support. Default, choose between this and `android-native-activity`.
android-game-activity = ["bevy_internal/android-game-activity"]
Feature for bevy UI (#3546) # Objective - For a plugin, I would like to enable `bevy_ui` without adding the complete `render` feature ## Solution - Add a feature for `bevy_ui` Co-authored-by: François <8672791+mockersf@users.noreply.github.com>
2022-01-04 19:49:38 +00:00
# Enable systems that allow for automated testing on CI
run some examples on CI using swiftshader (#1826) From suggestion from Godot workflows: https://github.com/bevyengine/bevy/issues/1730#issuecomment-810321110 * Add a feature `bevy_debug` that will make Bevy read a debug config file to setup some debug systems * Currently, only one that will exit after x frames * Could add option to dump screen to image file once that's possible * Add a job in CI workflow that will run a few examples using [`swiftshader`](https://github.com/google/swiftshader) * This job takes around 13 minutes, so doesn't add to global CI duration |example|number of frames|duration| |-|-|-| |`alien_cake_addict`|300|1:50| |`breakout`|1800|0:44| |`contributors`|1800|0:43| |`load_gltf`|300|2:37| |`scene`|1800|0:44|
2021-04-14 21:40:36 +00:00
bevy_ci_testing = ["bevy_internal/bevy_ci_testing"]
animation player (#4375) # Objective - Add a basic animation player - Single track - Not generic, can only animate `Transform`s - With plenty of possible optimisations available - Close-ish to https://github.com/bevyengine/rfcs/pull/49 - https://discord.com/channels/691052431525675048/774027865020039209/958820063148929064 ## Solution - Can play animations - looping or not - Can pause animations - Can seek in animation - Can alter speed of animation - I also removed the previous gltf animation example https://user-images.githubusercontent.com/8672791/161051887-e79283f0-9803-448a-93d0-5f7a62acb02d.mp4
2022-04-02 22:36:02 +00:00
# Enable animation support, and glTF animation loading
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
animation = ["bevy_internal/animation", "bevy_animation"]
animation player (#4375) # Objective - Add a basic animation player - Single track - Not generic, can only animate `Transform`s - With plenty of possible optimisations available - Close-ish to https://github.com/bevyengine/rfcs/pull/49 - https://discord.com/channels/691052431525675048/774027865020039209/958820063148929064 ## Solution - Can play animations - looping or not - Can pause animations - Can seek in animation - Can alter speed of animation - I also removed the previous gltf animation example https://user-images.githubusercontent.com/8672791/161051887-e79283f0-9803-448a-93d0-5f7a62acb02d.mp4
2022-04-02 22:36:02 +00:00
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# Enable using a shared stdlib for cxx on Android
IOS, Android... same thing (#7493) # Objective - Merge the examples on iOS and Android - Make sure they both work from the same code ## Solution - don't create window when not in an active state (from #6830) - exit on suspend on Android (from #6830) - automatically enable dependency feature of bevy_audio on android so that it works out of the box - don't inverse y position of touch events - reuse the same example for both Android and iOS Fixes #4616 Fixes #4103 Fixes #3648 Fixes #3458 Fixes #3249 Fixes #86
2023-02-06 18:08:49 +00:00
android_shared_stdcxx = ["bevy_internal/android_shared_stdcxx"]
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
# Enable detailed trace event logging. These trace events are expensive even when off, thus they require compile time opt-in
Introduce detailed_trace macro, use in TrackedRenderPass (#7639) Profiles show that in extremely hot loops, like the draw loops in the renderer, invoking the trace! macro has noticeable overhead, even if the trace log level is not enabled. Solve this by introduce a 'wrapper' detailed_trace macro around trace, that wraps the trace! log statement in a trivially false if statement unless a cargo feature is enabled # Objective - Eliminate significant overhead observed with trace-level logging in render hot loops, even when trace log level is not enabled. - This is an alternative solution to the one proposed in #7223 ## Solution - Introduce a wrapper around the `trace!` macro called `detailed_trace!`. This macro wraps the `trace!` macro with an if statement that is conditional on a new cargo feature, `detailed_trace`. When the feature is not enabled (the default), then the if statement is trivially false and should be optimized away at compile time. - Convert the observed hot occurrences of trace logging in `TrackedRenderPass` with this new macro. Testing the results of ``` cargo run --profile stress-test --features bevy/trace_tracy --example many_cubes -- spheres ``` ![image](https://user-images.githubusercontent.com/1222141/218298552-38551717-b062-4c64-afdc-a60267ac984d.png) shows significant improvement of the `main_opaque_pass_3d` of the renderer, a median time decrease from 6.0ms to 3.5ms. --- ## Changelog - For performance reasons, some detailed renderer trace logs now require the use of cargo feature `detailed_trace` in addition to setting the log level to `TRACE` in order to be shown. ## Migration Guide - Some detailed bevy trace events now require the use of the cargo feature `detailed_trace` in addition to enabling `TRACE` level logging to view. Should you wish to see these logs, please compile your code with the bevy feature `detailed_trace`. Currently, the only logs that are affected are the renderer logs pertaining to `TrackedRenderPass` functions
2023-02-13 18:20:27 +00:00
detailed_trace = ["bevy_internal/detailed_trace"]
Migrate cameras to required components (#15641) # Objective Yet another PR for migrating stuff to required components. This time, cameras! ## Solution As per the [selected proposal](https://hackmd.io/tsYID4CGRiWxzsgawzxG_g#Combined-Proposal-1-Selected), deprecate `Camera2dBundle` and `Camera3dBundle` in favor of `Camera2d` and `Camera3d`. Adding a `Camera` without `Camera2d` or `Camera3d` now logs a warning, as suggested by Cart [on Discord](https://discord.com/channels/691052431525675048/1264881140007702558/1291506402832945273). I would personally like cameras to work a bit differently and be split into a few more components, to avoid some footguns and confusing semantics, but that is more controversial, and shouldn't block this core migration. ## Testing I ran a few 2D and 3D examples, and tried cameras with and without render graphs. --- ## Migration Guide `Camera2dBundle` and `Camera3dBundle` have been deprecated in favor of `Camera2d` and `Camera3d`. Inserting them will now also insert the other components required by them automatically.
2024-10-05 01:59:52 +00:00
# Include tonemapping Look Up Tables KTX2 files. If everything is pink, you need to enable this feature or change the `Tonemapping` method for your `Camera2d` or `Camera3d`.
Log a warning when the `tonemapping_luts` feature is disabled but required for the selected tonemapper. (#10253) # Objective Make it obvious why stuff renders pink when rendering stuff with bevy with `default_features = false` and bevy's default tonemapper (TonyMcMapFace, it requires a LUT which requires the `tonemapping_luts`, `ktx2`, and `zstd` features). Not sure if this should be considered as fixing these issues, but in my previous PR (https://github.com/bevyengine/bevy/pull/9073, and old discussions on discord that I only somewhat remember) it seemed like we didn't want to make ktx2 and zstd required features for bevy_core_pipeline. Related https://github.com/bevyengine/bevy/issues/9179 Related https://github.com/bevyengine/bevy/issues/9098 ## Solution This logs an error when a LUT based tonemapper is used without the `tonemapping_luts` feature enabled, and cleans up the default features a bit (`tonemapping_luts` now includes the `ktx2` and `zstd` features, since it panics without them). Another solution would be to fall back to a non-lut based tonemapper, but I don't like this solution as then it's not explicitly clear to users why eg. a library example renders differently than a normal bevy app (if the library forgot the `tonemapping_luts` feature). I did remove the `ktx2` and `zstd` features from the list of default features in Cargo.toml, as I don't believe anything else currently in bevy relies on them (or at least searching through every hit for `ktx2` and `zstd` didn't show anything except loading an environment map in some examples), and they still show up in the `cargo_features` doc as default features. --- ## Changelog - The `tonemapping_luts` feature now includes both the `ktx2` and `zstd` features to avoid a panic when the `tonemapping_luts` feature was enable without both the `ktx2` and `zstd` feature enabled.
2023-10-27 02:07:24 +00:00
tonemapping_luts = ["bevy_internal/tonemapping_luts", "ktx2", "zstd"]
Initial tonemapping options (#7594) # Objective Splits tone mapping from https://github.com/bevyengine/bevy/pull/6677 into a separate PR. Address https://github.com/bevyengine/bevy/issues/2264. Adds tone mapping options: - None: Bypasses tonemapping for instances where users want colors output to match those set. - Reinhard - Reinhard Luminance: Bevy's exiting tonemapping - [ACES](https://github.com/TheRealMJP/BakingLab/blob/master/BakingLab/ACES.hlsl) (Fitted version, based on the same implementation that Godot 4 uses) see https://github.com/bevyengine/bevy/issues/2264 - [AgX](https://github.com/sobotka/AgX) - SomewhatBoringDisplayTransform - TonyMcMapface - Blender Filmic This PR also adds support for EXR images so they can be used to compare tonemapping options with reference images. ## Migration Guide - Tonemapping is now an enum with NONE and the various tonemappers. - The DebandDither is now a separate component. Co-authored-by: JMS55 <47158642+JMS55@users.noreply.github.com>
2023-02-19 20:38:13 +00:00
don't crash without features `bevy_pbr`, `ktx2`, `zstd` (#14020) # Objective - Fixes #13728 ## Solution - add a new feature `smaa_luts`. if enables, it also enables `ktx2` and `zstd`. if not, it doesn't load the files but use placeholders instead - adds all the resources needed in the same places that system that uses them are added.
2024-06-26 03:08:23 +00:00
# Include SMAA Look Up Tables KTX2 Files
smaa_luts = ["bevy_internal/smaa_luts"]
Integrate AccessKit (#6874) # Objective UIs created for Bevy cannot currently be made accessible. This PR aims to address that. ## Solution Integrate AccessKit as a dependency, adding accessibility support to existing bevy_ui widgets. ## Changelog ### Added * Integrate with and expose [AccessKit](https://accesskit.dev) for platform accessibility. * Add `Label` for marking text specifically as a label for UI controls.
2023-03-01 22:45:04 +00:00
# Enable AccessKit on Unix backends (currently only works with experimental screen readers and forks.)
accesskit_unix = ["bevy_internal/accesskit_unix"]
Re-export glam_assert feature (#8232) # Objective - Allow the use of the "glam _assert" feature to help catch runtime errors and validate the arguments passed to glam. e.g. ```rs // Will panic if self is zero length when glam_assert is enabled. pub fn normalize(self) -> Self { let normalized = self.mul(self.length_recip()); glam_assert!(normalized.is_finite()); normalized } ``` ## Solution - Re-export the optional feature glam_assert --- ## Changelog Added: Optional feature "glam_assert"
2023-03-28 20:18:50 +00:00
# Enable assertions to check the validity of parameters passed to glam
glam_assert = ["bevy_internal/glam_assert"]
re-export `debug_glam_assert` feature (#10206) # Objective - I want to use the `debug_glam_assert` feature with bevy. ## Solution - Re-export the feature flag --- ## Changelog - Re-export `debug_glam_assert` feature flag from glam.
2023-10-22 23:01:28 +00:00
# Enable assertions in debug builds to check the validity of parameters passed to glam
debug_glam_assert = ["bevy_internal/debug_glam_assert"]
add a default font (#8445) # Objective - Have a default font ## Solution - Add a font based on FiraMono containing only ASCII characters and use it as the default font - It is behind a feature `default_font` enabled by default - I also updated examples to use it, but not UI examples to still show how to use a custom font --- ## Changelog * If you display text without using the default handle provided by `TextStyle`, the text will be displayed
2023-04-21 22:30:18 +00:00
# Include a default font, containing only ASCII characters, at the cost of a 20kB binary size increase
default_font = ["bevy_internal/default_font"]
make glsl and spirv support optional (#8491) # Objective - Reduce compilation time ## Solution - Make `spirv` and `glsl` shader format support optional. They are not needed for Bevy shaders. - on my mac (where shaders are compiled to `msl`), this reduces the total build time by 2 to 5 seconds, improvement should be even better with less cores There is a big reduction in compile time for `naga`, and small improvements on `wgpu` and `bevy_render` This PR with optional shader formats enabled timings: <img width="1478" alt="current main" src="https://user-images.githubusercontent.com/8672791/234347032-cbd5c276-a9b0-49c3-b793-481677391c18.png"> This PR: <img width="1479" alt="this pr" src="https://user-images.githubusercontent.com/8672791/234347059-a67412a9-da8d-4356-91d8-7b0ae84ca100.png"> --- ## Migration Guide - If you want to use shaders in `spirv`, enable the `shader_format_spirv` feature - If you want to use shaders in `glsl`, enable the `shader_format_glsl` feature
2023-04-25 19:30:48 +00:00
# Enable support for shaders in GLSL
shader_format_glsl = ["bevy_internal/shader_format_glsl"]
# Enable support for shaders in SPIR-V
shader_format_spirv = ["bevy_internal/shader_format_spirv"]
`StandardMaterial` Light Transmission (#8015) # Objective <img width="1920" alt="Screenshot 2023-04-26 at 01 07 34" src="https://user-images.githubusercontent.com/418473/234467578-0f34187b-5863-4ea1-88e9-7a6bb8ce8da3.png"> This PR adds both diffuse and specular light transmission capabilities to the `StandardMaterial`, with support for screen space refractions. This enables realistically representing a wide range of real-world materials, such as: - Glass; (Including frosted glass) - Transparent and translucent plastics; - Various liquids and gels; - Gemstones; - Marble; - Wax; - Paper; - Leaves; - Porcelain. Unlike existing support for transparency, light transmission does not rely on fixed function alpha blending, and therefore works with both `AlphaMode::Opaque` and `AlphaMode::Mask` materials. ## Solution - Introduces a number of transmission related fields in the `StandardMaterial`; - For specular transmission: - Adds logic to take a view main texture snapshot after the opaque phase; (in order to perform screen space refractions) - Introduces a new `Transmissive3d` phase to the renderer, to which all meshes with `transmission > 0.0` materials are sent. - Calculates a light exit point (of the approximate mesh volume) using `ior` and `thickness` properties - Samples the snapshot texture with an adaptive number of taps across a `roughness`-controlled radius enabling “blurry” refractions - For diffuse transmission: - Approximates transmitted diffuse light by using a second, flipped + displaced, diffuse-only Lambertian lobe for each light source. ## To Do - [x] Figure out where `fresnel_mix()` is taking place, if at all, and where `dielectric_specular` is being calculated, if at all, and update them to use the `ior` value (Not a blocker, just a nice-to-have for more correct BSDF) - To the _best of my knowledge, this is now taking place, after 964340cdd. The fresnel mix is actually "split" into two parts in our implementation, one `(1 - fresnel(...))` in the transmission, and `fresnel()` in the light implementations. A surface with more reflectance now will produce slightly dimmer transmission towards the grazing angle, as more of the light gets reflected. - [x] Add `transmission_texture` - [x] Add `diffuse_transmission_texture` - [x] Add `thickness_texture` - [x] Add `attenuation_distance` and `attenuation_color` - [x] Connect values to glTF loader - [x] `transmission` and `transmission_texture` - [x] `thickness` and `thickness_texture` - [x] `ior` - [ ] `diffuse_transmission` and `diffuse_transmission_texture` (needs upstream support in `gltf` crate, not a blocker) - [x] Add support for multiple screen space refraction “steps” - [x] Conditionally create no transmission snapshot texture at all if `steps == 0` - [x] Conditionally enable/disable screen space refraction transmission snapshots - [x] Read from depth pre-pass to prevent refracting pixels in front of the light exit point - [x] Use `interleaved_gradient_noise()` function for sampling blur in a way that benefits from TAA - [x] Drill down a TAA `#define`, tweak some aspects of the effect conditionally based on it - [x] Remove const array that's crashing under HLSL (unless a new `naga` release with https://github.com/gfx-rs/naga/pull/2496 comes out before we merge this) - [ ] Look into alternatives to the `switch` hack for dynamically indexing the const array (might not be needed, compilers seem to be decent at expanding it) - [ ] Add pipeline keys for gating transmission (do we really want/need this?) - [x] Tweak some material field/function names? ## A Note on Texture Packing _This was originally added as a comment to the `specular_transmission_texture`, `thickness_texture` and `diffuse_transmission_texture` documentation, I removed it since it was more confusing than helpful, and will likely be made redundant/will need to be updated once we have a better infrastructure for preprocessing assets_ Due to how channels are mapped, you can more efficiently use a single shared texture image for configuring the following: - R - `specular_transmission_texture` - G - `thickness_texture` - B - _unused_ - A - `diffuse_transmission_texture` The `KHR_materials_diffuse_transmission` glTF extension also defines a `diffuseTransmissionColorTexture`, that _we don't currently support_. One might choose to pack the intensity and color textures together, using RGB for the color and A for the intensity, in which case this packing advice doesn't really apply. --- ## Changelog - Added a new `Transmissive3d` render phase for rendering specular transmissive materials with screen space refractions - Added rendering support for transmitted environment map light on the `StandardMaterial` as a fallback for screen space refractions - Added `diffuse_transmission`, `specular_transmission`, `thickness`, `ior`, `attenuation_distance` and `attenuation_color` to the `StandardMaterial` - Added `diffuse_transmission_texture`, `specular_transmission_texture`, `thickness_texture` to the `StandardMaterial`, gated behind a new `pbr_transmission_textures` cargo feature (off by default, for maximum hardware compatibility) - Added `Camera3d::screen_space_specular_transmission_steps` for controlling the number of “layers of transparency” rendered for transmissive objects - Added a `TransmittedShadowReceiver` component for enabling shadows in (diffusely) transmitted light. (disabled by default, as it requires carefully setting up the `thickness` to avoid self-shadow artifacts) - Added support for the `KHR_materials_transmission`, `KHR_materials_ior` and `KHR_materials_volume` glTF extensions - Renamed items related to temporal jitter for greater consistency ## Migration Guide - `SsaoPipelineKey::temporal_noise` has been renamed to `SsaoPipelineKey::temporal_jitter` - The `TAA` shader def (controlled by the presence of the `TemporalAntiAliasSettings` component in the camera) has been replaced with the `TEMPORAL_JITTER` shader def (controlled by the presence of the `TemporalJitter` component in the camera) - `MeshPipelineKey::TAA` has been replaced by `MeshPipelineKey::TEMPORAL_JITTER` - The `TEMPORAL_NOISE` shader def has been consolidated with `TEMPORAL_JITTER`
2023-10-31 20:59:02 +00:00
# Enable support for transmission-related textures in the `StandardMaterial`, at the risk of blowing past the global, per-shader texture limit on older/lower-end GPUs
pbr_transmission_textures = ["bevy_internal/pbr_transmission_textures"]
Implement clearcoat per the Filament and the `KHR_materials_clearcoat` specifications. (#13031) Clearcoat is a separate material layer that represents a thin translucent layer of a material. Examples include (from the [Filament spec]) car paint, soda cans, and lacquered wood. This commit implements support for clearcoat following the Filament and Khronos specifications, marking the beginnings of support for multiple PBR layers in Bevy. The [`KHR_materials_clearcoat`] specification describes the clearcoat support in glTF. In Blender, applying a clearcoat to the Principled BSDF node causes the clearcoat settings to be exported via this extension. As of this commit, Bevy parses and reads the extension data when present in glTF. Note that the `gltf` crate has no support for `KHR_materials_clearcoat`; this patch therefore implements the JSON semantics manually. Clearcoat is integrated with `StandardMaterial`, but the code is behind a series of `#ifdef`s that only activate when clearcoat is present. Additionally, the `pbr_feature_layer_material_textures` Cargo feature must be active in order to enable support for clearcoat factor maps, clearcoat roughness maps, and clearcoat normal maps. This approach mirrors the same pattern used by the existing transmission feature and exists to avoid running out of texture bindings on platforms like WebGL and WebGPU. Note that constant clearcoat factors and roughness values *are* supported in the browser; only the relatively-less-common maps are disabled on those platforms. This patch refactors the lighting code in `StandardMaterial` significantly in order to better support multiple layers in a natural way. That code was due for a refactor in any case, so this is a nice improvement. A new demo, `clearcoat`, has been added. It's based on [the corresponding three.js demo], but all the assets (aside from the skybox and environment map) are my original work. [Filament spec]: https://google.github.io/filament/Filament.html#materialsystem/clearcoatmodel [`KHR_materials_clearcoat`]: https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Khronos/KHR_materials_clearcoat/README.md [the corresponding three.js demo]: https://threejs.org/examples/webgl_materials_physical_clearcoat.html ![Screenshot 2024-04-19 101143](https://github.com/bevyengine/bevy/assets/157897/3444bcb5-5c20-490c-b0ad-53759bd47ae2) ![Screenshot 2024-04-19 102054](https://github.com/bevyengine/bevy/assets/157897/6e953944-75b8-49ef-bc71-97b0a53b3a27) ## Changelog ### Added * `StandardMaterial` now supports a clearcoat layer, which represents a thin translucent layer over an underlying material. * The glTF loader now supports the `KHR_materials_clearcoat` extension, representing materials with clearcoat layers. ## Migration Guide * The lighting functions in the `pbr_lighting` WGSL module now have clearcoat parameters, if `STANDARD_MATERIAL_CLEARCOAT` is defined. * The `R` reflection vector parameter has been removed from some lighting functions, as it was unused.
2024-05-05 22:57:05 +00:00
# Enable support for multi-layer material textures in the `StandardMaterial`, at the risk of blowing past the global, per-shader texture limit on older/lower-end GPUs
pbr_multi_layer_material_textures = [
"bevy_internal/pbr_multi_layer_material_textures",
]
Added feature switch to default Standard Material's new anisotropy texture to off (#14048) # Objective - Standard Material is starting to run out of samplers (currently uses 13 with no additional features off, I think in 0.13 it was 12). - This change adds a new feature switch, modelled on the other ones which add features to Standard Material, to turn off the new anisotropy feature by default. ## Solution - feature + texture define ## Testing - Anisotropy example still works fine - Other samples work fine - Standard Material now takes 12 samplers by default on my Mac instead of 13 ## Migration Guide - Add feature pbr_anisotropy_texture if you are using that texture in any standard materials. --------- Co-authored-by: John Payne <20407779+johngpayne@users.noreply.github.com>
2024-07-02 18:02:05 +00:00
# Enable support for anisotropy texture in the `StandardMaterial`, at the risk of blowing past the global, per-shader texture limit on older/lower-end GPUs
pbr_anisotropy_texture = ["bevy_internal/pbr_anisotropy_texture"]
Place percentage-closer soft shadows behind a feature gate to save on samplers. (#16068) The two additional linear texture samplers that PCSS added caused us to blow past the limit on Apple Silicon macOS and WebGL. To fix the issue, this commit adds a `--feature pbr_pcss` feature gate that disables PCSS if not present. Closes #15345. Closes #15525. Closes #15821. --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com> Co-authored-by: IceSentry <IceSentry@users.noreply.github.com>
2024-10-24 21:16:00 +00:00
# Enable support for PCSS, at the risk of blowing past the global, per-shader sampler limit on older/lower-end GPUs
Make PCSS experimental (#16382) # Objective PCSS still has some fundamental issues (#16155). We should resolve them before "releasing" the feature. ## Solution 1. Rename the already-optional `pbr_pcss` cargo feature to `experimental_pbr_pcss` to better communicate its state to developers. 2. Adjust the description of the `experimental_pbr_pcss` cargo feature to better communicate its state to developers. 3. Gate PCSS-related light component fields behind that cargo feature, to prevent surfacing them to developers by default.
2024-11-14 07:39:26 +00:00
experimental_pbr_pcss = ["bevy_internal/experimental_pbr_pcss"]
Place percentage-closer soft shadows behind a feature gate to save on samplers. (#16068) The two additional linear texture samplers that PCSS added caused us to blow past the limit on Apple Silicon macOS and WebGL. To fix the issue, this commit adds a `--feature pbr_pcss` feature gate that disables PCSS if not present. Closes #15345. Closes #15525. Closes #15821. --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com> Co-authored-by: IceSentry <IceSentry@users.noreply.github.com>
2024-10-24 21:16:00 +00:00
Update to wgpu 0.19 and raw-window-handle 0.6 (#11280) # Objective Keep core dependencies up to date. ## Solution Update the dependencies. wgpu 0.19 only supports raw-window-handle (rwh) 0.6, so bumping that was included in this. The rwh 0.6 version bump is just the simplest way of doing it. There might be a way we can take advantage of wgpu's new safe surface creation api, but I'm not familiar enough with bevy's window management to untangle it and my attempt ended up being a mess of lifetimes and rustc complaining about missing trait impls (that were implemented). Thanks to @MiniaczQ for the (much simpler) rwh 0.6 version bump code. Unblocks https://github.com/bevyengine/bevy/pull/9172 and https://github.com/bevyengine/bevy/pull/10812 ~~This might be blocked on cpal and oboe updating their ndk versions to 0.8, as they both currently target ndk 0.7 which uses rwh 0.5.2~~ Tested on android, and everything seems to work correctly (audio properly stops when minimized, and plays when re-focusing the app). --- ## Changelog - `wgpu` has been updated to 0.19! The long awaited arcanization has been merged (for more info, see https://gfx-rs.github.io/2023/11/24/arcanization.html), and Vulkan should now be working again on Intel GPUs. - Targeting WebGPU now requires that you add the new `webgpu` feature (setting the `RUSTFLAGS` environment variable to `--cfg=web_sys_unstable_apis` is still required). This feature currently overrides the `webgl2` feature if you have both enabled (the `webgl2` feature is enabled by default), so it is not recommended to add it as a default feature to libraries without putting it behind a flag that allows library users to opt out of it! In the future we plan on supporting wasm binaries that can target both webgl2 and webgpu now that wgpu added support for doing so (see https://github.com/bevyengine/bevy/issues/11505). - `raw-window-handle` has been updated to version 0.6. ## Migration Guide - `bevy_render::instance_index::get_instance_index()` has been removed as the webgl2 workaround is no longer required as it was fixed upstream in wgpu. The `BASE_INSTANCE_WORKAROUND` shaderdef has also been removed. - WebGPU now requires the new `webgpu` feature to be enabled. The `webgpu` feature currently overrides the `webgl2` feature so you no longer need to disable all default features and re-add them all when targeting `webgpu`, but binaries built with both the `webgpu` and `webgl2` features will only target the webgpu backend, and will only work on browsers that support WebGPU. - Places where you conditionally compiled things for webgl2 need to be updated because of this change, eg: - `#[cfg(any(not(feature = "webgl"), not(target_arch = "wasm32")))]` becomes `#[cfg(any(not(feature = "webgl") ,not(target_arch = "wasm32"), feature = "webgpu"))]` - `#[cfg(all(feature = "webgl", target_arch = "wasm32"))]` becomes `#[cfg(all(feature = "webgl", target_arch = "wasm32", not(feature = "webgpu")))]` - `if cfg!(all(feature = "webgl", target_arch = "wasm32"))` becomes `if cfg!(all(feature = "webgl", target_arch = "wasm32", not(feature = "webgpu")))` - `create_texture_with_data` now also takes a `TextureDataOrder`. You can probably just set this to `TextureDataOrder::default()` - `TextureFormat`'s `block_size` has been renamed to `block_copy_size` - See the `wgpu` changelog for anything I might've missed: https://github.com/gfx-rs/wgpu/blob/trunk/CHANGELOG.md --------- Co-authored-by: François <mockersf@gmail.com>
2024-01-26 18:14:21 +00:00
# Enable some limitations to be able to use WebGL2. Please refer to the [WebGL2 and WebGPU](https://github.com/bevyengine/bevy/tree/latest/examples#webgl2-and-webgpu) section of the examples README for more information on how to run Wasm builds with WebGPU.
Webgpu support (#8336) # Objective - Support WebGPU - alternative to #5027 that doesn't need any async / await - fixes #8315 - Surprise fix #7318 ## Solution ### For async renderer initialisation - Update the plugin lifecycle: - app builds the plugin - calls `plugin.build` - registers the plugin - app starts the event loop - event loop waits for `ready` of all registered plugins in the same order - returns `true` by default - then call all `finish` then all `cleanup` in the same order as registered - then execute the schedule In the case of the renderer, to avoid anything async: - building the renderer plugin creates a detached task that will send back the initialised renderer through a mutex in a resource - `ready` will wait for the renderer to be present in the resource - `finish` will take that renderer and place it in the expected resources by other plugins - other plugins (that expect the renderer to be available) `finish` are called and they are able to set up their pipelines - `cleanup` is called, only custom one is still for pipeline rendering ### For WebGPU support - update the `build-wasm-example` script to support passing `--api webgpu` that will build the example with WebGPU support - feature for webgl2 was always enabled when building for wasm. it's now in the default feature list and enabled on all platforms, so check for this feature must also check that the target_arch is `wasm32` --- ## Migration Guide - `Plugin::setup` has been renamed `Plugin::cleanup` - `Plugin::finish` has been added, and plugins adding pipelines should do it in this function instead of `Plugin::build` ```rust // Before impl Plugin for MyPlugin { fn build(&self, app: &mut App) { app.insert_resource::<MyResource> .add_systems(Update, my_system); let render_app = match app.get_sub_app_mut(RenderApp) { Ok(render_app) => render_app, Err(_) => return, }; render_app .init_resource::<RenderResourceNeedingDevice>() .init_resource::<OtherRenderResource>(); } } // After impl Plugin for MyPlugin { fn build(&self, app: &mut App) { app.insert_resource::<MyResource> .add_systems(Update, my_system); let render_app = match app.get_sub_app_mut(RenderApp) { Ok(render_app) => render_app, Err(_) => return, }; render_app .init_resource::<OtherRenderResource>(); } fn finish(&self, app: &mut App) { let render_app = match app.get_sub_app_mut(RenderApp) { Ok(render_app) => render_app, Err(_) => return, }; render_app .init_resource::<RenderResourceNeedingDevice>(); } } ```
2023-05-04 22:07:57 +00:00
webgl2 = ["bevy_internal/webgl"]
Update `wgpu` to v0.19.3 and unpin `web-sys`. (#12247) # Objective This PR unpins `web-sys` so that unrelated projects that have `bevy_render` in their workspace can finally update their `web-sys`. More details in and fixes #12246. ## Solution * Update `wgpu` from 0.19.1 to 0.19.3. * Remove the `web-sys` pin. * Update docs and wasm helper to remove the now-stale `--cfg=web_sys_unstable_apis` Rust flag. --- ## Changelog Updated `wgpu` to v0.19.3 and removed `web-sys` pin.
2024-03-02 00:44:51 +00:00
# Enable support for WebGPU in Wasm. When enabled, this feature will override the `webgl2` feature and you won't be able to run Wasm builds with WebGL2, only with WebGPU.
Update to wgpu 0.19 and raw-window-handle 0.6 (#11280) # Objective Keep core dependencies up to date. ## Solution Update the dependencies. wgpu 0.19 only supports raw-window-handle (rwh) 0.6, so bumping that was included in this. The rwh 0.6 version bump is just the simplest way of doing it. There might be a way we can take advantage of wgpu's new safe surface creation api, but I'm not familiar enough with bevy's window management to untangle it and my attempt ended up being a mess of lifetimes and rustc complaining about missing trait impls (that were implemented). Thanks to @MiniaczQ for the (much simpler) rwh 0.6 version bump code. Unblocks https://github.com/bevyengine/bevy/pull/9172 and https://github.com/bevyengine/bevy/pull/10812 ~~This might be blocked on cpal and oboe updating their ndk versions to 0.8, as they both currently target ndk 0.7 which uses rwh 0.5.2~~ Tested on android, and everything seems to work correctly (audio properly stops when minimized, and plays when re-focusing the app). --- ## Changelog - `wgpu` has been updated to 0.19! The long awaited arcanization has been merged (for more info, see https://gfx-rs.github.io/2023/11/24/arcanization.html), and Vulkan should now be working again on Intel GPUs. - Targeting WebGPU now requires that you add the new `webgpu` feature (setting the `RUSTFLAGS` environment variable to `--cfg=web_sys_unstable_apis` is still required). This feature currently overrides the `webgl2` feature if you have both enabled (the `webgl2` feature is enabled by default), so it is not recommended to add it as a default feature to libraries without putting it behind a flag that allows library users to opt out of it! In the future we plan on supporting wasm binaries that can target both webgl2 and webgpu now that wgpu added support for doing so (see https://github.com/bevyengine/bevy/issues/11505). - `raw-window-handle` has been updated to version 0.6. ## Migration Guide - `bevy_render::instance_index::get_instance_index()` has been removed as the webgl2 workaround is no longer required as it was fixed upstream in wgpu. The `BASE_INSTANCE_WORKAROUND` shaderdef has also been removed. - WebGPU now requires the new `webgpu` feature to be enabled. The `webgpu` feature currently overrides the `webgl2` feature so you no longer need to disable all default features and re-add them all when targeting `webgpu`, but binaries built with both the `webgpu` and `webgl2` features will only target the webgpu backend, and will only work on browsers that support WebGPU. - Places where you conditionally compiled things for webgl2 need to be updated because of this change, eg: - `#[cfg(any(not(feature = "webgl"), not(target_arch = "wasm32")))]` becomes `#[cfg(any(not(feature = "webgl") ,not(target_arch = "wasm32"), feature = "webgpu"))]` - `#[cfg(all(feature = "webgl", target_arch = "wasm32"))]` becomes `#[cfg(all(feature = "webgl", target_arch = "wasm32", not(feature = "webgpu")))]` - `if cfg!(all(feature = "webgl", target_arch = "wasm32"))` becomes `if cfg!(all(feature = "webgl", target_arch = "wasm32", not(feature = "webgpu")))` - `create_texture_with_data` now also takes a `TextureDataOrder`. You can probably just set this to `TextureDataOrder::default()` - `TextureFormat`'s `block_size` has been renamed to `block_copy_size` - See the `wgpu` changelog for anything I might've missed: https://github.com/gfx-rs/wgpu/blob/trunk/CHANGELOG.md --------- Co-authored-by: François <mockersf@gmail.com>
2024-01-26 18:14:21 +00:00
webgpu = ["bevy_internal/webgpu"]
Add `asset_processor` feature and remove AssetMode::ProcessedDev (#10194) # Objective Users shouldn't need to change their source code between "development workflows" and "releasing". Currently, Bevy Asset V2 has two "processed" asset modes `Processed` (assumes assets are already processed) and `ProcessedDev` (starts an asset processor and processes assets). This means that the mode must be changed _in code_ when switching from "app dev" to "release". Very suboptimal. We have already removed "runtime opt-in" for hot-reloading. Enabling the `file_watcher` feature _automatically_ enables file watching in code. This means deploying a game (without hot reloading enabled) just means calling `cargo build --release` instead of `cargo run --features bevy/file_watcher`. We should adopt this pattern for asset processing. ## Solution This adds the `asset_processor` feature, which will start the `AssetProcessor` when an `AssetPlugin` runs in `AssetMode::Processed`. The "asset processing workflow" is now: 1. Enable `AssetMode::Processed` on `AssetPlugin` 2. When developing, run with the `asset_processor` and `file_watcher` features 3. When releasing, build without these features. The `AssetMode::ProcessedDev` mode has been removed.
2023-10-20 20:50:26 +00:00
# Enables the built-in asset processor for processed assets.
asset_processor = ["bevy_internal/asset_processor"]
Bevy Asset V2 (#8624) # Bevy Asset V2 Proposal ## Why Does Bevy Need A New Asset System? Asset pipelines are a central part of the gamedev process. Bevy's current asset system is missing a number of features that make it non-viable for many classes of gamedev. After plenty of discussions and [a long community feedback period](https://github.com/bevyengine/bevy/discussions/3972), we've identified a number missing features: * **Asset Preprocessing**: it should be possible to "preprocess" / "compile" / "crunch" assets at "development time" rather than when the game starts up. This enables offloading expensive work from deployed apps, faster asset loading, less runtime memory usage, etc. * **Per-Asset Loader Settings**: Individual assets cannot define their own loaders that override the defaults. Additionally, they cannot provide per-asset settings to their loaders. This is a huge limitation, as many asset types don't provide all information necessary for Bevy _inside_ the asset. For example, a raw PNG image says nothing about how it should be sampled (ex: linear vs nearest). * **Asset `.meta` files**: assets should have configuration files stored adjacent to the asset in question, which allows the user to configure asset-type-specific settings. These settings should be accessible during the pre-processing phase. Modifying a `.meta` file should trigger a re-processing / re-load of the asset. It should be possible to configure asset loaders from the meta file. * **Processed Asset Hot Reloading**: Changes to processed assets (or their dependencies) should result in re-processing them and re-loading the results in live Bevy Apps. * **Asset Dependency Tracking**: The current bevy_asset has no good way to wait for asset dependencies to load. It punts this as an exercise for consumers of the loader apis, which is unreasonable and error prone. There should be easy, ergonomic ways to wait for assets to load and block some logic on an asset's entire dependency tree loading. * **Runtime Asset Loading**: it should be (optionally) possible to load arbitrary assets dynamically at runtime. This necessitates being able to deploy and run the asset server alongside Bevy Apps on _all platforms_. For example, we should be able to invoke the shader compiler at runtime, stream scenes from sources like the internet, etc. To keep deployed binaries (and startup times) small, the runtime asset server configuration should be configurable with different settings compared to the "pre processor asset server". * **Multiple Backends**: It should be possible to load assets from arbitrary sources (filesystems, the internet, remote asset serves, etc). * **Asset Packing**: It should be possible to deploy assets in compressed "packs", which makes it easier and more efficient to distribute assets with Bevy Apps. * **Asset Handoff**: It should be possible to hold a "live" asset handle, which correlates to runtime data, without actually holding the asset in memory. Ex: it must be possible to hold a reference to a GPU mesh generated from a "mesh asset" without keeping the mesh data in CPU memory * **Per-Platform Processed Assets**: Different platforms and app distributions have different capabilities and requirements. Some platforms need lower asset resolutions or different asset formats to operate within the hardware constraints of the platform. It should be possible to define per-platform asset processing profiles. And it should be possible to deploy only the assets required for a given platform. These features have architectural implications that are significant enough to require a full rewrite. The current Bevy Asset implementation got us this far, but it can take us no farther. This PR defines a brand new asset system that implements most of these features, while laying the foundations for the remaining features to be built. ## Bevy Asset V2 Here is a quick overview of the features introduced in this PR. * **Asset Preprocessing**: Preprocess assets at development time into more efficient (and configurable) representations * **Dependency Aware**: Dependencies required to process an asset are tracked. If an asset's processed dependency changes, it will be reprocessed * **Hot Reprocessing/Reloading**: detect changes to asset source files, reprocess them if they have changed, and then hot-reload them in Bevy Apps. * **Only Process Changes**: Assets are only re-processed when their source file (or meta file) has changed. This uses hashing and timestamps to avoid processing assets that haven't changed. * **Transactional and Reliable**: Uses write-ahead logging (a technique commonly used by databases) to recover from crashes / forced-exits. Whenever possible it avoids full-reprocessing / only uncompleted transactions will be reprocessed. When the processor is running in parallel with a Bevy App, processor asset writes block Bevy App asset reads. Reading metadata + asset bytes is guaranteed to be transactional / correctly paired. * **Portable / Run anywhere / Database-free**: The processor does not rely on an in-memory database (although it uses some database techniques for reliability). This is important because pretty much all in-memory databases have unsupported platforms or build complications. * **Configure Processor Defaults Per File Type**: You can say "use this processor for all files of this type". * **Custom Processors**: The `Processor` trait is flexible and unopinionated. It can be implemented by downstream plugins. * **LoadAndSave Processors**: Most asset processing scenarios can be expressed as "run AssetLoader A, save the results using AssetSaver X, and then load the result using AssetLoader B". For example, load this png image using `PngImageLoader`, which produces an `Image` asset and then save it using `CompressedImageSaver` (which also produces an `Image` asset, but in a compressed format), which takes an `Image` asset as input. This means if you have an `AssetLoader` for an asset, you are already half way there! It also means that you can share AssetSavers across multiple loaders. Because `CompressedImageSaver` accepts Bevy's generic Image asset as input, it means you can also use it with some future `JpegImageLoader`. * **Loader and Saver Settings**: Asset Loaders and Savers can now define their own settings types, which are passed in as input when an asset is loaded / saved. Each asset can define its own settings. * **Asset `.meta` files**: configure asset loaders, their settings, enable/disable processing, and configure processor settings * **Runtime Asset Dependency Tracking** Runtime asset dependencies (ex: if an asset contains a `Handle<Image>`) are tracked by the asset server. An event is emitted when an asset and all of its dependencies have been loaded * **Unprocessed Asset Loading**: Assets do not require preprocessing. They can be loaded directly. A processed asset is just a "normal" asset with some extra metadata. Asset Loaders don't need to know or care about whether or not an asset was processed. * **Async Asset IO**: Asset readers/writers use async non-blocking interfaces. Note that because Rust doesn't yet support async traits, there is a bit of manual Boxing / Future boilerplate. This will hopefully be removed in the near future when Rust gets async traits. * **Pluggable Asset Readers and Writers**: Arbitrary asset source readers/writers are supported, both by the processor and the asset server. * **Better Asset Handles** * **Single Arc Tree**: Asset Handles now use a single arc tree that represents the lifetime of the asset. This makes their implementation simpler, more efficient, and allows us to cheaply attach metadata to handles. Ex: the AssetPath of a handle is now directly accessible on the handle itself! * **Const Typed Handles**: typed handles can be constructed in a const context. No more weird "const untyped converted to typed at runtime" patterns! * **Handles and Ids are Smaller / Faster To Hash / Compare**: Typed `Handle<T>` is now much smaller in memory and `AssetId<T>` is even smaller. * **Weak Handle Usage Reduction**: In general Handles are now considered to be "strong". Bevy features that previously used "weak `Handle<T>`" have been ported to `AssetId<T>`, which makes it statically clear that the features do not hold strong handles (while retaining strong type information). Currently Handle::Weak still exists, but it is very possible that we can remove that entirely. * **Efficient / Dense Asset Ids**: Assets now have efficient dense runtime asset ids, which means we can avoid expensive hash lookups. Assets are stored in Vecs instead of HashMaps. There are now typed and untyped ids, which means we no longer need to store dynamic type information in the ID for typed handles. "AssetPathId" (which was a nightmare from a performance and correctness standpoint) has been entirely removed in favor of dense ids (which are retrieved for a path on load) * **Direct Asset Loading, with Dependency Tracking**: Assets that are defined at runtime can still have their dependencies tracked by the Asset Server (ex: if you create a material at runtime, you can still wait for its textures to load). This is accomplished via the (currently optional) "asset dependency visitor" trait. This system can also be used to define a set of assets to load, then wait for those assets to load. * **Async folder loading**: Folder loading also uses this system and immediately returns a handle to the LoadedFolder asset, which means folder loading no longer blocks on directory traversals. * **Improved Loader Interface**: Loaders now have a specific "top level asset type", which makes returning the top-level asset simpler and statically typed. * **Basic Image Settings and Processing**: Image assets can now be processed into the gpu-friendly Basic Universal format. The ImageLoader now has a setting to define what format the image should be loaded as. Note that this is just a minimal MVP ... plenty of additional work to do here. To demo this, enable the `basis-universal` feature and turn on asset processing. * **Simpler Audio Play / AudioSink API**: Asset handle providers are cloneable, which means the Audio resource can mint its own handles. This means you can now do `let sink_handle = audio.play(music)` instead of `let sink_handle = audio_sinks.get_handle(audio.play(music))`. Note that this might still be replaced by https://github.com/bevyengine/bevy/pull/8424. **Removed Handle Casting From Engine Features**: Ex: FontAtlases no longer use casting between handle types ## Using The New Asset System ### Normal Unprocessed Asset Loading By default the `AssetPlugin` does not use processing. It behaves pretty much the same way as the old system. If you are defining a custom asset, first derive `Asset`: ```rust #[derive(Asset)] struct Thing { value: String, } ``` Initialize the asset: ```rust app.init_asset:<Thing>() ``` Implement a new `AssetLoader` for it: ```rust #[derive(Default)] struct ThingLoader; #[derive(Serialize, Deserialize, Default)] pub struct ThingSettings { some_setting: bool, } impl AssetLoader for ThingLoader { type Asset = Thing; type Settings = ThingSettings; fn load<'a>( &'a self, reader: &'a mut Reader, settings: &'a ThingSettings, load_context: &'a mut LoadContext, ) -> BoxedFuture<'a, Result<Thing, anyhow::Error>> { Box::pin(async move { let mut bytes = Vec::new(); reader.read_to_end(&mut bytes).await?; // convert bytes to value somehow Ok(Thing { value }) }) } fn extensions(&self) -> &[&str] { &["thing"] } } ``` Note that this interface will get much cleaner once Rust gets support for async traits. `Reader` is an async futures_io::AsyncRead. You can stream bytes as they come in or read them all into a `Vec<u8>`, depending on the context. You can use `let handle = load_context.load(path)` to kick off a dependency load, retrieve a handle, and register the dependency for the asset. Then just register the loader in your Bevy app: ```rust app.init_asset_loader::<ThingLoader>() ``` Now just add your `Thing` asset files into the `assets` folder and load them like this: ```rust fn system(asset_server: Res<AssetServer>) { let handle = Handle<Thing> = asset_server.load("cool.thing"); } ``` You can check load states directly via the asset server: ```rust if asset_server.load_state(&handle) == LoadState::Loaded { } ``` You can also listen for events: ```rust fn system(mut events: EventReader<AssetEvent<Thing>>, handle: Res<SomeThingHandle>) { for event in events.iter() { if event.is_loaded_with_dependencies(&handle) { } } } ``` Note the new `AssetEvent::LoadedWithDependencies`, which only fires when the asset is loaded _and_ all dependencies (and their dependencies) have loaded. Unlike the old asset system, for a given asset path all `Handle<T>` values point to the same underlying Arc. This means Handles can cheaply hold more asset information, such as the AssetPath: ```rust // prints the AssetPath of the handle info!("{:?}", handle.path()) ``` ### Processed Assets Asset processing can be enabled via the `AssetPlugin`. When developing Bevy Apps with processed assets, do this: ```rust app.add_plugins(DefaultPlugins.set(AssetPlugin::processed_dev())) ``` This runs the `AssetProcessor` in the background with hot-reloading. It reads assets from the `assets` folder, processes them, and writes them to the `.imported_assets` folder. Asset loads in the Bevy App will wait for a processed version of the asset to become available. If an asset in the `assets` folder changes, it will be reprocessed and hot-reloaded in the Bevy App. When deploying processed Bevy apps, do this: ```rust app.add_plugins(DefaultPlugins.set(AssetPlugin::processed())) ``` This does not run the `AssetProcessor` in the background. It behaves like `AssetPlugin::unprocessed()`, but reads assets from `.imported_assets`. When the `AssetProcessor` is running, it will populate sibling `.meta` files for assets in the `assets` folder. Meta files for assets that do not have a processor configured look like this: ```rust ( meta_format_version: "1.0", asset: Load( loader: "bevy_render::texture::image_loader::ImageLoader", settings: ( format: FromExtension, ), ), ) ``` This is metadata for an image asset. For example, if you have `assets/my_sprite.png`, this could be the metadata stored at `assets/my_sprite.png.meta`. Meta files are totally optional. If no metadata exists, the default settings will be used. In short, this file says "load this asset with the ImageLoader and use the file extension to determine the image type". This type of meta file is supported in all AssetPlugin modes. If in `Unprocessed` mode, the asset (with the meta settings) will be loaded directly. If in `ProcessedDev` mode, the asset file will be copied directly to the `.imported_assets` folder. The meta will also be copied directly to the `.imported_assets` folder, but with one addition: ```rust ( meta_format_version: "1.0", processed_info: Some(( hash: 12415480888597742505, full_hash: 14344495437905856884, process_dependencies: [], )), asset: Load( loader: "bevy_render::texture::image_loader::ImageLoader", settings: ( format: FromExtension, ), ), ) ``` `processed_info` contains `hash` (a direct hash of the asset and meta bytes), `full_hash` (a hash of `hash` and the hashes of all `process_dependencies`), and `process_dependencies` (the `path` and `full_hash` of every process_dependency). A "process dependency" is an asset dependency that is _directly_ used when processing the asset. Images do not have process dependencies, so this is empty. When the processor is enabled, you can use the `Process` metadata config: ```rust ( meta_format_version: "1.0", asset: Process( processor: "bevy_asset::processor::process::LoadAndSave<bevy_render::texture::image_loader::ImageLoader, bevy_render::texture::compressed_image_saver::CompressedImageSaver>", settings: ( loader_settings: ( format: FromExtension, ), saver_settings: ( generate_mipmaps: true, ), ), ), ) ``` This configures the asset to use the `LoadAndSave` processor, which runs an AssetLoader and feeds the result into an AssetSaver (which saves the given Asset and defines a loader to load it with). (for terseness LoadAndSave will likely get a shorter/friendlier type name when [Stable Type Paths](#7184) lands). `LoadAndSave` is likely to be the most common processor type, but arbitrary processors are supported. `CompressedImageSaver` saves an `Image` in the Basis Universal format and configures the ImageLoader to load it as basis universal. The `AssetProcessor` will read this meta, run it through the LoadAndSave processor, and write the basis-universal version of the image to `.imported_assets`. The final metadata will look like this: ```rust ( meta_format_version: "1.0", processed_info: Some(( hash: 905599590923828066, full_hash: 9948823010183819117, process_dependencies: [], )), asset: Load( loader: "bevy_render::texture::image_loader::ImageLoader", settings: ( format: Format(Basis), ), ), ) ``` To try basis-universal processing out in Bevy examples, (for example `sprite.rs`), change `add_plugins(DefaultPlugins)` to `add_plugins(DefaultPlugins.set(AssetPlugin::processed_dev()))` and run with the `basis-universal` feature enabled: `cargo run --features=basis-universal --example sprite`. To create a custom processor, there are two main paths: 1. Use the `LoadAndSave` processor with an existing `AssetLoader`. Implement the `AssetSaver` trait, register the processor using `asset_processor.register_processor::<LoadAndSave<ImageLoader, CompressedImageSaver>>(image_saver.into())`. 2. Implement the `Process` trait directly and register it using: `asset_processor.register_processor(thing_processor)`. You can configure default processors for file extensions like this: ```rust asset_processor.set_default_processor::<ThingProcessor>("thing") ``` There is one more metadata type to be aware of: ```rust ( meta_format_version: "1.0", asset: Ignore, ) ``` This will ignore the asset during processing / prevent it from being written to `.imported_assets`. The AssetProcessor stores a transaction log at `.imported_assets/log` and uses it to gracefully recover from unexpected stops. This means you can force-quit the processor (and Bevy Apps running the processor in parallel) at arbitrary times! `.imported_assets` is "local state". It should _not_ be checked into source control. It should also be considered "read only". In practice, you _can_ modify processed assets and processed metadata if you really need to test something. But those modifications will not be represented in the hashes of the assets, so the processed state will be "out of sync" with the source assets. The processor _will not_ fix this for you. Either revert the change after you have tested it, or delete the processed files so they can be re-populated. ## Open Questions There are a number of open questions to be discussed. We should decide if they need to be addressed in this PR and if so, how we will address them: ### Implied Dependencies vs Dependency Enumeration There are currently two ways to populate asset dependencies: * **Implied via AssetLoaders**: if an AssetLoader loads an asset (and retrieves a handle), a dependency is added to the list. * **Explicit via the optional Asset::visit_dependencies**: if `server.load_asset(my_asset)` is called, it will call `my_asset.visit_dependencies`, which will grab dependencies that have been manually defined for the asset via the Asset trait impl (which can be derived). This means that defining explicit dependencies is optional for "loaded assets". And the list of dependencies is always accurate because loaders can only produce Handles if they register dependencies. If an asset was loaded with an AssetLoader, it only uses the implied dependencies. If an asset was created at runtime and added with `asset_server.load_asset(MyAsset)`, it will use `Asset::visit_dependencies`. However this can create a behavior mismatch between loaded assets and equivalent "created at runtime" assets if `Assets::visit_dependencies` doesn't exactly match the dependencies produced by the AssetLoader. This behavior mismatch can be resolved by completely removing "implied loader dependencies" and requiring `Asset::visit_dependencies` to supply dependency data. But this creates two problems: * It makes defining loaded assets harder and more error prone: Devs must remember to manually annotate asset dependencies with `#[dependency]` when deriving `Asset`. For more complicated assets (such as scenes), the derive likely wouldn't be sufficient and a manual `visit_dependencies` impl would be required. * Removes the ability to immediately kick off dependency loads: When AssetLoaders retrieve a Handle, they also immediately kick off an asset load for the handle, which means it can start loading in parallel _before_ the asset finishes loading. For large assets, this could be significant. (although this could be mitigated for processed assets if we store dependencies in the processed meta file and load them ahead of time) ### Eager ProcessorDev Asset Loading I made a controversial call in the interest of fast startup times ("time to first pixel") for the "processor dev mode configuration". When initializing the AssetProcessor, current processed versions of unchanged assets are yielded immediately, even if their dependencies haven't been checked yet for reprocessing. This means that non-current-state-of-filesystem-but-previously-valid assets might be returned to the App first, then hot-reloaded if/when their dependencies change and the asset is reprocessed. Is this behavior desirable? There is largely one alternative: do not yield an asset from the processor to the app until all of its dependencies have been checked for changes. In some common cases (load dependency has not changed since last run) this will increase startup time. The main question is "by how much" and is that slower startup time worth it in the interest of only yielding assets that are true to the current state of the filesystem. Should this be configurable? I'm starting to think we should only yield an asset after its (historical) dependencies have been checked for changes + processed as necessary, but I'm curious what you all think. ### Paths Are Currently The Only Canonical ID / Do We Want Asset UUIDs? In this implementation AssetPaths are the only canonical asset identifier (just like the previous Bevy Asset system and Godot). Moving assets will result in re-scans (and currently reprocessing, although reprocessing can easily be avoided with some changes). Asset renames/moves will break code and assets that rely on specific paths, unless those paths are fixed up. Do we want / need "stable asset uuids"? Introducing them is very possible: 1. Generate a UUID and include it in .meta files 2. Support UUID in AssetPath 3. Generate "asset indices" which are loaded on startup and map UUIDs to paths. 4 (maybe). Consider only supporting UUIDs for processed assets so we can generate quick-to-load indices instead of scanning meta files. The main "pro" is that assets referencing UUIDs don't need to be migrated when a path changes. The main "con" is that UUIDs cannot be "lazily resolved" like paths. They need a full view of all assets to answer the question "does this UUID exist". Which means UUIDs require the AssetProcessor to fully finish startup scans before saying an asset doesnt exist. And they essentially require asset pre-processing to use in apps, because scanning all asset metadata files at runtime to resolve a UUID is not viable for medium-to-large apps. It really requires a pre-generated UUID index, which must be loaded before querying for assets. I personally think this should be investigated in a separate PR. Paths aren't going anywhere ... _everyone_ uses filesystems (and filesystem-like apis) to manage their asset source files. I consider them permanent canonical asset information. Additionally, they behave well for both processed and unprocessed asset modes. Given that Bevy is supporting both, this feels like the right canonical ID to start with. UUIDS (and maybe even other indexed-identifier types) can be added later as necessary. ### Folder / File Naming Conventions All asset processing config currently lives in the `.imported_assets` folder. The processor transaction log is in `.imported_assets/log`. Processed assets are added to `.imported_assets/Default`, which will make migrating to processed asset profiles (ex: a `.imported_assets/Mobile` profile) a non-breaking change. It also allows us to create top-level files like `.imported_assets/log` without it being interpreted as an asset. Meta files currently have a `.meta` suffix. Do we like these names and conventions? ### Should the `AssetPlugin::processed_dev` configuration enable `watch_for_changes` automatically? Currently it does (which I think makes sense), but it does make it the only configuration that enables watch_for_changes by default. ### Discuss on_loaded High Level Interface: This PR includes a very rough "proof of concept" `on_loaded` system adapter that uses the `LoadedWithDependencies` event in combination with `asset_server.load_asset` dependency tracking to support this pattern ```rust fn main() { App::new() .init_asset::<MyAssets>() .add_systems(Update, on_loaded(create_array_texture)) .run(); } #[derive(Asset, Clone)] struct MyAssets { #[dependency] picture_of_my_cat: Handle<Image>, #[dependency] picture_of_my_other_cat: Handle<Image>, } impl FromWorld for ArrayTexture { fn from_world(world: &mut World) -> Self { picture_of_my_cat: server.load("meow.png"), picture_of_my_other_cat: server.load("meeeeeeeow.png"), } } fn spawn_cat(In(my_assets): In<MyAssets>, mut commands: Commands) { commands.spawn(SpriteBundle { texture: my_assets.picture_of_my_cat.clone(), ..default() }); commands.spawn(SpriteBundle { texture: my_assets.picture_of_my_other_cat.clone(), ..default() }); } ``` The implementation is _very_ rough. And it is currently unsafe because `bevy_ecs` doesn't expose some internals to do this safely from inside `bevy_asset`. There are plenty of unanswered questions like: * "do we add a Loadable" derive? (effectively automate the FromWorld implementation above) * Should `MyAssets` even be an Asset? (largely implemented this way because it elegantly builds on `server.load_asset(MyAsset { .. })` dependency tracking). We should think hard about what our ideal API looks like (and if this is a pattern we want to support). Not necessarily something we need to solve in this PR. The current `on_loaded` impl should probably be removed from this PR before merging. ## Clarifying Questions ### What about Assets as Entities? This Bevy Asset V2 proposal implementation initially stored Assets as ECS Entities. Instead of `AssetId<T>` + the `Assets<T>` resource it used `Entity` as the asset id and Asset values were just ECS components. There are plenty of compelling reasons to do this: 1. Easier to inline assets in Bevy Scenes (as they are "just" normal entities + components) 2. More flexible queries: use the power of the ECS to filter assets (ex: `Query<Mesh, With<Tree>>`). 3. Extensible. Users can add arbitrary component data to assets. 4. Things like "component visualization tools" work out of the box to visualize asset data. However Assets as Entities has a ton of caveats right now: * We need to be able to allocate entity ids without a direct World reference (aka rework id allocator in Entities ... i worked around this in my prototypes by just pre allocating big chunks of entities) * We want asset change events in addition to ECS change tracking ... how do we populate them when mutations can come from anywhere? Do we use Changed queries? This would require iterating over the change data for all assets every frame. Is this acceptable or should we implement a new "event based" component change detection option? * Reconciling manually created assets with asset-system managed assets has some nuance (ex: are they "loaded" / do they also have that component metadata?) * "how do we handle "static" / default entity handles" (ties in to the Entity Indices discussion: https://github.com/bevyengine/bevy/discussions/8319). This is necessary for things like "built in" assets and default handles in things like SpriteBundle. * Storing asset information as a component makes it easy to "invalidate" asset state by removing the component (or forcing modifications). Ideally we have ways to lock this down (some combination of Rust type privacy and ECS validation) In practice, how we store and identify assets is a reasonably superficial change (porting off of Assets as Entities and implementing dedicated storage + ids took less than a day). So once we sort out the remaining challenges the flip should be straightforward. Additionally, I do still have "Assets as Entities" in my commit history, so we can reuse that work. I personally think "assets as entities" is a good endgame, but it also doesn't provide _significant_ value at the moment and it certainly isn't ready yet with the current state of things. ### Why not Distill? [Distill](https://github.com/amethyst/distill) is a high quality fully featured asset system built in Rust. It is very natural to ask "why not just use Distill?". It is also worth calling out that for awhile, [we planned on adopting Distill / I signed off on it](https://github.com/bevyengine/bevy/issues/708). However I think Bevy has a number of constraints that make Distill adoption suboptimal: * **Architectural Simplicity:** * Distill's processor requires an in-memory database (lmdb) and RPC networked API (using Cap'n Proto). Each of these introduces API complexity that increases maintenance burden and "code grokability". Ignoring tests, documentation, and examples, Distill has 24,237 lines of Rust code (including generated code for RPC + database interactions). If you ignore generated code, it has 11,499 lines. * Bevy builds the AssetProcessor and AssetServer using pluggable AssetReader/AssetWriter Rust traits with simple io interfaces. They do not necessitate databases or RPC interfaces (although Readers/Writers could use them if that is desired). Bevy Asset V2 (at the time of writing this PR) is 5,384 lines of Rust code (ignoring tests, documentation, and examples). Grain of salt: Distill does have more features currently (ex: Asset Packing, GUIDS, remote-out-of-process asset processor). I do plan to implement these features in Bevy Asset V2 and I personally highly doubt they will meaningfully close the 6115 lines-of-code gap. * This complexity gap (which while illustrated by lines of code, is much bigger than just that) is noteworthy to me. Bevy should be hackable and there are pillars of Distill that are very hard to understand and extend. This is a matter of opinion (and Bevy Asset V2 also has complicated areas), but I think Bevy Asset V2 is much more approachable for the average developer. * Necessary disclaimer: counting lines of code is an extremely rough complexity metric. Read the code and form your own opinions. * **Optional Asset Processing:** Not all Bevy Apps (or Bevy App developers) need / want asset preprocessing. Processing increases the complexity of the development environment by introducing things like meta files, imported asset storage, running processors in the background, waiting for processing to finish, etc. Distill _requires_ preprocessing to work. With Bevy Asset V2 processing is fully opt-in. The AssetServer isn't directly aware of asset processors at all. AssetLoaders only care about converting bytes to runtime Assets ... they don't know or care if the bytes were pre-processed or not. Processing is "elegantly" (forgive my self-congratulatory phrasing) layered on top and builds on the existing Asset system primitives. * **Direct Filesystem Access to Processed Asset State:** Distill stores processed assets in a database. This makes debugging / inspecting the processed outputs harder (either requires special tooling to query the database or they need to be "deployed" to be inspected). Bevy Asset V2, on the other hand, stores processed assets in the filesystem (by default ... this is configurable). This makes interacting with the processed state more natural. Note that both Godot and Unity's new asset system store processed assets in the filesystem. * **Portability**: Because Distill's processor uses lmdb and RPC networking, it cannot be run on certain platforms (ex: lmdb is a non-rust dependency that cannot run on the web, some platforms don't support running network servers). Bevy should be able to process assets everywhere (ex: run the Bevy Editor on the web, compile + process shaders on mobile, etc). Distill does partially mitigate this problem by supporting "streaming" assets via the RPC protocol, but this is not a full solve from my perspective. And Bevy Asset V2 can (in theory) also stream assets (without requiring RPC, although this isn't implemented yet) Note that I _do_ still think Distill would be a solid asset system for Bevy. But I think the approach in this PR is a better solve for Bevy's specific "asset system requirements". ### Doesn't async-fs just shim requests to "sync" `std::fs`? What is the point? "True async file io" has limited / spotty platform support. async-fs (and the rust async ecosystem generally ... ex Tokio) currently use async wrappers over std::fs that offload blocking requests to separate threads. This may feel unsatisfying, but it _does_ still provide value because it prevents our task pools from blocking on file system operations (which would prevent progress when there are many tasks to do, but all threads in a pool are currently blocking on file system ops). Additionally, using async APIs for our AssetReaders and AssetWriters also provides value because we can later add support for "true async file io" for platforms that support it. _And_ we can implement other "true async io" asset backends (such as networked asset io). ## Draft TODO - [x] Fill in missing filesystem event APIs: file removed event (which is expressed as dangling RenameFrom events in some cases), file/folder renamed event - [x] Assets without loaders are not moved to the processed folder. This breaks things like referenced `.bin` files for GLTFs. This should be configurable per-non-asset-type. - [x] Initial implementation of Reflect and FromReflect for Handle. The "deserialization" parity bar is low here as this only worked with static UUIDs in the old impl ... this is a non-trivial problem. Either we add a Handle::AssetPath variant that gets "upgraded" to a strong handle on scene load or we use a separate AssetRef type for Bevy scenes (which is converted to a runtime Handle on load). This deserves its own discussion in a different pr. - [x] Populate read_asset_bytes hash when run by the processor (a bit of a special case .. when run by the processor the processed meta will contain the hash so we don't need to compute it on the spot, but we don't want/need to read the meta when run by the main AssetServer) - [x] Delay hot reloading: currently filesystem events are handled immediately, which creates timing issues in some cases. For example hot reloading images can sometimes break because the image isn't finished writing. We should add a delay, likely similar to the [implementation in this PR](https://github.com/bevyengine/bevy/pull/8503). - [x] Port old platform-specific AssetIo implementations to the new AssetReader interface (currently missing Android and web) - [x] Resolve on_loaded unsafety (either by removing the API entirely or removing the unsafe) - [x] Runtime loader setting overrides - [x] Remove remaining unwraps that should be error-handled. There are number of TODOs here - [x] Pretty AssetPath Display impl - [x] Document more APIs - [x] Resolve spurious "reloading because it has changed" events (to repro run load_gltf with `processed_dev()`) - [x] load_dependency hot reloading currently only works for processed assets. If processing is disabled, load_dependency changes are not hot reloaded. - [x] Replace AssetInfo dependency load/fail counters with `loading_dependencies: HashSet<UntypedAssetId>` to prevent reloads from (potentially) breaking counters. Storing this will also enable "dependency reloaded" events (see [Next Steps](#next-steps)) - [x] Re-add filesystem watcher cargo feature gate (currently it is not optional) - [ ] Migration Guide - [ ] Changelog ## Followup TODO - [ ] Replace "eager unchanged processed asset loading" behavior with "don't returned unchanged processed asset until dependencies have been checked". - [ ] Add true `Ignore` AssetAction that does not copy the asset to the imported_assets folder. - [ ] Finish "live asset unloading" (ex: free up CPU asset memory after uploading an image to the GPU), rethink RenderAssets, and port renderer features. The `Assets` collection uses `Option<T>` for asset storage to support its removal. (1) the Option might not actually be necessary ... might be able to just remove from the collection entirely (2) need to finalize removal apis - [ ] Try replacing the "channel based" asset id recycling with something a bit more efficient (ex: we might be able to use raw atomic ints with some cleverness) - [ ] Consider adding UUIDs to processed assets (scoped just to helping identify moved assets ... not exposed to load queries ... see [Next Steps](#next-steps)) - [ ] Store "last modified" source asset and meta timestamps in processed meta files to enable skipping expensive hashing when the file wasn't changed - [ ] Fix "slow loop" handle drop fix - [ ] Migrate to TypeName - [x] Handle "loader preregistration". See #9429 ## Next Steps * **Configurable per-type defaults for AssetMeta**: It should be possible to add configuration like "all png image meta should default to using nearest sampling" (currently this hard-coded per-loader/processor Settings::default() impls). Also see the "Folder Meta" bullet point. * **Avoid Reprocessing on Asset Renames / Moves**: See the "canonical asset ids" discussion in [Open Questions](#open-questions) and the relevant bullet point in [Draft TODO](#draft-todo). Even without canonical ids, folder renames could avoid reprocessing in some cases. * **Multiple Asset Sources**: Expand AssetPath to support "asset source names" and support multiple AssetReaders in the asset server (ex: `webserver://some_path/image.png` backed by an Http webserver AssetReader). The "default" asset reader would use normal `some_path/image.png` paths. Ideally this works in combination with multiple AssetWatchers for hot-reloading * **Stable Type Names**: this pr removes the TypeUuid requirement from assets in favor of `std::any::type_name`. This makes defining assets easier (no need to generate a new uuid / use weird proc macro syntax). It also makes reading meta files easier (because things have "friendly names"). We also use type names for components in scene files. If they are good enough for components, they are good enough for assets. And consistency across Bevy pillars is desirable. However, `std::any::type_name` is not guaranteed to be stable (although in practice it is). We've developed a [stable type path](https://github.com/bevyengine/bevy/pull/7184) to resolve this, which should be adopted when it is ready. * **Command Line Interface**: It should be possible to run the asset processor in a separate process from the command line. This will also require building a network-server-backed AssetReader to communicate between the app and the processor. We've been planning to build a "bevy cli" for awhile. This seems like a good excuse to build it. * **Asset Packing**: This is largely an additive feature, so it made sense to me to punt this until we've laid the foundations in this PR. * **Per-Platform Processed Assets**: It should be possible to generate assets for multiple platforms by supporting multiple "processor profiles" per asset (ex: compress with format X on PC and Y on iOS). I think there should probably be arbitrary "profiles" (which can be separate from actual platforms), which are then assigned to a given platform when generating the final asset distribution for that platform. Ex: maybe devs want a "Mobile" profile that is shared between iOS and Android. Or a "LowEnd" profile shared between web and mobile. * **Versioning and Migrations**: Assets, Loaders, Savers, and Processors need to have versions to determine if their schema is valid. If an asset / loader version is incompatible with the current version expected at runtime, the processor should be able to migrate them. I think we should try using Bevy Reflect for this, as it would allow us to load the old version as a dynamic Reflect type without actually having the old Rust type. It would also allow us to define "patches" to migrate between versions (Bevy Reflect devs are currently working on patching). The `.meta` file already has its own format version. Migrating that to new versions should also be possible. * **Real Copy-on-write AssetPaths**: Rust's actual Cow (clone-on-write type) currently used by AssetPath can still result in String clones that aren't actually necessary (cloning an Owned Cow clones the contents). Bevy's asset system requires cloning AssetPaths in a number of places, which result in actual clones of the internal Strings. This is not efficient. AssetPath internals should be reworked to exhibit truer cow-like-behavior that reduces String clones to the absolute minimum. * **Consider processor-less processing**: In theory the AssetServer could run processors "inline" even if the background AssetProcessor is disabled. If we decide this is actually desirable, we could add this. But I don't think its a priority in the short or medium term. * **Pre-emptive dependency loading**: We could encode dependencies in processed meta files, which could then be used by the Asset Server to kick of dependency loads as early as possible (prior to starting the actual asset load). Is this desirable? How much time would this save in practice? * **Optimize Processor With UntypedAssetIds**: The processor exclusively uses AssetPath to identify assets currently. It might be possible to swap these out for UntypedAssetIds in some places, which are smaller / cheaper to hash and compare. * **One to Many Asset Processing**: An asset source file that produces many assets currently must be processed into a single "processed" asset source. If labeled assets can be written separately they can each have their own configured savers _and_ they could be loaded more granularly. Definitely worth exploring! * **Automatically Track "Runtime-only" Asset Dependencies**: Right now, tracking "created at runtime" asset dependencies requires adding them via `asset_server.load_asset(StandardMaterial::default())`. I think with some cleverness we could also do this for `materials.add(StandardMaterial::default())`, making tracking work "everywhere". There are challenges here relating to change detection / ensuring the server is made aware of dependency changes. This could be expensive in some cases. * **"Dependency Changed" events**: Some assets have runtime artifacts that need to be re-generated when one of their dependencies change (ex: regenerate a material's bind group when a Texture needs to change). We are generating the dependency graph so we can definitely produce these events. Buuuuut generating these events will have a cost / they could be high frequency for some assets, so we might want this to be opt-in for specific cases. * **Investigate Storing More Information In Handles**: Handles can now store arbitrary information, which makes it cheaper and easier to access. How much should we move into them? Canonical asset load states (via atomics)? (`handle.is_loaded()` would be very cool). Should we store the entire asset and remove the `Assets<T>` collection? (`Arc<RwLock<Option<Image>>>`?) * **Support processing and loading files without extensions**: This is a pretty arbitrary restriction and could be supported with very minimal changes. * **Folder Meta**: It would be nice if we could define per folder processor configuration defaults (likely in a `.meta` or `.folder_meta` file). Things like "default to linear filtering for all Images in this folder". * **Replace async_broadcast with event-listener?** This might be approximately drop-in for some uses and it feels more light weight * **Support Running the AssetProcessor on the Web**: Most of the hard work is done here, but there are some easy straggling TODOs (make the transaction log an interface instead of a direct file writer so we can write a web storage backend, implement an AssetReader/AssetWriter that reads/writes to something like LocalStorage). * **Consider identifying and preventing circular dependencies**: This is especially important for "processor dependencies", as processing will silently never finish in these cases. * **Built-in/Inlined Asset Hot Reloading**: This PR regresses "built-in/inlined" asset hot reloading (previously provided by the DebugAssetServer). I'm intentionally punting this because I think it can be cleanly implemented with "multiple asset sources" by registering a "debug asset source" (ex: `debug://bevy_pbr/src/render/pbr.wgsl` asset paths) in combination with an AssetWatcher for that asset source and support for "manually loading pats with asset bytes instead of AssetReaders". The old DebugAssetServer was quite nasty and I'd love to avoid that hackery going forward. * **Investigate ways to remove double-parsing meta files**: Parsing meta files currently involves parsing once with "minimal" versions of the meta file to extract the type name of the loader/processor config, then parsing again to parse the "full" meta. This is suboptimal. We should be able to define custom deserializers that (1) assume the loader/processor type name comes first (2) dynamically looks up the loader/processor registrations to deserialize settings in-line (similar to components in the bevy scene format). Another alternative: deserialize as dynamic Reflect objects and then convert. * **More runtime loading configuration**: Support using the Handle type as a hint to select an asset loader (instead of relying on AssetPath extensions) * **More high level Processor trait implementations**: For example, it might be worth adding support for arbitrary chains of "asset transforms" that modify an in-memory asset representation between loading and saving. (ex: load a Mesh, run a `subdivide_mesh` transform, followed by a `flip_normals` transform, then save the mesh to an efficient compressed format). * **Bevy Scene Handle Deserialization**: (see the relevant [Draft TODO item](#draft-todo) for context) * **Explore High Level Load Interfaces**: See [this discussion](#discuss-on_loaded-high-level-interface) for one prototype. * **Asset Streaming**: It would be great if we could stream Assets (ex: stream a long video file piece by piece) * **ID Exchanging**: In this PR Asset Handles/AssetIds are bigger than they need to be because they have a Uuid enum variant. If we implement an "id exchanging" system that trades Uuids for "efficient runtime ids", we can cut down on the size of AssetIds, making them more efficient. This has some open design questions, such as how to spawn entities with "default" handle values (as these wouldn't have access to the exchange api in the current system). * **Asset Path Fixup Tooling**: Assets that inline asset paths inside them will break when an asset moves. The asset system provides the functionality to detect when paths break. We should build a framework that enables formats to define "path migrations". This is especially important for scene files. For editor-generated files, we should also consider using UUIDs (see other bullet point) to avoid the need to migrate in these cases. --------- Co-authored-by: BeastLe9enD <beastle9end@outlook.de> Co-authored-by: Mike <mike.hsu@gmail.com> Co-authored-by: Nicola Papale <nicopap@users.noreply.github.com>
2023-09-07 02:07:27 +00:00
# Enables watching the filesystem for Bevy Asset hot-reloading
Multiple Asset Sources (#9885) This adds support for **Multiple Asset Sources**. You can now register a named `AssetSource`, which you can load assets from like you normally would: ```rust let shader: Handle<Shader> = asset_server.load("custom_source://path/to/shader.wgsl"); ``` Notice that `AssetPath` now supports `some_source://` syntax. This can now be accessed through the `asset_path.source()` accessor. Asset source names _are not required_. If one is not specified, the default asset source will be used: ```rust let shader: Handle<Shader> = asset_server.load("path/to/shader.wgsl"); ``` The behavior of the default asset source has not changed. Ex: the `assets` folder is still the default. As referenced in #9714 ## Why? **Multiple Asset Sources** enables a number of often-asked-for scenarios: * **Loading some assets from other locations on disk**: you could create a `config` asset source that reads from the OS-default config folder (not implemented in this PR) * **Loading some assets from a remote server**: you could register a new `remote` asset source that reads some assets from a remote http server (not implemented in this PR) * **Improved "Binary Embedded" Assets**: we can use this system for "embedded-in-binary assets", which allows us to replace the old `load_internal_asset!` approach, which couldn't support asset processing, didn't support hot-reloading _well_, and didn't make embedded assets accessible to the `AssetServer` (implemented in this pr) ## Adding New Asset Sources An `AssetSource` is "just" a collection of `AssetReader`, `AssetWriter`, and `AssetWatcher` entries. You can configure new asset sources like this: ```rust app.register_asset_source( "other", AssetSource::build() .with_reader(|| Box::new(FileAssetReader::new("other"))) ) ) ``` Note that `AssetSource` construction _must_ be repeatable, which is why a closure is accepted. `AssetSourceBuilder` supports `with_reader`, `with_writer`, `with_watcher`, `with_processed_reader`, `with_processed_writer`, and `with_processed_watcher`. Note that the "asset source" system replaces the old "asset providers" system. ## Processing Multiple Sources The `AssetProcessor` now supports multiple asset sources! Processed assets can refer to assets in other sources and everything "just works". Each `AssetSource` defines an unprocessed and processed `AssetReader` / `AssetWriter`. Currently this is all or nothing for a given `AssetSource`. A given source is either processed or it is not. Later we might want to add support for "lazy asset processing", where an `AssetSource` (such as a remote server) can be configured to only process assets that are directly referenced by local assets (in order to save local disk space and avoid doing extra work). ## A new `AssetSource`: `embedded` One of the big features motivating **Multiple Asset Sources** was improving our "embedded-in-binary" asset loading. To prove out the **Multiple Asset Sources** implementation, I chose to build a new `embedded` `AssetSource`, which replaces the old `load_interal_asset!` system. The old `load_internal_asset!` approach had a number of issues: * The `AssetServer` was not aware of (or capable of loading) internal assets. * Because internal assets weren't visible to the `AssetServer`, they could not be processed (or used by assets that are processed). This would prevent things "preprocessing shaders that depend on built in Bevy shaders", which is something we desperately need to start doing. * Each "internal asset" needed a UUID to be defined in-code to reference it. This was very manual and toilsome. The new `embedded` `AssetSource` enables the following pattern: ```rust // Called in `crates/bevy_pbr/src/render/mesh.rs` embedded_asset!(app, "mesh.wgsl"); // later in the app let shader: Handle<Shader> = asset_server.load("embedded://bevy_pbr/render/mesh.wgsl"); ``` Notice that this always treats the crate name as the "root path", and it trims out the `src` path for brevity. This is generally predictable, but if you need to debug you can use the new `embedded_path!` macro to get a `PathBuf` that matches the one used by `embedded_asset`. You can also reference embedded assets in arbitrary assets, such as WGSL shaders: ```rust #import "embedded://bevy_pbr/render/mesh.wgsl" ``` This also makes `embedded` assets go through the "normal" asset lifecycle. They are only loaded when they are actually used! We are also discussing implicitly converting asset paths to/from shader modules, so in the future (not in this PR) you might be able to load it like this: ```rust #import bevy_pbr::render::mesh::Vertex ``` Compare that to the old system! ```rust pub const MESH_SHADER_HANDLE: Handle<Shader> = Handle::weak_from_u128(3252377289100772450); load_internal_asset!(app, MESH_SHADER_HANDLE, "mesh.wgsl", Shader::from_wgsl); // The mesh asset is the _only_ accessible via MESH_SHADER_HANDLE and _cannot_ be loaded via the AssetServer. ``` ## Hot Reloading `embedded` You can enable `embedded` hot reloading by enabling the `embedded_watcher` cargo feature: ``` cargo run --features=embedded_watcher ``` ## Improved Hot Reloading Workflow First: the `filesystem_watcher` cargo feature has been renamed to `file_watcher` for brevity (and to match the `FileAssetReader` naming convention). More importantly, hot asset reloading is no longer configured in-code by default. If you enable any asset watcher feature (such as `file_watcher` or `rust_source_watcher`), asset watching will be automatically enabled. This removes the need to _also_ enable hot reloading in your app code. That means you can replace this: ```rust app.add_plugins(DefaultPlugins.set(AssetPlugin::default().watch_for_changes())) ``` with this: ```rust app.add_plugins(DefaultPlugins) ``` If you want to hot reload assets in your app during development, just run your app like this: ``` cargo run --features=file_watcher ``` This means you can use the same code for development and deployment! To deploy an app, just don't include the watcher feature ``` cargo build --release ``` My intent is to move to this approach for pretty much all dev workflows. In a future PR I would like to replace `AssetMode::ProcessedDev` with a `runtime-processor` cargo feature. We could then group all common "dev" cargo features under a single `dev` feature: ```sh # this would enable file_watcher, embedded_watcher, runtime-processor, and more cargo run --features=dev ``` ## AssetMode `AssetPlugin::Unprocessed`, `AssetPlugin::Processed`, and `AssetPlugin::ProcessedDev` have been replaced with an `AssetMode` field on `AssetPlugin`. ```rust // before app.add_plugins(DefaultPlugins.set(AssetPlugin::Processed { /* fields here */ }) // after app.add_plugins(DefaultPlugins.set(AssetPlugin { mode: AssetMode::Processed, ..default() }) ``` This aligns `AssetPlugin` with our other struct-like plugins. The old "source" and "destination" `AssetProvider` fields in the enum variants have been replaced by the "asset source" system. You no longer need to configure the AssetPlugin to "point" to custom asset providers. ## AssetServerMode To improve the implementation of **Multiple Asset Sources**, `AssetServer` was made aware of whether or not it is using "processed" or "unprocessed" assets. You can check that like this: ```rust if asset_server.mode() == AssetServerMode::Processed { /* do something */ } ``` Note that this refactor should also prepare the way for building "one to many processed output files", as it makes the server aware of whether it is loading from processed or unprocessed sources. Meaning we can store and read processed and unprocessed assets differently! ## AssetPath can now refer to folders The "file only" restriction has been removed from `AssetPath`. The `AssetServer::load_folder` API now accepts an `AssetPath` instead of a `Path`, meaning you can load folders from other asset sources! ## Improved AssetPath Parsing AssetPath parsing was reworked to support sources, improve error messages, and to enable parsing with a single pass over the string. `AssetPath::new` was replaced by `AssetPath::parse` and `AssetPath::try_parse`. ## AssetWatcher broken out from AssetReader `AssetReader` is no longer responsible for constructing `AssetWatcher`. This has been moved to `AssetSourceBuilder`. ## Duplicate Event Debouncing Asset V2 already debounced duplicate filesystem events, but this was _input_ events. Multiple input event types can produce the same _output_ `AssetSourceEvent`. Now that we have `embedded_watcher`, which does expensive file io on events, it made sense to debounce output events too, so I added that! This will also benefit the AssetProcessor by preventing integrity checks for duplicate events (and helps keep the noise down in trace logs). ## Next Steps * **Port Built-in Shaders**: Currently the primary (and essentially only) user of `load_interal_asset` in Bevy's source code is "built-in shaders". I chose not to do that in this PR for a few reasons: 1. We need to add the ability to pass shader defs in to shaders via meta files. Some shaders (such as MESH_VIEW_TYPES) need to pass shader def values in that are defined in code. 2. We need to revisit the current shader module naming system. I think we _probably_ want to imply modules from source structure (at least by default). Ideally in a way that can losslessly convert asset paths to/from shader modules (to enable the asset system to resolve modules using the asset server). 3. I want to keep this change set minimal / get this merged first. * **Deprecate `load_internal_asset`**: we can't do that until we do (1) and (2) * **Relative Asset Paths**: This PR significantly increases the need for relative asset paths (which was already pretty high). Currently when loading dependencies, it is assumed to be an absolute path, which means if in an `AssetLoader` you call `context.load("some/path/image.png")` it will assume that is the "default" asset source, _even if the current asset is in a different asset source_. This will cause breakage for AssetLoaders that are not designed to add the current source to whatever paths are being used. AssetLoaders should generally not need to be aware of the name of their current asset source, or need to think about the "current asset source" generally. We should build apis that support relative asset paths and then encourage using relative paths as much as possible (both via api design and docs). Relative paths are also important because they will allow developers to move folders around (even across providers) without reprocessing, provided there is no path breakage.
2023-10-13 23:17:32 +00:00
file_watcher = ["bevy_internal/file_watcher"]
# Enables watching in memory asset providers for Bevy Asset hot-reloading
embedded_watcher = ["bevy_internal/embedded_watcher"]
Bevy Asset V2 (#8624) # Bevy Asset V2 Proposal ## Why Does Bevy Need A New Asset System? Asset pipelines are a central part of the gamedev process. Bevy's current asset system is missing a number of features that make it non-viable for many classes of gamedev. After plenty of discussions and [a long community feedback period](https://github.com/bevyengine/bevy/discussions/3972), we've identified a number missing features: * **Asset Preprocessing**: it should be possible to "preprocess" / "compile" / "crunch" assets at "development time" rather than when the game starts up. This enables offloading expensive work from deployed apps, faster asset loading, less runtime memory usage, etc. * **Per-Asset Loader Settings**: Individual assets cannot define their own loaders that override the defaults. Additionally, they cannot provide per-asset settings to their loaders. This is a huge limitation, as many asset types don't provide all information necessary for Bevy _inside_ the asset. For example, a raw PNG image says nothing about how it should be sampled (ex: linear vs nearest). * **Asset `.meta` files**: assets should have configuration files stored adjacent to the asset in question, which allows the user to configure asset-type-specific settings. These settings should be accessible during the pre-processing phase. Modifying a `.meta` file should trigger a re-processing / re-load of the asset. It should be possible to configure asset loaders from the meta file. * **Processed Asset Hot Reloading**: Changes to processed assets (or their dependencies) should result in re-processing them and re-loading the results in live Bevy Apps. * **Asset Dependency Tracking**: The current bevy_asset has no good way to wait for asset dependencies to load. It punts this as an exercise for consumers of the loader apis, which is unreasonable and error prone. There should be easy, ergonomic ways to wait for assets to load and block some logic on an asset's entire dependency tree loading. * **Runtime Asset Loading**: it should be (optionally) possible to load arbitrary assets dynamically at runtime. This necessitates being able to deploy and run the asset server alongside Bevy Apps on _all platforms_. For example, we should be able to invoke the shader compiler at runtime, stream scenes from sources like the internet, etc. To keep deployed binaries (and startup times) small, the runtime asset server configuration should be configurable with different settings compared to the "pre processor asset server". * **Multiple Backends**: It should be possible to load assets from arbitrary sources (filesystems, the internet, remote asset serves, etc). * **Asset Packing**: It should be possible to deploy assets in compressed "packs", which makes it easier and more efficient to distribute assets with Bevy Apps. * **Asset Handoff**: It should be possible to hold a "live" asset handle, which correlates to runtime data, without actually holding the asset in memory. Ex: it must be possible to hold a reference to a GPU mesh generated from a "mesh asset" without keeping the mesh data in CPU memory * **Per-Platform Processed Assets**: Different platforms and app distributions have different capabilities and requirements. Some platforms need lower asset resolutions or different asset formats to operate within the hardware constraints of the platform. It should be possible to define per-platform asset processing profiles. And it should be possible to deploy only the assets required for a given platform. These features have architectural implications that are significant enough to require a full rewrite. The current Bevy Asset implementation got us this far, but it can take us no farther. This PR defines a brand new asset system that implements most of these features, while laying the foundations for the remaining features to be built. ## Bevy Asset V2 Here is a quick overview of the features introduced in this PR. * **Asset Preprocessing**: Preprocess assets at development time into more efficient (and configurable) representations * **Dependency Aware**: Dependencies required to process an asset are tracked. If an asset's processed dependency changes, it will be reprocessed * **Hot Reprocessing/Reloading**: detect changes to asset source files, reprocess them if they have changed, and then hot-reload them in Bevy Apps. * **Only Process Changes**: Assets are only re-processed when their source file (or meta file) has changed. This uses hashing and timestamps to avoid processing assets that haven't changed. * **Transactional and Reliable**: Uses write-ahead logging (a technique commonly used by databases) to recover from crashes / forced-exits. Whenever possible it avoids full-reprocessing / only uncompleted transactions will be reprocessed. When the processor is running in parallel with a Bevy App, processor asset writes block Bevy App asset reads. Reading metadata + asset bytes is guaranteed to be transactional / correctly paired. * **Portable / Run anywhere / Database-free**: The processor does not rely on an in-memory database (although it uses some database techniques for reliability). This is important because pretty much all in-memory databases have unsupported platforms or build complications. * **Configure Processor Defaults Per File Type**: You can say "use this processor for all files of this type". * **Custom Processors**: The `Processor` trait is flexible and unopinionated. It can be implemented by downstream plugins. * **LoadAndSave Processors**: Most asset processing scenarios can be expressed as "run AssetLoader A, save the results using AssetSaver X, and then load the result using AssetLoader B". For example, load this png image using `PngImageLoader`, which produces an `Image` asset and then save it using `CompressedImageSaver` (which also produces an `Image` asset, but in a compressed format), which takes an `Image` asset as input. This means if you have an `AssetLoader` for an asset, you are already half way there! It also means that you can share AssetSavers across multiple loaders. Because `CompressedImageSaver` accepts Bevy's generic Image asset as input, it means you can also use it with some future `JpegImageLoader`. * **Loader and Saver Settings**: Asset Loaders and Savers can now define their own settings types, which are passed in as input when an asset is loaded / saved. Each asset can define its own settings. * **Asset `.meta` files**: configure asset loaders, their settings, enable/disable processing, and configure processor settings * **Runtime Asset Dependency Tracking** Runtime asset dependencies (ex: if an asset contains a `Handle<Image>`) are tracked by the asset server. An event is emitted when an asset and all of its dependencies have been loaded * **Unprocessed Asset Loading**: Assets do not require preprocessing. They can be loaded directly. A processed asset is just a "normal" asset with some extra metadata. Asset Loaders don't need to know or care about whether or not an asset was processed. * **Async Asset IO**: Asset readers/writers use async non-blocking interfaces. Note that because Rust doesn't yet support async traits, there is a bit of manual Boxing / Future boilerplate. This will hopefully be removed in the near future when Rust gets async traits. * **Pluggable Asset Readers and Writers**: Arbitrary asset source readers/writers are supported, both by the processor and the asset server. * **Better Asset Handles** * **Single Arc Tree**: Asset Handles now use a single arc tree that represents the lifetime of the asset. This makes their implementation simpler, more efficient, and allows us to cheaply attach metadata to handles. Ex: the AssetPath of a handle is now directly accessible on the handle itself! * **Const Typed Handles**: typed handles can be constructed in a const context. No more weird "const untyped converted to typed at runtime" patterns! * **Handles and Ids are Smaller / Faster To Hash / Compare**: Typed `Handle<T>` is now much smaller in memory and `AssetId<T>` is even smaller. * **Weak Handle Usage Reduction**: In general Handles are now considered to be "strong". Bevy features that previously used "weak `Handle<T>`" have been ported to `AssetId<T>`, which makes it statically clear that the features do not hold strong handles (while retaining strong type information). Currently Handle::Weak still exists, but it is very possible that we can remove that entirely. * **Efficient / Dense Asset Ids**: Assets now have efficient dense runtime asset ids, which means we can avoid expensive hash lookups. Assets are stored in Vecs instead of HashMaps. There are now typed and untyped ids, which means we no longer need to store dynamic type information in the ID for typed handles. "AssetPathId" (which was a nightmare from a performance and correctness standpoint) has been entirely removed in favor of dense ids (which are retrieved for a path on load) * **Direct Asset Loading, with Dependency Tracking**: Assets that are defined at runtime can still have their dependencies tracked by the Asset Server (ex: if you create a material at runtime, you can still wait for its textures to load). This is accomplished via the (currently optional) "asset dependency visitor" trait. This system can also be used to define a set of assets to load, then wait for those assets to load. * **Async folder loading**: Folder loading also uses this system and immediately returns a handle to the LoadedFolder asset, which means folder loading no longer blocks on directory traversals. * **Improved Loader Interface**: Loaders now have a specific "top level asset type", which makes returning the top-level asset simpler and statically typed. * **Basic Image Settings and Processing**: Image assets can now be processed into the gpu-friendly Basic Universal format. The ImageLoader now has a setting to define what format the image should be loaded as. Note that this is just a minimal MVP ... plenty of additional work to do here. To demo this, enable the `basis-universal` feature and turn on asset processing. * **Simpler Audio Play / AudioSink API**: Asset handle providers are cloneable, which means the Audio resource can mint its own handles. This means you can now do `let sink_handle = audio.play(music)` instead of `let sink_handle = audio_sinks.get_handle(audio.play(music))`. Note that this might still be replaced by https://github.com/bevyengine/bevy/pull/8424. **Removed Handle Casting From Engine Features**: Ex: FontAtlases no longer use casting between handle types ## Using The New Asset System ### Normal Unprocessed Asset Loading By default the `AssetPlugin` does not use processing. It behaves pretty much the same way as the old system. If you are defining a custom asset, first derive `Asset`: ```rust #[derive(Asset)] struct Thing { value: String, } ``` Initialize the asset: ```rust app.init_asset:<Thing>() ``` Implement a new `AssetLoader` for it: ```rust #[derive(Default)] struct ThingLoader; #[derive(Serialize, Deserialize, Default)] pub struct ThingSettings { some_setting: bool, } impl AssetLoader for ThingLoader { type Asset = Thing; type Settings = ThingSettings; fn load<'a>( &'a self, reader: &'a mut Reader, settings: &'a ThingSettings, load_context: &'a mut LoadContext, ) -> BoxedFuture<'a, Result<Thing, anyhow::Error>> { Box::pin(async move { let mut bytes = Vec::new(); reader.read_to_end(&mut bytes).await?; // convert bytes to value somehow Ok(Thing { value }) }) } fn extensions(&self) -> &[&str] { &["thing"] } } ``` Note that this interface will get much cleaner once Rust gets support for async traits. `Reader` is an async futures_io::AsyncRead. You can stream bytes as they come in or read them all into a `Vec<u8>`, depending on the context. You can use `let handle = load_context.load(path)` to kick off a dependency load, retrieve a handle, and register the dependency for the asset. Then just register the loader in your Bevy app: ```rust app.init_asset_loader::<ThingLoader>() ``` Now just add your `Thing` asset files into the `assets` folder and load them like this: ```rust fn system(asset_server: Res<AssetServer>) { let handle = Handle<Thing> = asset_server.load("cool.thing"); } ``` You can check load states directly via the asset server: ```rust if asset_server.load_state(&handle) == LoadState::Loaded { } ``` You can also listen for events: ```rust fn system(mut events: EventReader<AssetEvent<Thing>>, handle: Res<SomeThingHandle>) { for event in events.iter() { if event.is_loaded_with_dependencies(&handle) { } } } ``` Note the new `AssetEvent::LoadedWithDependencies`, which only fires when the asset is loaded _and_ all dependencies (and their dependencies) have loaded. Unlike the old asset system, for a given asset path all `Handle<T>` values point to the same underlying Arc. This means Handles can cheaply hold more asset information, such as the AssetPath: ```rust // prints the AssetPath of the handle info!("{:?}", handle.path()) ``` ### Processed Assets Asset processing can be enabled via the `AssetPlugin`. When developing Bevy Apps with processed assets, do this: ```rust app.add_plugins(DefaultPlugins.set(AssetPlugin::processed_dev())) ``` This runs the `AssetProcessor` in the background with hot-reloading. It reads assets from the `assets` folder, processes them, and writes them to the `.imported_assets` folder. Asset loads in the Bevy App will wait for a processed version of the asset to become available. If an asset in the `assets` folder changes, it will be reprocessed and hot-reloaded in the Bevy App. When deploying processed Bevy apps, do this: ```rust app.add_plugins(DefaultPlugins.set(AssetPlugin::processed())) ``` This does not run the `AssetProcessor` in the background. It behaves like `AssetPlugin::unprocessed()`, but reads assets from `.imported_assets`. When the `AssetProcessor` is running, it will populate sibling `.meta` files for assets in the `assets` folder. Meta files for assets that do not have a processor configured look like this: ```rust ( meta_format_version: "1.0", asset: Load( loader: "bevy_render::texture::image_loader::ImageLoader", settings: ( format: FromExtension, ), ), ) ``` This is metadata for an image asset. For example, if you have `assets/my_sprite.png`, this could be the metadata stored at `assets/my_sprite.png.meta`. Meta files are totally optional. If no metadata exists, the default settings will be used. In short, this file says "load this asset with the ImageLoader and use the file extension to determine the image type". This type of meta file is supported in all AssetPlugin modes. If in `Unprocessed` mode, the asset (with the meta settings) will be loaded directly. If in `ProcessedDev` mode, the asset file will be copied directly to the `.imported_assets` folder. The meta will also be copied directly to the `.imported_assets` folder, but with one addition: ```rust ( meta_format_version: "1.0", processed_info: Some(( hash: 12415480888597742505, full_hash: 14344495437905856884, process_dependencies: [], )), asset: Load( loader: "bevy_render::texture::image_loader::ImageLoader", settings: ( format: FromExtension, ), ), ) ``` `processed_info` contains `hash` (a direct hash of the asset and meta bytes), `full_hash` (a hash of `hash` and the hashes of all `process_dependencies`), and `process_dependencies` (the `path` and `full_hash` of every process_dependency). A "process dependency" is an asset dependency that is _directly_ used when processing the asset. Images do not have process dependencies, so this is empty. When the processor is enabled, you can use the `Process` metadata config: ```rust ( meta_format_version: "1.0", asset: Process( processor: "bevy_asset::processor::process::LoadAndSave<bevy_render::texture::image_loader::ImageLoader, bevy_render::texture::compressed_image_saver::CompressedImageSaver>", settings: ( loader_settings: ( format: FromExtension, ), saver_settings: ( generate_mipmaps: true, ), ), ), ) ``` This configures the asset to use the `LoadAndSave` processor, which runs an AssetLoader and feeds the result into an AssetSaver (which saves the given Asset and defines a loader to load it with). (for terseness LoadAndSave will likely get a shorter/friendlier type name when [Stable Type Paths](#7184) lands). `LoadAndSave` is likely to be the most common processor type, but arbitrary processors are supported. `CompressedImageSaver` saves an `Image` in the Basis Universal format and configures the ImageLoader to load it as basis universal. The `AssetProcessor` will read this meta, run it through the LoadAndSave processor, and write the basis-universal version of the image to `.imported_assets`. The final metadata will look like this: ```rust ( meta_format_version: "1.0", processed_info: Some(( hash: 905599590923828066, full_hash: 9948823010183819117, process_dependencies: [], )), asset: Load( loader: "bevy_render::texture::image_loader::ImageLoader", settings: ( format: Format(Basis), ), ), ) ``` To try basis-universal processing out in Bevy examples, (for example `sprite.rs`), change `add_plugins(DefaultPlugins)` to `add_plugins(DefaultPlugins.set(AssetPlugin::processed_dev()))` and run with the `basis-universal` feature enabled: `cargo run --features=basis-universal --example sprite`. To create a custom processor, there are two main paths: 1. Use the `LoadAndSave` processor with an existing `AssetLoader`. Implement the `AssetSaver` trait, register the processor using `asset_processor.register_processor::<LoadAndSave<ImageLoader, CompressedImageSaver>>(image_saver.into())`. 2. Implement the `Process` trait directly and register it using: `asset_processor.register_processor(thing_processor)`. You can configure default processors for file extensions like this: ```rust asset_processor.set_default_processor::<ThingProcessor>("thing") ``` There is one more metadata type to be aware of: ```rust ( meta_format_version: "1.0", asset: Ignore, ) ``` This will ignore the asset during processing / prevent it from being written to `.imported_assets`. The AssetProcessor stores a transaction log at `.imported_assets/log` and uses it to gracefully recover from unexpected stops. This means you can force-quit the processor (and Bevy Apps running the processor in parallel) at arbitrary times! `.imported_assets` is "local state". It should _not_ be checked into source control. It should also be considered "read only". In practice, you _can_ modify processed assets and processed metadata if you really need to test something. But those modifications will not be represented in the hashes of the assets, so the processed state will be "out of sync" with the source assets. The processor _will not_ fix this for you. Either revert the change after you have tested it, or delete the processed files so they can be re-populated. ## Open Questions There are a number of open questions to be discussed. We should decide if they need to be addressed in this PR and if so, how we will address them: ### Implied Dependencies vs Dependency Enumeration There are currently two ways to populate asset dependencies: * **Implied via AssetLoaders**: if an AssetLoader loads an asset (and retrieves a handle), a dependency is added to the list. * **Explicit via the optional Asset::visit_dependencies**: if `server.load_asset(my_asset)` is called, it will call `my_asset.visit_dependencies`, which will grab dependencies that have been manually defined for the asset via the Asset trait impl (which can be derived). This means that defining explicit dependencies is optional for "loaded assets". And the list of dependencies is always accurate because loaders can only produce Handles if they register dependencies. If an asset was loaded with an AssetLoader, it only uses the implied dependencies. If an asset was created at runtime and added with `asset_server.load_asset(MyAsset)`, it will use `Asset::visit_dependencies`. However this can create a behavior mismatch between loaded assets and equivalent "created at runtime" assets if `Assets::visit_dependencies` doesn't exactly match the dependencies produced by the AssetLoader. This behavior mismatch can be resolved by completely removing "implied loader dependencies" and requiring `Asset::visit_dependencies` to supply dependency data. But this creates two problems: * It makes defining loaded assets harder and more error prone: Devs must remember to manually annotate asset dependencies with `#[dependency]` when deriving `Asset`. For more complicated assets (such as scenes), the derive likely wouldn't be sufficient and a manual `visit_dependencies` impl would be required. * Removes the ability to immediately kick off dependency loads: When AssetLoaders retrieve a Handle, they also immediately kick off an asset load for the handle, which means it can start loading in parallel _before_ the asset finishes loading. For large assets, this could be significant. (although this could be mitigated for processed assets if we store dependencies in the processed meta file and load them ahead of time) ### Eager ProcessorDev Asset Loading I made a controversial call in the interest of fast startup times ("time to first pixel") for the "processor dev mode configuration". When initializing the AssetProcessor, current processed versions of unchanged assets are yielded immediately, even if their dependencies haven't been checked yet for reprocessing. This means that non-current-state-of-filesystem-but-previously-valid assets might be returned to the App first, then hot-reloaded if/when their dependencies change and the asset is reprocessed. Is this behavior desirable? There is largely one alternative: do not yield an asset from the processor to the app until all of its dependencies have been checked for changes. In some common cases (load dependency has not changed since last run) this will increase startup time. The main question is "by how much" and is that slower startup time worth it in the interest of only yielding assets that are true to the current state of the filesystem. Should this be configurable? I'm starting to think we should only yield an asset after its (historical) dependencies have been checked for changes + processed as necessary, but I'm curious what you all think. ### Paths Are Currently The Only Canonical ID / Do We Want Asset UUIDs? In this implementation AssetPaths are the only canonical asset identifier (just like the previous Bevy Asset system and Godot). Moving assets will result in re-scans (and currently reprocessing, although reprocessing can easily be avoided with some changes). Asset renames/moves will break code and assets that rely on specific paths, unless those paths are fixed up. Do we want / need "stable asset uuids"? Introducing them is very possible: 1. Generate a UUID and include it in .meta files 2. Support UUID in AssetPath 3. Generate "asset indices" which are loaded on startup and map UUIDs to paths. 4 (maybe). Consider only supporting UUIDs for processed assets so we can generate quick-to-load indices instead of scanning meta files. The main "pro" is that assets referencing UUIDs don't need to be migrated when a path changes. The main "con" is that UUIDs cannot be "lazily resolved" like paths. They need a full view of all assets to answer the question "does this UUID exist". Which means UUIDs require the AssetProcessor to fully finish startup scans before saying an asset doesnt exist. And they essentially require asset pre-processing to use in apps, because scanning all asset metadata files at runtime to resolve a UUID is not viable for medium-to-large apps. It really requires a pre-generated UUID index, which must be loaded before querying for assets. I personally think this should be investigated in a separate PR. Paths aren't going anywhere ... _everyone_ uses filesystems (and filesystem-like apis) to manage their asset source files. I consider them permanent canonical asset information. Additionally, they behave well for both processed and unprocessed asset modes. Given that Bevy is supporting both, this feels like the right canonical ID to start with. UUIDS (and maybe even other indexed-identifier types) can be added later as necessary. ### Folder / File Naming Conventions All asset processing config currently lives in the `.imported_assets` folder. The processor transaction log is in `.imported_assets/log`. Processed assets are added to `.imported_assets/Default`, which will make migrating to processed asset profiles (ex: a `.imported_assets/Mobile` profile) a non-breaking change. It also allows us to create top-level files like `.imported_assets/log` without it being interpreted as an asset. Meta files currently have a `.meta` suffix. Do we like these names and conventions? ### Should the `AssetPlugin::processed_dev` configuration enable `watch_for_changes` automatically? Currently it does (which I think makes sense), but it does make it the only configuration that enables watch_for_changes by default. ### Discuss on_loaded High Level Interface: This PR includes a very rough "proof of concept" `on_loaded` system adapter that uses the `LoadedWithDependencies` event in combination with `asset_server.load_asset` dependency tracking to support this pattern ```rust fn main() { App::new() .init_asset::<MyAssets>() .add_systems(Update, on_loaded(create_array_texture)) .run(); } #[derive(Asset, Clone)] struct MyAssets { #[dependency] picture_of_my_cat: Handle<Image>, #[dependency] picture_of_my_other_cat: Handle<Image>, } impl FromWorld for ArrayTexture { fn from_world(world: &mut World) -> Self { picture_of_my_cat: server.load("meow.png"), picture_of_my_other_cat: server.load("meeeeeeeow.png"), } } fn spawn_cat(In(my_assets): In<MyAssets>, mut commands: Commands) { commands.spawn(SpriteBundle { texture: my_assets.picture_of_my_cat.clone(), ..default() }); commands.spawn(SpriteBundle { texture: my_assets.picture_of_my_other_cat.clone(), ..default() }); } ``` The implementation is _very_ rough. And it is currently unsafe because `bevy_ecs` doesn't expose some internals to do this safely from inside `bevy_asset`. There are plenty of unanswered questions like: * "do we add a Loadable" derive? (effectively automate the FromWorld implementation above) * Should `MyAssets` even be an Asset? (largely implemented this way because it elegantly builds on `server.load_asset(MyAsset { .. })` dependency tracking). We should think hard about what our ideal API looks like (and if this is a pattern we want to support). Not necessarily something we need to solve in this PR. The current `on_loaded` impl should probably be removed from this PR before merging. ## Clarifying Questions ### What about Assets as Entities? This Bevy Asset V2 proposal implementation initially stored Assets as ECS Entities. Instead of `AssetId<T>` + the `Assets<T>` resource it used `Entity` as the asset id and Asset values were just ECS components. There are plenty of compelling reasons to do this: 1. Easier to inline assets in Bevy Scenes (as they are "just" normal entities + components) 2. More flexible queries: use the power of the ECS to filter assets (ex: `Query<Mesh, With<Tree>>`). 3. Extensible. Users can add arbitrary component data to assets. 4. Things like "component visualization tools" work out of the box to visualize asset data. However Assets as Entities has a ton of caveats right now: * We need to be able to allocate entity ids without a direct World reference (aka rework id allocator in Entities ... i worked around this in my prototypes by just pre allocating big chunks of entities) * We want asset change events in addition to ECS change tracking ... how do we populate them when mutations can come from anywhere? Do we use Changed queries? This would require iterating over the change data for all assets every frame. Is this acceptable or should we implement a new "event based" component change detection option? * Reconciling manually created assets with asset-system managed assets has some nuance (ex: are they "loaded" / do they also have that component metadata?) * "how do we handle "static" / default entity handles" (ties in to the Entity Indices discussion: https://github.com/bevyengine/bevy/discussions/8319). This is necessary for things like "built in" assets and default handles in things like SpriteBundle. * Storing asset information as a component makes it easy to "invalidate" asset state by removing the component (or forcing modifications). Ideally we have ways to lock this down (some combination of Rust type privacy and ECS validation) In practice, how we store and identify assets is a reasonably superficial change (porting off of Assets as Entities and implementing dedicated storage + ids took less than a day). So once we sort out the remaining challenges the flip should be straightforward. Additionally, I do still have "Assets as Entities" in my commit history, so we can reuse that work. I personally think "assets as entities" is a good endgame, but it also doesn't provide _significant_ value at the moment and it certainly isn't ready yet with the current state of things. ### Why not Distill? [Distill](https://github.com/amethyst/distill) is a high quality fully featured asset system built in Rust. It is very natural to ask "why not just use Distill?". It is also worth calling out that for awhile, [we planned on adopting Distill / I signed off on it](https://github.com/bevyengine/bevy/issues/708). However I think Bevy has a number of constraints that make Distill adoption suboptimal: * **Architectural Simplicity:** * Distill's processor requires an in-memory database (lmdb) and RPC networked API (using Cap'n Proto). Each of these introduces API complexity that increases maintenance burden and "code grokability". Ignoring tests, documentation, and examples, Distill has 24,237 lines of Rust code (including generated code for RPC + database interactions). If you ignore generated code, it has 11,499 lines. * Bevy builds the AssetProcessor and AssetServer using pluggable AssetReader/AssetWriter Rust traits with simple io interfaces. They do not necessitate databases or RPC interfaces (although Readers/Writers could use them if that is desired). Bevy Asset V2 (at the time of writing this PR) is 5,384 lines of Rust code (ignoring tests, documentation, and examples). Grain of salt: Distill does have more features currently (ex: Asset Packing, GUIDS, remote-out-of-process asset processor). I do plan to implement these features in Bevy Asset V2 and I personally highly doubt they will meaningfully close the 6115 lines-of-code gap. * This complexity gap (which while illustrated by lines of code, is much bigger than just that) is noteworthy to me. Bevy should be hackable and there are pillars of Distill that are very hard to understand and extend. This is a matter of opinion (and Bevy Asset V2 also has complicated areas), but I think Bevy Asset V2 is much more approachable for the average developer. * Necessary disclaimer: counting lines of code is an extremely rough complexity metric. Read the code and form your own opinions. * **Optional Asset Processing:** Not all Bevy Apps (or Bevy App developers) need / want asset preprocessing. Processing increases the complexity of the development environment by introducing things like meta files, imported asset storage, running processors in the background, waiting for processing to finish, etc. Distill _requires_ preprocessing to work. With Bevy Asset V2 processing is fully opt-in. The AssetServer isn't directly aware of asset processors at all. AssetLoaders only care about converting bytes to runtime Assets ... they don't know or care if the bytes were pre-processed or not. Processing is "elegantly" (forgive my self-congratulatory phrasing) layered on top and builds on the existing Asset system primitives. * **Direct Filesystem Access to Processed Asset State:** Distill stores processed assets in a database. This makes debugging / inspecting the processed outputs harder (either requires special tooling to query the database or they need to be "deployed" to be inspected). Bevy Asset V2, on the other hand, stores processed assets in the filesystem (by default ... this is configurable). This makes interacting with the processed state more natural. Note that both Godot and Unity's new asset system store processed assets in the filesystem. * **Portability**: Because Distill's processor uses lmdb and RPC networking, it cannot be run on certain platforms (ex: lmdb is a non-rust dependency that cannot run on the web, some platforms don't support running network servers). Bevy should be able to process assets everywhere (ex: run the Bevy Editor on the web, compile + process shaders on mobile, etc). Distill does partially mitigate this problem by supporting "streaming" assets via the RPC protocol, but this is not a full solve from my perspective. And Bevy Asset V2 can (in theory) also stream assets (without requiring RPC, although this isn't implemented yet) Note that I _do_ still think Distill would be a solid asset system for Bevy. But I think the approach in this PR is a better solve for Bevy's specific "asset system requirements". ### Doesn't async-fs just shim requests to "sync" `std::fs`? What is the point? "True async file io" has limited / spotty platform support. async-fs (and the rust async ecosystem generally ... ex Tokio) currently use async wrappers over std::fs that offload blocking requests to separate threads. This may feel unsatisfying, but it _does_ still provide value because it prevents our task pools from blocking on file system operations (which would prevent progress when there are many tasks to do, but all threads in a pool are currently blocking on file system ops). Additionally, using async APIs for our AssetReaders and AssetWriters also provides value because we can later add support for "true async file io" for platforms that support it. _And_ we can implement other "true async io" asset backends (such as networked asset io). ## Draft TODO - [x] Fill in missing filesystem event APIs: file removed event (which is expressed as dangling RenameFrom events in some cases), file/folder renamed event - [x] Assets without loaders are not moved to the processed folder. This breaks things like referenced `.bin` files for GLTFs. This should be configurable per-non-asset-type. - [x] Initial implementation of Reflect and FromReflect for Handle. The "deserialization" parity bar is low here as this only worked with static UUIDs in the old impl ... this is a non-trivial problem. Either we add a Handle::AssetPath variant that gets "upgraded" to a strong handle on scene load or we use a separate AssetRef type for Bevy scenes (which is converted to a runtime Handle on load). This deserves its own discussion in a different pr. - [x] Populate read_asset_bytes hash when run by the processor (a bit of a special case .. when run by the processor the processed meta will contain the hash so we don't need to compute it on the spot, but we don't want/need to read the meta when run by the main AssetServer) - [x] Delay hot reloading: currently filesystem events are handled immediately, which creates timing issues in some cases. For example hot reloading images can sometimes break because the image isn't finished writing. We should add a delay, likely similar to the [implementation in this PR](https://github.com/bevyengine/bevy/pull/8503). - [x] Port old platform-specific AssetIo implementations to the new AssetReader interface (currently missing Android and web) - [x] Resolve on_loaded unsafety (either by removing the API entirely or removing the unsafe) - [x] Runtime loader setting overrides - [x] Remove remaining unwraps that should be error-handled. There are number of TODOs here - [x] Pretty AssetPath Display impl - [x] Document more APIs - [x] Resolve spurious "reloading because it has changed" events (to repro run load_gltf with `processed_dev()`) - [x] load_dependency hot reloading currently only works for processed assets. If processing is disabled, load_dependency changes are not hot reloaded. - [x] Replace AssetInfo dependency load/fail counters with `loading_dependencies: HashSet<UntypedAssetId>` to prevent reloads from (potentially) breaking counters. Storing this will also enable "dependency reloaded" events (see [Next Steps](#next-steps)) - [x] Re-add filesystem watcher cargo feature gate (currently it is not optional) - [ ] Migration Guide - [ ] Changelog ## Followup TODO - [ ] Replace "eager unchanged processed asset loading" behavior with "don't returned unchanged processed asset until dependencies have been checked". - [ ] Add true `Ignore` AssetAction that does not copy the asset to the imported_assets folder. - [ ] Finish "live asset unloading" (ex: free up CPU asset memory after uploading an image to the GPU), rethink RenderAssets, and port renderer features. The `Assets` collection uses `Option<T>` for asset storage to support its removal. (1) the Option might not actually be necessary ... might be able to just remove from the collection entirely (2) need to finalize removal apis - [ ] Try replacing the "channel based" asset id recycling with something a bit more efficient (ex: we might be able to use raw atomic ints with some cleverness) - [ ] Consider adding UUIDs to processed assets (scoped just to helping identify moved assets ... not exposed to load queries ... see [Next Steps](#next-steps)) - [ ] Store "last modified" source asset and meta timestamps in processed meta files to enable skipping expensive hashing when the file wasn't changed - [ ] Fix "slow loop" handle drop fix - [ ] Migrate to TypeName - [x] Handle "loader preregistration". See #9429 ## Next Steps * **Configurable per-type defaults for AssetMeta**: It should be possible to add configuration like "all png image meta should default to using nearest sampling" (currently this hard-coded per-loader/processor Settings::default() impls). Also see the "Folder Meta" bullet point. * **Avoid Reprocessing on Asset Renames / Moves**: See the "canonical asset ids" discussion in [Open Questions](#open-questions) and the relevant bullet point in [Draft TODO](#draft-todo). Even without canonical ids, folder renames could avoid reprocessing in some cases. * **Multiple Asset Sources**: Expand AssetPath to support "asset source names" and support multiple AssetReaders in the asset server (ex: `webserver://some_path/image.png` backed by an Http webserver AssetReader). The "default" asset reader would use normal `some_path/image.png` paths. Ideally this works in combination with multiple AssetWatchers for hot-reloading * **Stable Type Names**: this pr removes the TypeUuid requirement from assets in favor of `std::any::type_name`. This makes defining assets easier (no need to generate a new uuid / use weird proc macro syntax). It also makes reading meta files easier (because things have "friendly names"). We also use type names for components in scene files. If they are good enough for components, they are good enough for assets. And consistency across Bevy pillars is desirable. However, `std::any::type_name` is not guaranteed to be stable (although in practice it is). We've developed a [stable type path](https://github.com/bevyengine/bevy/pull/7184) to resolve this, which should be adopted when it is ready. * **Command Line Interface**: It should be possible to run the asset processor in a separate process from the command line. This will also require building a network-server-backed AssetReader to communicate between the app and the processor. We've been planning to build a "bevy cli" for awhile. This seems like a good excuse to build it. * **Asset Packing**: This is largely an additive feature, so it made sense to me to punt this until we've laid the foundations in this PR. * **Per-Platform Processed Assets**: It should be possible to generate assets for multiple platforms by supporting multiple "processor profiles" per asset (ex: compress with format X on PC and Y on iOS). I think there should probably be arbitrary "profiles" (which can be separate from actual platforms), which are then assigned to a given platform when generating the final asset distribution for that platform. Ex: maybe devs want a "Mobile" profile that is shared between iOS and Android. Or a "LowEnd" profile shared between web and mobile. * **Versioning and Migrations**: Assets, Loaders, Savers, and Processors need to have versions to determine if their schema is valid. If an asset / loader version is incompatible with the current version expected at runtime, the processor should be able to migrate them. I think we should try using Bevy Reflect for this, as it would allow us to load the old version as a dynamic Reflect type without actually having the old Rust type. It would also allow us to define "patches" to migrate between versions (Bevy Reflect devs are currently working on patching). The `.meta` file already has its own format version. Migrating that to new versions should also be possible. * **Real Copy-on-write AssetPaths**: Rust's actual Cow (clone-on-write type) currently used by AssetPath can still result in String clones that aren't actually necessary (cloning an Owned Cow clones the contents). Bevy's asset system requires cloning AssetPaths in a number of places, which result in actual clones of the internal Strings. This is not efficient. AssetPath internals should be reworked to exhibit truer cow-like-behavior that reduces String clones to the absolute minimum. * **Consider processor-less processing**: In theory the AssetServer could run processors "inline" even if the background AssetProcessor is disabled. If we decide this is actually desirable, we could add this. But I don't think its a priority in the short or medium term. * **Pre-emptive dependency loading**: We could encode dependencies in processed meta files, which could then be used by the Asset Server to kick of dependency loads as early as possible (prior to starting the actual asset load). Is this desirable? How much time would this save in practice? * **Optimize Processor With UntypedAssetIds**: The processor exclusively uses AssetPath to identify assets currently. It might be possible to swap these out for UntypedAssetIds in some places, which are smaller / cheaper to hash and compare. * **One to Many Asset Processing**: An asset source file that produces many assets currently must be processed into a single "processed" asset source. If labeled assets can be written separately they can each have their own configured savers _and_ they could be loaded more granularly. Definitely worth exploring! * **Automatically Track "Runtime-only" Asset Dependencies**: Right now, tracking "created at runtime" asset dependencies requires adding them via `asset_server.load_asset(StandardMaterial::default())`. I think with some cleverness we could also do this for `materials.add(StandardMaterial::default())`, making tracking work "everywhere". There are challenges here relating to change detection / ensuring the server is made aware of dependency changes. This could be expensive in some cases. * **"Dependency Changed" events**: Some assets have runtime artifacts that need to be re-generated when one of their dependencies change (ex: regenerate a material's bind group when a Texture needs to change). We are generating the dependency graph so we can definitely produce these events. Buuuuut generating these events will have a cost / they could be high frequency for some assets, so we might want this to be opt-in for specific cases. * **Investigate Storing More Information In Handles**: Handles can now store arbitrary information, which makes it cheaper and easier to access. How much should we move into them? Canonical asset load states (via atomics)? (`handle.is_loaded()` would be very cool). Should we store the entire asset and remove the `Assets<T>` collection? (`Arc<RwLock<Option<Image>>>`?) * **Support processing and loading files without extensions**: This is a pretty arbitrary restriction and could be supported with very minimal changes. * **Folder Meta**: It would be nice if we could define per folder processor configuration defaults (likely in a `.meta` or `.folder_meta` file). Things like "default to linear filtering for all Images in this folder". * **Replace async_broadcast with event-listener?** This might be approximately drop-in for some uses and it feels more light weight * **Support Running the AssetProcessor on the Web**: Most of the hard work is done here, but there are some easy straggling TODOs (make the transaction log an interface instead of a direct file writer so we can write a web storage backend, implement an AssetReader/AssetWriter that reads/writes to something like LocalStorage). * **Consider identifying and preventing circular dependencies**: This is especially important for "processor dependencies", as processing will silently never finish in these cases. * **Built-in/Inlined Asset Hot Reloading**: This PR regresses "built-in/inlined" asset hot reloading (previously provided by the DebugAssetServer). I'm intentionally punting this because I think it can be cleanly implemented with "multiple asset sources" by registering a "debug asset source" (ex: `debug://bevy_pbr/src/render/pbr.wgsl` asset paths) in combination with an AssetWatcher for that asset source and support for "manually loading pats with asset bytes instead of AssetReaders". The old DebugAssetServer was quite nasty and I'd love to avoid that hackery going forward. * **Investigate ways to remove double-parsing meta files**: Parsing meta files currently involves parsing once with "minimal" versions of the meta file to extract the type name of the loader/processor config, then parsing again to parse the "full" meta. This is suboptimal. We should be able to define custom deserializers that (1) assume the loader/processor type name comes first (2) dynamically looks up the loader/processor registrations to deserialize settings in-line (similar to components in the bevy scene format). Another alternative: deserialize as dynamic Reflect objects and then convert. * **More runtime loading configuration**: Support using the Handle type as a hint to select an asset loader (instead of relying on AssetPath extensions) * **More high level Processor trait implementations**: For example, it might be worth adding support for arbitrary chains of "asset transforms" that modify an in-memory asset representation between loading and saving. (ex: load a Mesh, run a `subdivide_mesh` transform, followed by a `flip_normals` transform, then save the mesh to an efficient compressed format). * **Bevy Scene Handle Deserialization**: (see the relevant [Draft TODO item](#draft-todo) for context) * **Explore High Level Load Interfaces**: See [this discussion](#discuss-on_loaded-high-level-interface) for one prototype. * **Asset Streaming**: It would be great if we could stream Assets (ex: stream a long video file piece by piece) * **ID Exchanging**: In this PR Asset Handles/AssetIds are bigger than they need to be because they have a Uuid enum variant. If we implement an "id exchanging" system that trades Uuids for "efficient runtime ids", we can cut down on the size of AssetIds, making them more efficient. This has some open design questions, such as how to spawn entities with "default" handle values (as these wouldn't have access to the exchange api in the current system). * **Asset Path Fixup Tooling**: Assets that inline asset paths inside them will break when an asset moves. The asset system provides the functionality to detect when paths break. We should build a framework that enables formats to define "path migrations". This is especially important for scene files. For editor-generated files, we should also consider using UUIDs (see other bullet point) to avoid the need to migrate in these cases. --------- Co-authored-by: BeastLe9enD <beastle9end@outlook.de> Co-authored-by: Mike <mike.hsu@gmail.com> Co-authored-by: Nicola Papale <nicopap@users.noreply.github.com>
2023-09-07 02:07:27 +00:00
System Stepping implemented as Resource (#8453) # Objective Add interactive system debugging capabilities to bevy, providing step/break/continue style capabilities to running system schedules. * Original implementation: #8063 - `ignore_stepping()` everywhere was too much complexity * Schedule-config & Resource discussion: #8168 - Decided on selective adding of Schedules & Resource-based control ## Solution Created `Stepping` Resource. This resource can be used to enable stepping on a per-schedule basis. Systems within schedules can be individually configured to: * AlwaysRun: Ignore any stepping state and run every frame * NeverRun: Never run while stepping is enabled - this allows for disabling of systems while debugging * Break: If we're running the full frame, stop before this system is run Stepping provides two modes of execution that reflect traditional debuggers: * Step-based: Only execute one system at a time * Continue/Break: Run all systems, but stop before running a system marked as Break ### Demo https://user-images.githubusercontent.com/857742/233630981-99f3bbda-9ca6-4cc4-a00f-171c4946dc47.mov Breakout has been modified to use Stepping. The game runs normally for a couple of seconds, then stepping is enabled and the game appears to pause. A list of Schedules & Systems appears with a cursor at the first System in the list. The demo then steps forward full frames using the spacebar until the ball is about to hit a brick. Then we step system by system as the ball impacts a brick, showing the cursor moving through the individual systems. Finally the demo switches back to frame stepping as the ball changes course. ### Limitations Due to architectural constraints in bevy, there are some cases systems stepping will not function as a user would expect. #### Event-driven systems Stepping does not support systems that are driven by `Event`s as events are flushed after 1-2 frames. Although game systems are not running while stepping, ignored systems are still running every frame, so events will be flushed. This presents to the user as stepping the event-driven system never executes the system. It does execute, but the events have already been flushed. This can be resolved by changing event handling to use a buffer for events, and only dropping an event once all readers have read it. The work-around to allow these systems to properly execute during stepping is to have them ignore stepping: `app.add_systems(event_driven_system.ignore_stepping())`. This was done in the breakout example to ensure sound played even while stepping. #### Conditional Systems When a system is stepped, it is given an opportunity to run. If the conditions of the system say it should not run, it will not. Similar to Event-driven systems, if a system is conditional, and that condition is only true for a very small time window, then stepping the system may not execute the system. This includes depending on any sort of external clock. This exhibits to the user as the system not always running when it is stepped. A solution to this limitation is to ensure any conditions are consistent while stepping is enabled. For example, all systems that modify any state the condition uses should also enable stepping. #### State-transition Systems Stepping is configured on the per-`Schedule` level, requiring the user to have a `ScheduleLabel`. To support state-transition systems, bevy generates needed schedules dynamically. Currently it’s very difficult (if not impossible, I haven’t verified) for the user to get the labels for these schedules. Without ready access to the dynamically generated schedules, and a resolution for the `Event` lifetime, **stepping of the state-transition systems is not supported** --- ## Changelog - `Schedule::run()` updated to consult `Stepping` Resource to determine which Systems to run each frame - Added `Schedule.label` as a `BoxedSystemLabel`, along with supporting `Schedule::set_label()` and `Schedule::label()` methods - `Stepping` needed to know which `Schedule` was running, and prior to this PR, `Schedule` didn't track its own label - Would have preferred to add `Schedule::with_label()` and remove `Schedule::new()`, but this PR touches enough already - Added calls to `Schedule.set_label()` to `App` and `World` as needed - Added `Stepping` resource - Added `Stepping::begin_frame()` system to `MainSchedulePlugin` - Run before `Main::run_main()` - Notifies any `Stepping` Resource a new render frame is starting ## Migration Guide - Add a call to `Schedule::set_label()` for any custom `Schedule` - This is only required if the `Schedule` will be stepped --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2024-02-03 05:18:38 +00:00
# Enable stepping-based debugging of Bevy systems
bevy_debug_stepping = ["bevy_internal/bevy_debug_stepping"]
Meshlet rendering (initial feature) (#10164) # Objective - Implements a more efficient, GPU-driven (https://github.com/bevyengine/bevy/issues/1342) rendering pipeline based on meshlets. - Meshes are split into small clusters of triangles called meshlets, each of which acts as a mini index buffer into the larger mesh data. Meshlets can be compressed, streamed, culled, and batched much more efficiently than monolithic meshes. ![image](https://github.com/bevyengine/bevy/assets/47158642/cb2aaad0-7a9a-4e14-93b0-15d4e895b26a) ![image](https://github.com/bevyengine/bevy/assets/47158642/7534035b-1eb7-4278-9b99-5322e4401715) # Misc * Future work: https://github.com/bevyengine/bevy/issues/11518 * Nanite reference: https://advances.realtimerendering.com/s2021/Karis_Nanite_SIGGRAPH_Advances_2021_final.pdf Two pass occlusion culling explained very well: https://medium.com/@mil_kru/two-pass-occlusion-culling-4100edcad501 --------- Co-authored-by: Ricky Taylor <rickytaylor26@gmail.com> Co-authored-by: vero <email@atlasdostal.com> Co-authored-by: François <mockersf@gmail.com> Co-authored-by: atlas dostal <rodol@rivalrebels.com>
2024-03-25 19:08:27 +00:00
# Enables the meshlet renderer for dense high-poly scenes (experimental)
meshlet = ["bevy_internal/meshlet"]
# Enables processing meshes into meshlet meshes for bevy_pbr
meshlet_processor = ["bevy_internal/meshlet_processor"]
Fix ios simulator support (#12339) # Objective - #12103 broke iOS simulator support, it doesn't even compile anymore ## Solution - Fix the feature
2024-03-06 17:48:17 +00:00
# Enable support for the ios_simulator by downgrading some rendering capabilities
ios_simulator = ["bevy_internal/ios_simulator"]
Separate state crate (#13216) # Objective Extracts the state mechanisms into a new crate called "bevy_state". This comes with a few goals: - state wasn't really an inherent machinery of the ecs system, and so keeping it within bevy_ecs felt forced - by mixing it in with bevy_ecs, the maintainability of our more robust state system was significantly compromised moving state into a new crate makes it easier to encapsulate as it's own feature, and easier to read and understand since it's no longer a single, massive file. ## Solution move the state-related elements from bevy_ecs to a new crate ## Testing - Did you test these changes? If so, how? all the automated tests migrated and passed, ran the pre-existing examples without changes to validate. --- ## Migration Guide Since bevy_state is now gated behind the `bevy_state` feature, projects that use state but don't use the `default-features` will need to add that feature flag. Since it is no longer part of bevy_ecs, projects that use bevy_ecs directly will need to manually pull in `bevy_state`, trigger the StateTransition schedule, and handle any of the elements that bevy_app currently sets up. --------- Co-authored-by: Kristoffer Søholm <k.soeholm@gmail.com>
2024-05-09 18:06:05 +00:00
# Enable built in global state machines
bevy_state = ["bevy_internal/bevy_state"]
Track source location in change detection (#14034) # Objective - Make it possible to know *what* changed your component or resource. - Common need when debugging, when you want to know the last code location that mutated a value in the ECS. - This feature would be very useful for the editor alongside system stepping. ## Solution - Adds the caller location to column data. - Mutations now `track_caller` all the way up to the public API. - Commands that invoke these functions immediately call `Location::caller`, and pass this into the functions, instead of the functions themselves attempting to get the caller. This would not work for commands which are deferred, as the commands are executed by the scheduler, not the user's code. ## Testing - The `component_change_detection` example now shows where the component was mutated: ``` 2024-07-28T06:57:48.946022Z INFO component_change_detection: Entity { index: 1, generation: 1 }: New value: MyComponent(0.0) 2024-07-28T06:57:49.004371Z INFO component_change_detection: Entity { index: 1, generation: 1 }: New value: MyComponent(1.0) 2024-07-28T06:57:49.012738Z WARN component_change_detection: Change detected! -> value: Ref(MyComponent(1.0)) -> added: false -> changed: true -> changed by: examples/ecs/component_change_detection.rs:36:23 ``` - It's also possible to inspect change location from a debugger: <img width="608" alt="image" src="https://github.com/user-attachments/assets/c90ecc7a-0462-457a-80ae-42e7f5d346b4"> --- ## Changelog - Added source locations to ECS change detection behind the `track_change_detection` flag. ## Migration Guide - Added `changed_by` field to many internal ECS functions used with change detection when the `track_change_detection` feature flag is enabled. Use Location::caller() to provide the source of the function call. --------- Co-authored-by: BD103 <59022059+BD103@users.noreply.github.com> Co-authored-by: Gino Valente <49806985+MrGVSV@users.noreply.github.com>
2024-07-30 12:02:38 +00:00
# Enables source location tracking for change detection, which can assist with debugging
track_change_detection = ["bevy_internal/track_change_detection"]
bevy_reflect: Feature-gate function reflection (#14174) # Objective Function reflection requires a lot of macro code generation in the form of several `all_tuples!` invocations, as well as impls generated in the `Reflect` derive macro. Seeing as function reflection is currently a bit more niche, it makes sense to gate it all behind a feature. ## Solution Add a `functions` feature to `bevy_reflect`, which can be enabled in Bevy using the `reflect_functions` feature. ## Testing You can test locally by running: ``` cargo test --package bevy_reflect ``` That should ensure that everything still works with the feature disabled. To test with the feature on, you can run: ``` cargo test --package bevy_reflect --features functions ``` --- ## Changelog - Moved function reflection behind a Cargo feature (`bevy/reflect_functions` and `bevy_reflect/functions`) - Add `IntoFunction` export in `bevy_reflect::prelude` ## Internal Migration Guide > [!important] > Function reflection was introduced as part of the 0.15 dev cycle. This migration guide was written for developers relying on `main` during this cycle, and is not a breaking change coming from 0.14. Function reflection is now gated behind a feature. To use function reflection, enable the feature: - If using `bevy_reflect` directly, enable the `functions` feature - If using `bevy`, enable the `reflect_functions` feature
2024-07-14 15:55:31 +00:00
# Enable function reflection
reflect_functions = ["bevy_internal/reflect_functions"]
Inverse bevy_render bevy_winit dependency and move cursor to bevy_winit (#15649) # Objective - `bevy_render` should not depend on `bevy_winit` - Fixes #15565 ## Solution - `bevy_render` no longer depends on `bevy_winit` - The following is behind the `custom_cursor` feature - Move custom cursor code from `bevy_render` to `bevy_winit` behind the `custom_cursor` feature - `bevy_winit` now depends on `bevy_render` (for `Image` and `TextureFormat`) - `bevy_winit` now depends on `bevy_asset` (for `Assets`, `Handle` and `AssetId`) - `bevy_winit` now depends on `bytemuck` (already in tree) - Custom cursor code in `bevy_winit` reworked to use `AssetId` (other than that it is taken over 1:1) - Rework `bevy_winit` custom cursor interface visibility now that the logic is all contained in `bevy_winit` ## Testing - I ran the screenshot and window_settings examples - Tested on linux wayland so far --- ## Migration Guide `CursorIcon` and `CustomCursor` previously provided by `bevy::render::view::cursor` is now available from `bevy::winit`. A new feature `custom_cursor` enables this functionality (default feature).
2024-10-06 18:25:50 +00:00
# Enable winit custom cursor support
custom_cursor = ["bevy_internal/custom_cursor"]
Mark ghost nodes as experimental and partially feature flag them (#15961) # Objective As discussed in #15341, ghost nodes are a contentious and experimental feature. In the interest of enabling ecosystem experimentation, we've decided to keep them in Bevy 0.15. That said, we don't use them internally, and don't expect third-party crates to support them. If the experimentation returns a negative result (they aren't very useful, an alternative design is preferred etc) they will be removed. We should clearly communicate this status to users, and make sure that users don't use ghost nodes in their projects without a very clear understanding of what they're getting themselves into. ## Solution To make life easy for users (and Bevy), `GhostNode` and all associated helpers remain public and are always available. However, actually constructing these requires enabling a feature flag that's clearly marked as experimental. To do so, I've added a meaningless private field. When the feature flag is enabled, our constructs (`new` and `default`) can be used. I've added a `new` constructor, which should be preferred over `Default::default` as that can be readily deprecated, allowing us to prompt users to swap over to the much nicer `GhostNode` syntax once this is a unit struct again. Full credit: this was mostly @cart's design: I'm just implementing it! ## Testing I've run the ghost_nodes example and it fails to compile without the feature flag. With the feature flag, it works fine :) --------- Co-authored-by: Zachary Harrold <zac@harrold.com.au>
2024-10-16 22:20:48 +00:00
# Experimental support for nodes that are ignored for UI layouting
ghost_nodes = ["bevy_internal/ghost_nodes"]
initial commit
2019-11-13 03:36:02 +00:00
[dependencies]
Bump Version after Release (#14219) Bump version after release This PR has been auto-generated Co-authored-by: Bevy Auto Releaser <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: François Mockers <mockersf@gmail.com>
2024-07-08 12:54:08 +00:00
bevy_internal = { path = "crates/bevy_internal", version = "0.15.0-dev", default-features = false }
Crate-ify (almost) everything
2020-04-06 03:19:02 +00:00
Fix common capitalization errors in documentation (#14562) WASM -> Wasm MacOS -> macOS Nothing important, just something that annoyed me for a while :)
2024-07-31 21:16:05 +00:00
# Wasm does not support dynamic linking.
Make dynamic_linking a no-op on wasm targets (#12672) # Objective Resolve #10054. ## Solution Make dynamic linking a no-op by omitting it from the dependency tree on wasm targets. To test this, try `cargo build --lib --target wasm32-unknown-unknown --features bevy/dynamic_linking` with and without this PR. Might need to update the book on the website to explain this when this makes it into a release. Co-Authored By: @daxpedda --------- Co-authored-by: BD103 <59022059+BD103@users.noreply.github.com>
2024-04-24 04:49:38 +00:00
[target.'cfg(not(target_family = "wasm"))'.dependencies]
Bump Version after Release (#14219) Bump version after release This PR has been auto-generated Co-authored-by: Bevy Auto Releaser <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: François Mockers <mockersf@gmail.com>
2024-07-08 12:54:08 +00:00
bevy_dylib = { path = "crates/bevy_dylib", version = "0.15.0-dev", default-features = false, optional = true }
Make dynamic_linking a no-op on wasm targets (#12672) # Objective Resolve #10054. ## Solution Make dynamic linking a no-op by omitting it from the dependency tree on wasm targets. To test this, try `cargo build --lib --target wasm32-unknown-unknown --features bevy/dynamic_linking` with and without this PR. Might need to update the book on the website to explain this when this makes it into a release. Co-Authored By: @daxpedda --------- Co-authored-by: BD103 <59022059+BD103@users.noreply.github.com>
2024-04-24 04:49:38 +00:00
Crate-ify (almost) everything
2020-04-06 03:19:02 +00:00
[dev-dependencies]
Update rand requirement from 0.7 to 0.8 (#1114) * Update rand requirement from 0.7 to 0.8 * Update examples' usage of Rng::gen_range
2021-01-17 21:43:03 +00:00
rand = "0.8.0"
Switch to portable RNG in examples (#12644) # Objective Fixes issue #12613 - the RNG used in examples is _deterministic_, but its implementation is not _portable_ across platforms. We want to switch to using a portable RNG that does not vary across platforms, to ensure certain examples play out the same way every time. ## Solution Replace all occurences of `rand::rngs::StdRng` with `rand_chacha::ChaCha8Rng`, as recommended in issue #12613 --- ## Changelog - Add `rand_chacha` as a new dependency (controversial?) - Replace all occurences of `rand::rngs::StdRng` with `rand_chacha::ChaCha8Rng`
2024-03-22 20:25:49 +00:00
rand_chacha = "0.3.1"
Update to ron 0.8 (#5864) # Objective - Update ron to 0.8.0 - Fix breaking changes - Closes #5862 ## Solution - Removed now non-existing method call (behavior is now the same without it)
2022-09-02 14:20:49 +00:00
ron = "0.8.0"
Added Method to Allow Pipelined Asset Loading (#10565) # Objective - Fixes #10518 ## Solution I've added a method to `LoadContext`, `load_direct_with_reader`, which mirrors the behaviour of `load_direct` with a single key difference: it is provided with the `Reader` by the caller, rather than getting it from the contained `AssetServer`. This allows for an `AssetLoader` to process its `Reader` stream, and then directly hand the results off to the `LoadContext` to handle further loading. The outer `AssetLoader` can control how the `Reader` is interpreted by providing a relevant `AssetPath`. For example, a Gzip decompression loader could process the asset `images/my_image.png.gz` by decompressing the bytes, then handing the decompressed result to the `LoadContext` with the new path `images/my_image.png.gz/my_image.png`. This intuitively reflects the nature of contained assets, whilst avoiding unintended behaviour, since the generated path cannot be a real file path (a file and folder of the same name cannot coexist in most file-systems). ```rust #[derive(Asset, TypePath)] pub struct GzAsset { pub uncompressed: ErasedLoadedAsset, } #[derive(Default)] pub struct GzAssetLoader; impl AssetLoader for GzAssetLoader { type Asset = GzAsset; type Settings = (); type Error = GzAssetLoaderError; fn load<'a>( &'a self, reader: &'a mut Reader, _settings: &'a (), load_context: &'a mut LoadContext, ) -> BoxedFuture<'a, Result<Self::Asset, Self::Error>> { Box::pin(async move { let compressed_path = load_context.path(); let file_name = compressed_path .file_name() .ok_or(GzAssetLoaderError::IndeterminateFilePath)? .to_string_lossy(); let uncompressed_file_name = file_name .strip_suffix(".gz") .ok_or(GzAssetLoaderError::IndeterminateFilePath)?; let contained_path = compressed_path.join(uncompressed_file_name); let mut bytes_compressed = Vec::new(); reader.read_to_end(&mut bytes_compressed).await?; let mut decoder = GzDecoder::new(bytes_compressed.as_slice()); let mut bytes_uncompressed = Vec::new(); decoder.read_to_end(&mut bytes_uncompressed)?; // Now that we have decompressed the asset, let's pass it back to the // context to continue loading let mut reader = VecReader::new(bytes_uncompressed); let uncompressed = load_context .load_direct_with_reader(&mut reader, contained_path) .await?; Ok(GzAsset { uncompressed }) }) } fn extensions(&self) -> &[&str] { &["gz"] } } ``` Because this example is so prudent, I've included an `asset_decompression` example which implements this exact behaviour: ```rust fn main() { App::new() .add_plugins(DefaultPlugins) .init_asset::<GzAsset>() .init_asset_loader::<GzAssetLoader>() .add_systems(Startup, setup) .add_systems(Update, decompress::<Image>) .run(); } fn setup(mut commands: Commands, asset_server: Res<AssetServer>) { commands.spawn(Camera2dBundle::default()); commands.spawn(( Compressed::<Image> { compressed: asset_server.load("data/compressed_image.png.gz"), ..default() }, Sprite::default(), TransformBundle::default(), VisibilityBundle::default(), )); } fn decompress<A: Asset>( mut commands: Commands, asset_server: Res<AssetServer>, mut compressed_assets: ResMut<Assets<GzAsset>>, query: Query<(Entity, &Compressed<A>)>, ) { for (entity, Compressed { compressed, .. }) in query.iter() { let Some(GzAsset { uncompressed }) = compressed_assets.remove(compressed) else { continue; }; let uncompressed = uncompressed.take::<A>().unwrap(); commands .entity(entity) .remove::<Compressed<A>>() .insert(asset_server.add(uncompressed)); } } ``` A key limitation to this design is how to type the internally loaded asset, since the example `GzAssetLoader` is unaware of the internal asset type `A`. As such, in this example I store the contained asset as an `ErasedLoadedAsset`, and leave it up to the consumer of the `GzAsset` to handle typing the final result, which is the purpose of the `decompress` system. This limitation can be worked around by providing type information to the `GzAssetLoader`, such as `GzAssetLoader<Image, ImageAssetLoader>`, but this would require registering the asset loader for every possible decompression target. Aside from this limitation, nested asset containerisation works as an end user would expect; if the user registers a `TarAssetLoader`, and a `GzAssetLoader`, then they can load assets with compound containerisation, such as `images.tar.gz`. --- ## Changelog - Added `LoadContext::load_direct_with_reader` - Added `asset_decompression` example ## Notes - While I believe my implementation of a Gzip asset loader is reasonable, I haven't included it as a public feature of `bevy_asset` to keep the scope of this PR as focussed as possible. - I have included `flate2` as a `dev-dependency` for the example; it is not included in the main dependency graph.
2023-11-16 17:47:31 +00:00
flate2 = "1.0"
Remove bevy_dynamic_plugin as a default (#2578) It doesn't compile on wasm, and it's full of footguns # Objective - If bevy is used with default features on wasm, there's more of a chance it will compile - Note that I haven't done a full audit - it's possible that there are other problematic crates ## Solution - `bevy_dynamic_plugin` is no longer a default plugin - I've also done an accidental drive by reformatting of the root `Cargo.toml`, as I have [Even Better Toml](https://github.com/tamasfe/taplo) installed. - (Please, rustfmt do this for us)
2021-08-01 19:14:47 +00:00
serde = { version = "1", features = ["derive"] }
Initial implementation of the Bevy Remote Protocol (Adopted) (#14880) # Objective Adopted from #13563. The goal is to implement the Bevy Remote Protocol over HTTP/JSON, allowing the ECS to be interacted with remotely. ## Solution At a high level, there are really two separate things that have been undertaken here: 1. First, `RemotePlugin` has been created, which has the effect of embedding a [JSON-RPC](https://www.jsonrpc.org/specification) endpoint into a Bevy application. 2. Second, the [Bevy Remote Protocol verbs](https://gist.github.com/coreh/1baf6f255d7e86e4be29874d00137d1d#file-bevy-remote-protocol-md) (excluding `POLL`) have been implemented as remote methods for that JSON-RPC endpoint under a Bevy-exclusive namespace (e.g. `bevy/get`, `bevy/list`, etc.). To avoid some repetition, here is the crate-level documentation, which explains the request/response structure, built-in-methods, and custom method configuration: <details> <summary>Click to view crate-level docs</summary> ```rust //! An implementation of the Bevy Remote Protocol over HTTP and JSON, to allow //! for remote control of a Bevy app. //! //! Adding the [`RemotePlugin`] to your [`App`] causes Bevy to accept //! connections over HTTP (by default, on port 15702) while your app is running. //! These *remote clients* can inspect and alter the state of the //! entity-component system. Clients are expected to `POST` JSON requests to the //! root URL; see the `client` example for a trivial example of use. //! //! The Bevy Remote Protocol is based on the JSON-RPC 2.0 protocol. //! //! ## Request objects //! //! A typical client request might look like this: //! //! ```json //! { //! "method": "bevy/get", //! "id": 0, //! "params": { //! "entity": 4294967298, //! "components": [ //! "bevy_transform::components::transform::Transform" //! ] //! } //! } //! ``` //! //! The `id` and `method` fields are required. The `param` field may be omitted //! for certain methods: //! //! * `id` is arbitrary JSON data. The server completely ignores its contents, //! and the client may use it for any purpose. It will be copied via //! serialization and deserialization (so object property order, etc. can't be //! relied upon to be identical) and sent back to the client as part of the //! response. //! //! * `method` is a string that specifies one of the possible [`BrpRequest`] //! variants: `bevy/query`, `bevy/get`, `bevy/insert`, etc. It's case-sensitive. //! //! * `params` is parameter data specific to the request. //! //! For more information, see the documentation for [`BrpRequest`]. //! [`BrpRequest`] is serialized to JSON via `serde`, so [the `serde` //! documentation] may be useful to clarify the correspondence between the Rust //! structure and the JSON format. //! //! ## Response objects //! //! A response from the server to the client might look like this: //! //! ```json //! { //! "jsonrpc": "2.0", //! "id": 0, //! "result": { //! "bevy_transform::components::transform::Transform": { //! "rotation": { "x": 0.0, "y": 0.0, "z": 0.0, "w": 1.0 }, //! "scale": { "x": 1.0, "y": 1.0, "z": 1.0 }, //! "translation": { "x": 0.0, "y": 0.5, "z": 0.0 } //! } //! } //! } //! ``` //! //! The `id` field will always be present. The `result` field will be present if the //! request was successful. Otherwise, an `error` field will replace it. //! //! * `id` is the arbitrary JSON data that was sent as part of the request. It //! will be identical to the `id` data sent during the request, modulo //! serialization and deserialization. If there's an error reading the `id` field, //! it will be `null`. //! //! * `result` will be present if the request succeeded and will contain the response //! specific to the request. //! //! * `error` will be present if the request failed and will contain an error object //! with more information about the cause of failure. //! //! ## Error objects //! //! An error object might look like this: //! //! ```json //! { //! "code": -32602, //! "message": "Missing \"entity\" field" //! } //! ``` //! //! The `code` and `message` fields will always be present. There may also be a `data` field. //! //! * `code` is an integer representing the kind of an error that happened. Error codes documented //! in the [`error_codes`] module. //! //! * `message` is a short, one-sentence human-readable description of the error. //! //! * `data` is an optional field of arbitrary type containing additional information about the error. //! //! ## Built-in methods //! //! The Bevy Remote Protocol includes a number of built-in methods for accessing and modifying data //! in the ECS. Each of these methods uses the `bevy/` prefix, which is a namespace reserved for //! BRP built-in methods. //! //! ### bevy/get //! //! Retrieve the values of one or more components from an entity. //! //! `params`: //! - `entity`: The ID of the entity whose components will be fetched. //! - `components`: An array of fully-qualified type names of components to fetch. //! //! `result`: A map associating each type name to its value on the requested entity. //! //! ### bevy/query //! //! Perform a query over components in the ECS, returning all matching entities and their associated //! component values. //! //! All of the arrays that comprise this request are optional, and when they are not provided, they //! will be treated as if they were empty. //! //! `params`: //! `params`: //! - `data`: //! - `components` (optional): An array of fully-qualified type names of components to fetch. //! - `option` (optional): An array of fully-qualified type names of components to fetch optionally. //! - `has` (optional): An array of fully-qualified type names of components whose presence will be //! reported as boolean values. //! - `filter` (optional): //! - `with` (optional): An array of fully-qualified type names of components that must be present //! on entities in order for them to be included in results. //! - `without` (optional): An array of fully-qualified type names of components that must *not* be //! present on entities in order for them to be included in results. //! //! `result`: An array, each of which is an object containing: //! - `entity`: The ID of a query-matching entity. //! - `components`: A map associating each type name from `components`/`option` to its value on the matching //! entity if the component is present. //! - `has`: A map associating each type name from `has` to a boolean value indicating whether or not the //! entity has that component. If `has` was empty or omitted, this key will be omitted in the response. //! //! ### bevy/spawn //! //! Create a new entity with the provided components and return the resulting entity ID. //! //! `params`: //! - `components`: A map associating each component's fully-qualified type name with its value. //! //! `result`: //! - `entity`: The ID of the newly spawned entity. //! //! ### bevy/destroy //! //! Despawn the entity with the given ID. //! //! `params`: //! - `entity`: The ID of the entity to be despawned. //! //! `result`: null. //! //! ### bevy/remove //! //! Delete one or more components from an entity. //! //! `params`: //! - `entity`: The ID of the entity whose components should be removed. //! - `components`: An array of fully-qualified type names of components to be removed. //! //! `result`: null. //! //! ### bevy/insert //! //! Insert one or more components into an entity. //! //! `params`: //! - `entity`: The ID of the entity to insert components into. //! - `components`: A map associating each component's fully-qualified type name with its value. //! //! `result`: null. //! //! ### bevy/reparent //! //! Assign a new parent to one or more entities. //! //! `params`: //! - `entities`: An array of entity IDs of entities that will be made children of the `parent`. //! - `parent` (optional): The entity ID of the parent to which the child entities will be assigned. //! If excluded, the given entities will be removed from their parents. //! //! `result`: null. //! //! ### bevy/list //! //! List all registered components or all components present on an entity. //! //! When `params` is not provided, this lists all registered components. If `params` is provided, //! this lists only those components present on the provided entity. //! //! `params` (optional): //! - `entity`: The ID of the entity whose components will be listed. //! //! `result`: An array of fully-qualified type names of components. //! //! ## Custom methods //! //! In addition to the provided methods, the Bevy Remote Protocol can be extended to include custom //! methods. This is primarily done during the initialization of [`RemotePlugin`], although the //! methods may also be extended at runtime using the [`RemoteMethods`] resource. //! //! ### Example //! ```ignore //! fn main() { //! App::new() //! .add_plugins(DefaultPlugins) //! .add_plugins( //! // `default` adds all of the built-in methods, while `with_method` extends them //! RemotePlugin::default() //! .with_method("super_user/cool_method".to_owned(), path::to::my::cool::handler) //! // ... more methods can be added by chaining `with_method` //! ) //! .add_systems( //! // ... standard application setup //! ) //! .run(); //! } //! ``` //! //! The handler is expected to be a system-convertible function which takes optional JSON parameters //! as input and returns a [`BrpResult`]. This means that it should have a type signature which looks //! something like this: //! ``` //! # use serde_json::Value; //! # use bevy_ecs::prelude::{In, World}; //! # use bevy_remote::BrpResult; //! fn handler(In(params): In<Option<Value>>, world: &mut World) -> BrpResult { //! todo!() //! } //! ``` //! //! Arbitrary system parameters can be used in conjunction with the optional `Value` input. The //! handler system will always run with exclusive `World` access. //! //! [the `serde` documentation]: https://serde.rs/ ``` </details> ### Message lifecycle At a high level, the lifecycle of client-server interactions is something like this: 1. The client sends one or more `BrpRequest`s. The deserialized version of that is just the Rust representation of a JSON-RPC request, and it looks like this: ```rust pub struct BrpRequest { /// The action to be performed. Parsing is deferred for the sake of error reporting. pub method: Option<Value>, /// Arbitrary data that will be returned verbatim to the client as part of /// the response. pub id: Option<Value>, /// The parameters, specific to each method. /// /// These are passed as the first argument to the method handler. /// Sometimes params can be omitted. pub params: Option<Value>, } ``` 2. These requests are accumulated in a mailbox resource (small lie but close enough). 3. Each update, the mailbox is drained by a system `process_remote_requests`, where each request is processed according to its `method`, which has an associated handler. Each handler is a Bevy system that runs with exclusive world access and returns a result; e.g.: ```rust pub fn process_remote_get_request(In(params): In<Option<Value>>, world: &World) -> BrpResult { // ... } ``` 4. The result (or an error) is reported back to the client. ## Testing This can be tested by using the `server` and `client` examples. The `client` example is not particularly exhaustive at the moment (it only creates barebones `bevy/query` requests) but is still informative. Other queries can be made using `curl` with the `server` example running. For example, to make a `bevy/list` request and list all registered components: ```bash curl -X POST -d '{ "jsonrpc": "2.0", "id": 1, "method": "bevy/list" }' 127.0.0.1:15702 | jq . ``` --- ## Future direction There were a couple comments on BRP versioning while this was in draft. I agree that BRP versioning is a good idea, but I think that it requires some consensus on a couple fronts: - First of all, what does the version actually mean? Is it a version for the protocol itself or for the `bevy/*` methods implemented using it? Both? - Where does the version actually live? The most natural place is just where we have `"jsonrpc"` right now (at least if it's versioning the protocol itself), but this means we're not actually conforming to JSON-RPC any more (so, for example, any client library used to construct JSON-RPC requests would stop working). I'm not really against that, but it's at least a real decision. - What do we actually do when we encounter mismatched versions? Adding handling for this would be actual scope creep instead of just a little add-on in my opinion. Another thing that would be nice is making the internal structure of the implementation less JSON-specific. Right now, for example, component values that will appear in server responses are quite eagerly converted to JSON `Value`s, which prevents disentangling the handler logic from the communication medium, but it can probably be done in principle and I imagine it would enable more code reuse (e.g. for custom method handlers) in addition to making the internals more readily usable for other formats. --------- Co-authored-by: Patrick Walton <pcwalton@mimiga.net> Co-authored-by: DragonGamesStudios <margos.michal@gmail.com> Co-authored-by: Christopher Biscardi <chris@christopherbiscardi.com> Co-authored-by: Gino Valente <49806985+MrGVSV@users.noreply.github.com>
2024-09-23 18:36:16 +00:00
serde_json = "1"
add some more pipelined-rendering shader examples (#3041) based on #3031 Adds some examples showing of how to use the new pipelined rendering for custom shaders. - a minimal shader example which doesn't use render assets - the same but using glsl - an example showing how to render instanced data - a shader which uses the seconds since startup to animate some textures Instancing shader: ![grafik](https://user-images.githubusercontent.com/22177966/139299294-e176b62a-53d1-4287-9a66-02fb55affc02.png) Animated shader: ![animate_shader](https://user-images.githubusercontent.com/22177966/139299718-2940c0f3-8480-4ee0-98d7-b6ba40dc1472.gif) (the gif makes it look a bit ugly) Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-01-05 19:43:11 +00:00
bytemuck = "1.7"
Test for ambiguous system ordering in CI (#13950) Progress towards https://github.com/bevyengine/bevy/issues/7386. Following discussion https://discord.com/channels/691052431525675048/1253260494538539048/1253387942311886960 This Pull Request adds an example to detect system order ambiguities, and also asserts none exist. A lot of schedules are ignored in ordered to have the test passing, we should thrive to make them pass, but in other pull requests. <details><summary>example output <b>summary</b>, without ignored schedules</summary> <p> ```txt $ cargo run --example ambiguity_detection 2>&1 | grep -C 1 "pairs of syst" 2024-06-21T13:17:55.776585Z WARN bevy_ecs::schedule::schedule: Schedule First has ambiguities. 1 pairs of systems with conflicting data access have indeterminate execution order. Consider adding `before`, `after`, or `ambiguous_with` relationships between these: -- bevy_time::time_system (in set TimeSystem) and bevy_ecs::event::event_update_system (in set EventUpdates) -- 2024-06-21T13:17:55.782265Z WARN bevy_ecs::schedule::schedule: Schedule PreUpdate has ambiguities. 11 pairs of systems with conflicting data access have indeterminate execution order. Consider adding `before`, `after`, or `ambiguous_with` relationships between these: -- bevy_pbr::prepass::update_mesh_previous_global_transforms and bevy_asset::server::handle_internal_asset_events -- 2024-06-21T13:17:55.809516Z WARN bevy_ecs::schedule::schedule: Schedule PostUpdate has ambiguities. 63 pairs of systems with conflicting data access have indeterminate execution order. Consider adding `before`, `after`, or `ambiguous_with` relationships between these: -- bevy_ui::accessibility::image_changed and bevy_ecs::schedule::executor::apply_deferred -- 2024-06-21T13:17:55.816287Z WARN bevy_ecs::schedule::schedule: Schedule Last has ambiguities. 3 pairs of systems with conflicting data access have indeterminate execution order. Consider adding `before`, `after`, or `ambiguous_with` relationships between these: -- bevy_gizmos::update_gizmo_meshes<bevy_gizmos::aabb::AabbGizmoConfigGroup> (in set UpdateGizmoMeshes) and bevy_gizmos::update_gizmo_meshes<bevy_gizmos::light::LightGizmoConfigGroup> (in set UpdateGizmoMeshes) -- 2024-06-21T13:17:55.831074Z WARN bevy_ecs::schedule::schedule: Schedule ExtractSchedule has ambiguities. 296 pairs of systems with conflicting data access have indeterminate execution order. Consider adding `before`, `after`, or `ambiguous_with` relationships between these: -- bevy_render::extract_component::extract_components<bevy_sprite::SpriteSource> and bevy_render::render_asset::extract_render_asset<bevy_sprite::mesh2d::material::PreparedMaterial2d<bevy_sprite::mesh2d::color_material::ColorMaterial>> ``` </p> </details> To try locally: ```sh CI_TESTING_CONFIG="./.github/example-run/ambiguity_detection.ron" cargo run --example ambiguity_detection --features "bevy_ci_testing,trace,trace_chrome" ``` --------- Co-authored-by: Jan Hohenheim <jan@hohenheim.ch>
2024-07-17 21:05:48 +00:00
bevy_render = { path = "crates/bevy_render", version = "0.15.0-dev", default-features = false }
Example showing how to use AsyncComputeTaskPool and Tasks (#2180)
2021-05-23 20:13:55 +00:00
# Needed to poll Task examples
bump bevy_tasks futures-lite to 2.0.1 (#10675) # Objective Updates [`futures-lite`](https://github.com/smol-rs/futures-lite) in bevy_tasks to the next major version (1 -> 2). Also removes the duplication of `futures-lite`, as `async-fs` requires v 2, so there are currently 2 copies of futures-lite in the dependency tree. Futures-lite has received [a number of updates](https://github.com/smol-rs/futures-lite/blob/master/CHANGELOG.md) since bevy's current version `1.4`. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Mike <mike.hsu@gmail.com>
2023-11-24 00:11:02 +00:00
futures-lite = "2.0.1"
Use oslog for ios (#13364) # Objective On mobile devices, it's best to use the OS's native logging due to the difficulty of accessing the console. This is already done for Android. This is an updated version of https://github.com/bevyengine/bevy/pull/4462. ## Solution This PR uses Absolucy's [tracing-oslog](https://github.com/Absolucy/tracing-oslog) ([ZLib license](https://github.com/Absolucy/tracing-oslog/blob/main/LICENSE.md)) for iOS in order to use Apple's `os_log`. ## Testing I ran `examples/mobile` with the logging from `examples/app/logs.rs` on an iOS device, I then checked the logs could be filtered in the MacOS Console.app. ## Changelog - Change bevy_log to use Apple's os_log on iOS. ## Questions for Reviewers It's worth noting that the dependency this adds hasn't had bug fixes released in a few years, so we may want to consider one or more of: 1. a feature flag to opt-in, and it would also allow `os_log` on MacOS 2. merge as-is and have some (minor?) upstream bugs 3. hold off on this PR until a suitable alternative dependency arises 4. maintain our own implementation ## Future work In a follow-up PR it might be good to make the `subsystem` field have a better default value, like [this one](https://github.com/bevyengine/bevy/blob/main/examples/mobile/bevy_mobile_example.xcodeproj/project.pbxproj#L363). That value can be retrieved programmatically if we bind another system API (For posterity in Swift this is `Bundle.main.bundleIdentifier`, but the C/ObjC equivalent is likely easier to bind). This would almost always be the correct value, while the current default is unlikely to ever be correct. --------- Co-authored-by: Dusty DeWeese <dustin.deweese@gmail.com> Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Carter Anderson <mcanders1@gmail.com> Co-authored-by: François Mockers <francois.mockers@vleue.com>
2024-10-11 08:58:14 +00:00
async-std = "1.13"
add examples on how to have a data source running in another thread / in a task pool thread (#2915) Add two examples on how to communicate with a task that is running either in another thread or in a thread from `AsyncComputeTaskPool`. Loosely based on https://github.com/bevyengine/bevy/discussions/1150
2022-02-05 01:52:47 +00:00
crossbeam-channel = "0.5.0"
Enhance many_cubes stress test use cases (#9596) # Objective - Make `many_cubes` suitable for testing various parts of the upcoming batching work. ## Solution - Use `argh` for CLI. - Default to the sphere layout as it is more useful for benchmarking. - Add a benchmark mode that advances the camera by a fixed step to render the same frames across runs. - Add an option to vary the material data per-instance. The color is randomized. - Add an option to generate a number of textures and randomly choose one per instance. - Use seeded `StdRng` for deterministic random numbers.
2023-09-02 14:49:32 +00:00
argh = "0.1.12"
Disentangle bevy_utils/bevy_core's reexported dependencies (#12313) # Objective Make bevy_utils less of a compilation bottleneck. Tackle #11478. ## Solution * Move all of the directly reexported dependencies and move them to where they're actually used. * Remove the UUID utilities that have gone unused since `TypePath` took over for `TypeUuid`. * There was also a extraneous bytemuck dependency on `bevy_core` that has not been used for a long time (since `encase` became the primary way to prepare GPU buffers). * Remove the `all_tuples` macro reexport from bevy_ecs since it's accessible from `bevy_utils`. --- ## Changelog Removed: Many of the reexports from bevy_utils (petgraph, uuid, nonmax, smallvec, and thiserror). Removed: bevy_core's reexports of bytemuck. ## Migration Guide bevy_utils' reexports of petgraph, uuid, nonmax, smallvec, and thiserror have been removed. bevy_core' reexports of bytemuck's types has been removed. Add them as dependencies in your own crate instead.
2024-03-07 02:30:15 +00:00
thiserror = "1.0"
Allow `AssetServer::load` to acquire a guard item. (#13051) # Objective Supercedes #12881 . Added a simple implementation that allows the user to react to multiple asset loads both synchronously and asynchronously. ## Solution Added `load_acquire`, that holds an item and drops it when loading is finished or failed. When used synchronously Hold an `Arc<()>`, check for `Arc::strong_count() == 1` when all loading completed. When used asynchronously Hold a `SemaphoreGuard`, await on `acquire_all` for completion. This implementation has more freedom than the original in my opinion. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Zachary Harrold <zac@harrold.com.au>
2024-05-23 13:28:29 +00:00
event-listener = "5.3.0"
Initial implementation of the Bevy Remote Protocol (Adopted) (#14880) # Objective Adopted from #13563. The goal is to implement the Bevy Remote Protocol over HTTP/JSON, allowing the ECS to be interacted with remotely. ## Solution At a high level, there are really two separate things that have been undertaken here: 1. First, `RemotePlugin` has been created, which has the effect of embedding a [JSON-RPC](https://www.jsonrpc.org/specification) endpoint into a Bevy application. 2. Second, the [Bevy Remote Protocol verbs](https://gist.github.com/coreh/1baf6f255d7e86e4be29874d00137d1d#file-bevy-remote-protocol-md) (excluding `POLL`) have been implemented as remote methods for that JSON-RPC endpoint under a Bevy-exclusive namespace (e.g. `bevy/get`, `bevy/list`, etc.). To avoid some repetition, here is the crate-level documentation, which explains the request/response structure, built-in-methods, and custom method configuration: <details> <summary>Click to view crate-level docs</summary> ```rust //! An implementation of the Bevy Remote Protocol over HTTP and JSON, to allow //! for remote control of a Bevy app. //! //! Adding the [`RemotePlugin`] to your [`App`] causes Bevy to accept //! connections over HTTP (by default, on port 15702) while your app is running. //! These *remote clients* can inspect and alter the state of the //! entity-component system. Clients are expected to `POST` JSON requests to the //! root URL; see the `client` example for a trivial example of use. //! //! The Bevy Remote Protocol is based on the JSON-RPC 2.0 protocol. //! //! ## Request objects //! //! A typical client request might look like this: //! //! ```json //! { //! "method": "bevy/get", //! "id": 0, //! "params": { //! "entity": 4294967298, //! "components": [ //! "bevy_transform::components::transform::Transform" //! ] //! } //! } //! ``` //! //! The `id` and `method` fields are required. The `param` field may be omitted //! for certain methods: //! //! * `id` is arbitrary JSON data. The server completely ignores its contents, //! and the client may use it for any purpose. It will be copied via //! serialization and deserialization (so object property order, etc. can't be //! relied upon to be identical) and sent back to the client as part of the //! response. //! //! * `method` is a string that specifies one of the possible [`BrpRequest`] //! variants: `bevy/query`, `bevy/get`, `bevy/insert`, etc. It's case-sensitive. //! //! * `params` is parameter data specific to the request. //! //! For more information, see the documentation for [`BrpRequest`]. //! [`BrpRequest`] is serialized to JSON via `serde`, so [the `serde` //! documentation] may be useful to clarify the correspondence between the Rust //! structure and the JSON format. //! //! ## Response objects //! //! A response from the server to the client might look like this: //! //! ```json //! { //! "jsonrpc": "2.0", //! "id": 0, //! "result": { //! "bevy_transform::components::transform::Transform": { //! "rotation": { "x": 0.0, "y": 0.0, "z": 0.0, "w": 1.0 }, //! "scale": { "x": 1.0, "y": 1.0, "z": 1.0 }, //! "translation": { "x": 0.0, "y": 0.5, "z": 0.0 } //! } //! } //! } //! ``` //! //! The `id` field will always be present. The `result` field will be present if the //! request was successful. Otherwise, an `error` field will replace it. //! //! * `id` is the arbitrary JSON data that was sent as part of the request. It //! will be identical to the `id` data sent during the request, modulo //! serialization and deserialization. If there's an error reading the `id` field, //! it will be `null`. //! //! * `result` will be present if the request succeeded and will contain the response //! specific to the request. //! //! * `error` will be present if the request failed and will contain an error object //! with more information about the cause of failure. //! //! ## Error objects //! //! An error object might look like this: //! //! ```json //! { //! "code": -32602, //! "message": "Missing \"entity\" field" //! } //! ``` //! //! The `code` and `message` fields will always be present. There may also be a `data` field. //! //! * `code` is an integer representing the kind of an error that happened. Error codes documented //! in the [`error_codes`] module. //! //! * `message` is a short, one-sentence human-readable description of the error. //! //! * `data` is an optional field of arbitrary type containing additional information about the error. //! //! ## Built-in methods //! //! The Bevy Remote Protocol includes a number of built-in methods for accessing and modifying data //! in the ECS. Each of these methods uses the `bevy/` prefix, which is a namespace reserved for //! BRP built-in methods. //! //! ### bevy/get //! //! Retrieve the values of one or more components from an entity. //! //! `params`: //! - `entity`: The ID of the entity whose components will be fetched. //! - `components`: An array of fully-qualified type names of components to fetch. //! //! `result`: A map associating each type name to its value on the requested entity. //! //! ### bevy/query //! //! Perform a query over components in the ECS, returning all matching entities and their associated //! component values. //! //! All of the arrays that comprise this request are optional, and when they are not provided, they //! will be treated as if they were empty. //! //! `params`: //! `params`: //! - `data`: //! - `components` (optional): An array of fully-qualified type names of components to fetch. //! - `option` (optional): An array of fully-qualified type names of components to fetch optionally. //! - `has` (optional): An array of fully-qualified type names of components whose presence will be //! reported as boolean values. //! - `filter` (optional): //! - `with` (optional): An array of fully-qualified type names of components that must be present //! on entities in order for them to be included in results. //! - `without` (optional): An array of fully-qualified type names of components that must *not* be //! present on entities in order for them to be included in results. //! //! `result`: An array, each of which is an object containing: //! - `entity`: The ID of a query-matching entity. //! - `components`: A map associating each type name from `components`/`option` to its value on the matching //! entity if the component is present. //! - `has`: A map associating each type name from `has` to a boolean value indicating whether or not the //! entity has that component. If `has` was empty or omitted, this key will be omitted in the response. //! //! ### bevy/spawn //! //! Create a new entity with the provided components and return the resulting entity ID. //! //! `params`: //! - `components`: A map associating each component's fully-qualified type name with its value. //! //! `result`: //! - `entity`: The ID of the newly spawned entity. //! //! ### bevy/destroy //! //! Despawn the entity with the given ID. //! //! `params`: //! - `entity`: The ID of the entity to be despawned. //! //! `result`: null. //! //! ### bevy/remove //! //! Delete one or more components from an entity. //! //! `params`: //! - `entity`: The ID of the entity whose components should be removed. //! - `components`: An array of fully-qualified type names of components to be removed. //! //! `result`: null. //! //! ### bevy/insert //! //! Insert one or more components into an entity. //! //! `params`: //! - `entity`: The ID of the entity to insert components into. //! - `components`: A map associating each component's fully-qualified type name with its value. //! //! `result`: null. //! //! ### bevy/reparent //! //! Assign a new parent to one or more entities. //! //! `params`: //! - `entities`: An array of entity IDs of entities that will be made children of the `parent`. //! - `parent` (optional): The entity ID of the parent to which the child entities will be assigned. //! If excluded, the given entities will be removed from their parents. //! //! `result`: null. //! //! ### bevy/list //! //! List all registered components or all components present on an entity. //! //! When `params` is not provided, this lists all registered components. If `params` is provided, //! this lists only those components present on the provided entity. //! //! `params` (optional): //! - `entity`: The ID of the entity whose components will be listed. //! //! `result`: An array of fully-qualified type names of components. //! //! ## Custom methods //! //! In addition to the provided methods, the Bevy Remote Protocol can be extended to include custom //! methods. This is primarily done during the initialization of [`RemotePlugin`], although the //! methods may also be extended at runtime using the [`RemoteMethods`] resource. //! //! ### Example //! ```ignore //! fn main() { //! App::new() //! .add_plugins(DefaultPlugins) //! .add_plugins( //! // `default` adds all of the built-in methods, while `with_method` extends them //! RemotePlugin::default() //! .with_method("super_user/cool_method".to_owned(), path::to::my::cool::handler) //! // ... more methods can be added by chaining `with_method` //! ) //! .add_systems( //! // ... standard application setup //! ) //! .run(); //! } //! ``` //! //! The handler is expected to be a system-convertible function which takes optional JSON parameters //! as input and returns a [`BrpResult`]. This means that it should have a type signature which looks //! something like this: //! ``` //! # use serde_json::Value; //! # use bevy_ecs::prelude::{In, World}; //! # use bevy_remote::BrpResult; //! fn handler(In(params): In<Option<Value>>, world: &mut World) -> BrpResult { //! todo!() //! } //! ``` //! //! Arbitrary system parameters can be used in conjunction with the optional `Value` input. The //! handler system will always run with exclusive `World` access. //! //! [the `serde` documentation]: https://serde.rs/ ``` </details> ### Message lifecycle At a high level, the lifecycle of client-server interactions is something like this: 1. The client sends one or more `BrpRequest`s. The deserialized version of that is just the Rust representation of a JSON-RPC request, and it looks like this: ```rust pub struct BrpRequest { /// The action to be performed. Parsing is deferred for the sake of error reporting. pub method: Option<Value>, /// Arbitrary data that will be returned verbatim to the client as part of /// the response. pub id: Option<Value>, /// The parameters, specific to each method. /// /// These are passed as the first argument to the method handler. /// Sometimes params can be omitted. pub params: Option<Value>, } ``` 2. These requests are accumulated in a mailbox resource (small lie but close enough). 3. Each update, the mailbox is drained by a system `process_remote_requests`, where each request is processed according to its `method`, which has an associated handler. Each handler is a Bevy system that runs with exclusive world access and returns a result; e.g.: ```rust pub fn process_remote_get_request(In(params): In<Option<Value>>, world: &World) -> BrpResult { // ... } ``` 4. The result (or an error) is reported back to the client. ## Testing This can be tested by using the `server` and `client` examples. The `client` example is not particularly exhaustive at the moment (it only creates barebones `bevy/query` requests) but is still informative. Other queries can be made using `curl` with the `server` example running. For example, to make a `bevy/list` request and list all registered components: ```bash curl -X POST -d '{ "jsonrpc": "2.0", "id": 1, "method": "bevy/list" }' 127.0.0.1:15702 | jq . ``` --- ## Future direction There were a couple comments on BRP versioning while this was in draft. I agree that BRP versioning is a good idea, but I think that it requires some consensus on a couple fronts: - First of all, what does the version actually mean? Is it a version for the protocol itself or for the `bevy/*` methods implemented using it? Both? - Where does the version actually live? The most natural place is just where we have `"jsonrpc"` right now (at least if it's versioning the protocol itself), but this means we're not actually conforming to JSON-RPC any more (so, for example, any client library used to construct JSON-RPC requests would stop working). I'm not really against that, but it's at least a real decision. - What do we actually do when we encounter mismatched versions? Adding handling for this would be actual scope creep instead of just a little add-on in my opinion. Another thing that would be nice is making the internal structure of the implementation less JSON-specific. Right now, for example, component values that will appear in server responses are quite eagerly converted to JSON `Value`s, which prevents disentangling the handler logic from the communication medium, but it can probably be done in principle and I imagine it would enable more code reuse (e.g. for custom method handlers) in addition to making the internals more readily usable for other formats. --------- Co-authored-by: Patrick Walton <pcwalton@mimiga.net> Co-authored-by: DragonGamesStudios <margos.michal@gmail.com> Co-authored-by: Christopher Biscardi <chris@christopherbiscardi.com> Co-authored-by: Gino Valente <49806985+MrGVSV@users.noreply.github.com>
2024-09-23 18:36:16 +00:00
hyper = { version = "1", features = ["server", "http1"] }
http-body-util = "0.1"
anyhow = "1"
macro_rules_attribute = "0.2"
Remove `accesskit` re-export from `bevy_a11y` (#16257) # Objective - Fixes #16235 ## Solution - Both Bevy and AccessKit export a `Node` struct, to reduce confusion Bevy will no longer re-export `AccessKit` from `bevy_a11y` ## Testing - Tested locally ## Migration Guide ```diff # main.rs -- use bevy_a11y::{ -- accesskit::{Node, Rect, Role}, -- AccessibilityNode, -- }; ++ use bevy_a11y::AccessibilityNode; ++ use accesskit::{Node, Rect, Role}; # Cargo.toml ++ accesskit = "0.17" ``` - Users will need to add `accesskit = "0.17"` to the dependencies section of their `Cargo.toml` file and update their `accesskit` use statements to come directly from the external crate instead of `bevy_a11y`. - Make sure to keep the versions of `accesskit` aligned with the versions Bevy uses.
2024-11-08 21:01:16 +00:00
accesskit = "0.17"
Initial implementation of the Bevy Remote Protocol (Adopted) (#14880) # Objective Adopted from #13563. The goal is to implement the Bevy Remote Protocol over HTTP/JSON, allowing the ECS to be interacted with remotely. ## Solution At a high level, there are really two separate things that have been undertaken here: 1. First, `RemotePlugin` has been created, which has the effect of embedding a [JSON-RPC](https://www.jsonrpc.org/specification) endpoint into a Bevy application. 2. Second, the [Bevy Remote Protocol verbs](https://gist.github.com/coreh/1baf6f255d7e86e4be29874d00137d1d#file-bevy-remote-protocol-md) (excluding `POLL`) have been implemented as remote methods for that JSON-RPC endpoint under a Bevy-exclusive namespace (e.g. `bevy/get`, `bevy/list`, etc.). To avoid some repetition, here is the crate-level documentation, which explains the request/response structure, built-in-methods, and custom method configuration: <details> <summary>Click to view crate-level docs</summary> ```rust //! An implementation of the Bevy Remote Protocol over HTTP and JSON, to allow //! for remote control of a Bevy app. //! //! Adding the [`RemotePlugin`] to your [`App`] causes Bevy to accept //! connections over HTTP (by default, on port 15702) while your app is running. //! These *remote clients* can inspect and alter the state of the //! entity-component system. Clients are expected to `POST` JSON requests to the //! root URL; see the `client` example for a trivial example of use. //! //! The Bevy Remote Protocol is based on the JSON-RPC 2.0 protocol. //! //! ## Request objects //! //! A typical client request might look like this: //! //! ```json //! { //! "method": "bevy/get", //! "id": 0, //! "params": { //! "entity": 4294967298, //! "components": [ //! "bevy_transform::components::transform::Transform" //! ] //! } //! } //! ``` //! //! The `id` and `method` fields are required. The `param` field may be omitted //! for certain methods: //! //! * `id` is arbitrary JSON data. The server completely ignores its contents, //! and the client may use it for any purpose. It will be copied via //! serialization and deserialization (so object property order, etc. can't be //! relied upon to be identical) and sent back to the client as part of the //! response. //! //! * `method` is a string that specifies one of the possible [`BrpRequest`] //! variants: `bevy/query`, `bevy/get`, `bevy/insert`, etc. It's case-sensitive. //! //! * `params` is parameter data specific to the request. //! //! For more information, see the documentation for [`BrpRequest`]. //! [`BrpRequest`] is serialized to JSON via `serde`, so [the `serde` //! documentation] may be useful to clarify the correspondence between the Rust //! structure and the JSON format. //! //! ## Response objects //! //! A response from the server to the client might look like this: //! //! ```json //! { //! "jsonrpc": "2.0", //! "id": 0, //! "result": { //! "bevy_transform::components::transform::Transform": { //! "rotation": { "x": 0.0, "y": 0.0, "z": 0.0, "w": 1.0 }, //! "scale": { "x": 1.0, "y": 1.0, "z": 1.0 }, //! "translation": { "x": 0.0, "y": 0.5, "z": 0.0 } //! } //! } //! } //! ``` //! //! The `id` field will always be present. The `result` field will be present if the //! request was successful. Otherwise, an `error` field will replace it. //! //! * `id` is the arbitrary JSON data that was sent as part of the request. It //! will be identical to the `id` data sent during the request, modulo //! serialization and deserialization. If there's an error reading the `id` field, //! it will be `null`. //! //! * `result` will be present if the request succeeded and will contain the response //! specific to the request. //! //! * `error` will be present if the request failed and will contain an error object //! with more information about the cause of failure. //! //! ## Error objects //! //! An error object might look like this: //! //! ```json //! { //! "code": -32602, //! "message": "Missing \"entity\" field" //! } //! ``` //! //! The `code` and `message` fields will always be present. There may also be a `data` field. //! //! * `code` is an integer representing the kind of an error that happened. Error codes documented //! in the [`error_codes`] module. //! //! * `message` is a short, one-sentence human-readable description of the error. //! //! * `data` is an optional field of arbitrary type containing additional information about the error. //! //! ## Built-in methods //! //! The Bevy Remote Protocol includes a number of built-in methods for accessing and modifying data //! in the ECS. Each of these methods uses the `bevy/` prefix, which is a namespace reserved for //! BRP built-in methods. //! //! ### bevy/get //! //! Retrieve the values of one or more components from an entity. //! //! `params`: //! - `entity`: The ID of the entity whose components will be fetched. //! - `components`: An array of fully-qualified type names of components to fetch. //! //! `result`: A map associating each type name to its value on the requested entity. //! //! ### bevy/query //! //! Perform a query over components in the ECS, returning all matching entities and their associated //! component values. //! //! All of the arrays that comprise this request are optional, and when they are not provided, they //! will be treated as if they were empty. //! //! `params`: //! `params`: //! - `data`: //! - `components` (optional): An array of fully-qualified type names of components to fetch. //! - `option` (optional): An array of fully-qualified type names of components to fetch optionally. //! - `has` (optional): An array of fully-qualified type names of components whose presence will be //! reported as boolean values. //! - `filter` (optional): //! - `with` (optional): An array of fully-qualified type names of components that must be present //! on entities in order for them to be included in results. //! - `without` (optional): An array of fully-qualified type names of components that must *not* be //! present on entities in order for them to be included in results. //! //! `result`: An array, each of which is an object containing: //! - `entity`: The ID of a query-matching entity. //! - `components`: A map associating each type name from `components`/`option` to its value on the matching //! entity if the component is present. //! - `has`: A map associating each type name from `has` to a boolean value indicating whether or not the //! entity has that component. If `has` was empty or omitted, this key will be omitted in the response. //! //! ### bevy/spawn //! //! Create a new entity with the provided components and return the resulting entity ID. //! //! `params`: //! - `components`: A map associating each component's fully-qualified type name with its value. //! //! `result`: //! - `entity`: The ID of the newly spawned entity. //! //! ### bevy/destroy //! //! Despawn the entity with the given ID. //! //! `params`: //! - `entity`: The ID of the entity to be despawned. //! //! `result`: null. //! //! ### bevy/remove //! //! Delete one or more components from an entity. //! //! `params`: //! - `entity`: The ID of the entity whose components should be removed. //! - `components`: An array of fully-qualified type names of components to be removed. //! //! `result`: null. //! //! ### bevy/insert //! //! Insert one or more components into an entity. //! //! `params`: //! - `entity`: The ID of the entity to insert components into. //! - `components`: A map associating each component's fully-qualified type name with its value. //! //! `result`: null. //! //! ### bevy/reparent //! //! Assign a new parent to one or more entities. //! //! `params`: //! - `entities`: An array of entity IDs of entities that will be made children of the `parent`. //! - `parent` (optional): The entity ID of the parent to which the child entities will be assigned. //! If excluded, the given entities will be removed from their parents. //! //! `result`: null. //! //! ### bevy/list //! //! List all registered components or all components present on an entity. //! //! When `params` is not provided, this lists all registered components. If `params` is provided, //! this lists only those components present on the provided entity. //! //! `params` (optional): //! - `entity`: The ID of the entity whose components will be listed. //! //! `result`: An array of fully-qualified type names of components. //! //! ## Custom methods //! //! In addition to the provided methods, the Bevy Remote Protocol can be extended to include custom //! methods. This is primarily done during the initialization of [`RemotePlugin`], although the //! methods may also be extended at runtime using the [`RemoteMethods`] resource. //! //! ### Example //! ```ignore //! fn main() { //! App::new() //! .add_plugins(DefaultPlugins) //! .add_plugins( //! // `default` adds all of the built-in methods, while `with_method` extends them //! RemotePlugin::default() //! .with_method("super_user/cool_method".to_owned(), path::to::my::cool::handler) //! // ... more methods can be added by chaining `with_method` //! ) //! .add_systems( //! // ... standard application setup //! ) //! .run(); //! } //! ``` //! //! The handler is expected to be a system-convertible function which takes optional JSON parameters //! as input and returns a [`BrpResult`]. This means that it should have a type signature which looks //! something like this: //! ``` //! # use serde_json::Value; //! # use bevy_ecs::prelude::{In, World}; //! # use bevy_remote::BrpResult; //! fn handler(In(params): In<Option<Value>>, world: &mut World) -> BrpResult { //! todo!() //! } //! ``` //! //! Arbitrary system parameters can be used in conjunction with the optional `Value` input. The //! handler system will always run with exclusive `World` access. //! //! [the `serde` documentation]: https://serde.rs/ ``` </details> ### Message lifecycle At a high level, the lifecycle of client-server interactions is something like this: 1. The client sends one or more `BrpRequest`s. The deserialized version of that is just the Rust representation of a JSON-RPC request, and it looks like this: ```rust pub struct BrpRequest { /// The action to be performed. Parsing is deferred for the sake of error reporting. pub method: Option<Value>, /// Arbitrary data that will be returned verbatim to the client as part of /// the response. pub id: Option<Value>, /// The parameters, specific to each method. /// /// These are passed as the first argument to the method handler. /// Sometimes params can be omitted. pub params: Option<Value>, } ``` 2. These requests are accumulated in a mailbox resource (small lie but close enough). 3. Each update, the mailbox is drained by a system `process_remote_requests`, where each request is processed according to its `method`, which has an associated handler. Each handler is a Bevy system that runs with exclusive world access and returns a result; e.g.: ```rust pub fn process_remote_get_request(In(params): In<Option<Value>>, world: &World) -> BrpResult { // ... } ``` 4. The result (or an error) is reported back to the client. ## Testing This can be tested by using the `server` and `client` examples. The `client` example is not particularly exhaustive at the moment (it only creates barebones `bevy/query` requests) but is still informative. Other queries can be made using `curl` with the `server` example running. For example, to make a `bevy/list` request and list all registered components: ```bash curl -X POST -d '{ "jsonrpc": "2.0", "id": 1, "method": "bevy/list" }' 127.0.0.1:15702 | jq . ``` --- ## Future direction There were a couple comments on BRP versioning while this was in draft. I agree that BRP versioning is a good idea, but I think that it requires some consensus on a couple fronts: - First of all, what does the version actually mean? Is it a version for the protocol itself or for the `bevy/*` methods implemented using it? Both? - Where does the version actually live? The most natural place is just where we have `"jsonrpc"` right now (at least if it's versioning the protocol itself), but this means we're not actually conforming to JSON-RPC any more (so, for example, any client library used to construct JSON-RPC requests would stop working). I'm not really against that, but it's at least a real decision. - What do we actually do when we encounter mismatched versions? Adding handling for this would be actual scope creep instead of just a little add-on in my opinion. Another thing that would be nice is making the internal structure of the implementation less JSON-specific. Right now, for example, component values that will appear in server responses are quite eagerly converted to JSON `Value`s, which prevents disentangling the handler logic from the communication medium, but it can probably be done in principle and I imagine it would enable more code reuse (e.g. for custom method handlers) in addition to making the internals more readily usable for other formats. --------- Co-authored-by: Patrick Walton <pcwalton@mimiga.net> Co-authored-by: DragonGamesStudios <margos.michal@gmail.com> Co-authored-by: Christopher Biscardi <chris@christopherbiscardi.com> Co-authored-by: Gino Valente <49806985+MrGVSV@users.noreply.github.com>
2024-09-23 18:36:16 +00:00
[target.'cfg(not(target_family = "wasm"))'.dev-dependencies]
smol = "2"
smol-macros = "0.1"
smol-hyper = "0.1"
ureq = { version = "2.10.1", features = ["json"] }
render resources refactor and normal forward rendering
2019-12-24 00:13:05 +00:00
fix: upgrade to winit v0.30 (#13366) # Objective - Upgrade winit to v0.30 - Fixes https://github.com/bevyengine/bevy/issues/13331 ## Solution This is a rewrite/adaptation of the new trait system described and implemented in `winit` v0.30. ## Migration Guide The custom UserEvent is now renamed as WakeUp, used to wake up the loop if anything happens outside the app (a new [custom_user_event](https://github.com/bevyengine/bevy/pull/13366/files#diff-2de8c0a8d3028d0059a3d80ae31b2bbc1cde2595ce2d317ea378fe3e0cf6ef2d) shows this behavior. The internal `UpdateState` has been removed and replaced internally by the AppLifecycle. When changed, the AppLifecycle is sent as an event. The `UpdateMode` now accepts only two values: `Continuous` and `Reactive`, but the latter exposes 3 new properties to enable reactive to device, user or window events. The previous `UpdateMode::Reactive` is now equivalent to `UpdateMode::reactive()`, while `UpdateMode::ReactiveLowPower` to `UpdateMode::reactive_low_power()`. The `ApplicationLifecycle` has been renamed as `AppLifecycle`, and now contains the possible values of the application state inside the event loop: * `Idle`: the loop has not started yet * `Running` (previously called `Started`): the loop is running * `WillSuspend`: the loop is going to be suspended * `Suspended`: the loop is suspended * `WillResume`: the loop is going to be resumed Note: the `Resumed` state has been removed since the resumed app is just running. Finally, now that `winit` enables this, it extends the `WinitPlugin` to support custom events. ## Test platforms - [x] Windows - [x] MacOs - [x] Linux (x11) - [x] Linux (Wayland) - [x] Android - [x] iOS - [x] WASM/WebGPU - [x] WASM/WebGL2 ## Outstanding issues / regressions - [ ] iOS: build failed in CI - blocking, but may just be flakiness - [x] Cross-platform: when the window is maximised, changes in the scale factor don't apply, to make them apply one has to make the window smaller again. (Re-maximising keeps the updated scale factor) - non-blocking, but good to fix - [ ] Android: it's pretty easy to quickly open and close the app and then the music keeps playing when suspended. - non-blocking but worrying - [ ] Web: the application will hang when switching tabs - Not new, duplicate of https://github.com/bevyengine/bevy/issues/13486 - [ ] Cross-platform?: Screenshot failure, `ERROR present_frames: wgpu_core::present: No work has been submitted for this frame before` taking the first screenshot, but after pressing space - non-blocking, but good to fix --------- Co-authored-by: François <francois.mockers@vleue.com>
2024-06-03 13:06:48 +00:00
[target.'cfg(target_arch = "wasm32")'.dev-dependencies]
wasm-bindgen = { version = "0.2" }
web-sys = { version = "0.3", features = ["Window"] }
organize examples and add ecs guide
2020-05-01 20:12:47 +00:00
[[example]]
name = "hello_world"
path = "examples/hello_world.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
organize examples and add ecs guide
2020-05-01 20:12:47 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.hello_world]
hidden = true
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
# 2D Rendering
Revamp Bloom (#6677) ![image](https://user-images.githubusercontent.com/47158642/220197588-25e11022-02e4-45f3-b2e5-392c4ce7a025.png) Huge credit to @StarLederer, who did almost all of the work on this. We're just reusing this PR to keep everything in one place. # Objective 1. Make bloom more physically based. 1. Improve artistic control. 1. Allow to use bloom as screen blur. 1. Fix #6634. 1. Address #6655 (although the author makes incorrect conclusions). ## Solution 1. Set the default threshold to 0. 2. Lerp between bloom textures when `composite_mode: BloomCompositeMode::EnergyConserving`. 1. Use [a parametric function](https://starlederer.github.io/bloom) to control blend levels for each bloom texture. In the future this can be controlled per-pixel for things like lens dirt. 3. Implement BloomCompositeMode::Additive` for situations where the old school look is desired. ## Changelog * Bloom now looks different. * Added `BloomSettings:lf_boost`, `BloomSettings:lf_boost_curvature`, `BloomSettings::high_pass_frequency` and `BloomSettings::composite_mode`. * `BloomSettings::scale` removed. * `BloomSettings::knee` renamed to `BloomPrefilterSettings::softness`. * `BloomSettings::threshold` renamed to `BloomPrefilterSettings::threshold`. * The bloom example has been renamed to bloom_3d and improved. A bloom_2d example was added. ## Migration Guide * Refactor mentions of `BloomSettings::knee` and `BloomSettings::threshold` as `BloomSettings::prefilter_settings` where knee is now `softness`. * If defined without `..default()` add `..default()` to definitions of `BloomSettings` instances or manually define missing fields. * Adapt to Bloom looking visually different (if needed). Co-authored-by: Herman Lederer <germans.lederers@gmail.com>
2023-03-04 12:05:26 +00:00
[[example]]
name = "bloom_2d"
path = "examples/2d/bloom_2d.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Revamp Bloom (#6677) ![image](https://user-images.githubusercontent.com/47158642/220197588-25e11022-02e4-45f3-b2e5-392c4ce7a025.png) Huge credit to @StarLederer, who did almost all of the work on this. We're just reusing this PR to keep everything in one place. # Objective 1. Make bloom more physically based. 1. Improve artistic control. 1. Allow to use bloom as screen blur. 1. Fix #6634. 1. Address #6655 (although the author makes incorrect conclusions). ## Solution 1. Set the default threshold to 0. 2. Lerp between bloom textures when `composite_mode: BloomCompositeMode::EnergyConserving`. 1. Use [a parametric function](https://starlederer.github.io/bloom) to control blend levels for each bloom texture. In the future this can be controlled per-pixel for things like lens dirt. 3. Implement BloomCompositeMode::Additive` for situations where the old school look is desired. ## Changelog * Bloom now looks different. * Added `BloomSettings:lf_boost`, `BloomSettings:lf_boost_curvature`, `BloomSettings::high_pass_frequency` and `BloomSettings::composite_mode`. * `BloomSettings::scale` removed. * `BloomSettings::knee` renamed to `BloomPrefilterSettings::softness`. * `BloomSettings::threshold` renamed to `BloomPrefilterSettings::threshold`. * The bloom example has been renamed to bloom_3d and improved. A bloom_2d example was added. ## Migration Guide * Refactor mentions of `BloomSettings::knee` and `BloomSettings::threshold` as `BloomSettings::prefilter_settings` where knee is now `softness`. * If defined without `..default()` add `..default()` to definitions of `BloomSettings` instances or manually define missing fields. * Adapt to Bloom looking visually different (if needed). Co-authored-by: Herman Lederer <germans.lederers@gmail.com>
2023-03-04 12:05:26 +00:00
[package.metadata.example.bloom_2d]
name = "2D Bloom"
description = "Illustrates bloom post-processing in 2d"
category = "2D Rendering"
Fix bloom wasm support (#8631) # Objective - Fixes #7352 ## Solution GLES doesn't support binding specific mip levels for sampling. Fallback to using separate textures instead. - [wgpu-hal/src/gles/device.rs](https://github.com/gfx-rs/wgpu/blob/628a95cd1c27abce4d4ff2ffe4558cc4ef1e7fd3/wgpu-hal/src/gles/device.rs#L1038) --- --------- Co-authored-by: Wilhelm Vallrand <>
2023-05-19 20:11:41 +00:00
wasm = true
Revamp Bloom (#6677) ![image](https://user-images.githubusercontent.com/47158642/220197588-25e11022-02e4-45f3-b2e5-392c4ce7a025.png) Huge credit to @StarLederer, who did almost all of the work on this. We're just reusing this PR to keep everything in one place. # Objective 1. Make bloom more physically based. 1. Improve artistic control. 1. Allow to use bloom as screen blur. 1. Fix #6634. 1. Address #6655 (although the author makes incorrect conclusions). ## Solution 1. Set the default threshold to 0. 2. Lerp between bloom textures when `composite_mode: BloomCompositeMode::EnergyConserving`. 1. Use [a parametric function](https://starlederer.github.io/bloom) to control blend levels for each bloom texture. In the future this can be controlled per-pixel for things like lens dirt. 3. Implement BloomCompositeMode::Additive` for situations where the old school look is desired. ## Changelog * Bloom now looks different. * Added `BloomSettings:lf_boost`, `BloomSettings:lf_boost_curvature`, `BloomSettings::high_pass_frequency` and `BloomSettings::composite_mode`. * `BloomSettings::scale` removed. * `BloomSettings::knee` renamed to `BloomPrefilterSettings::softness`. * `BloomSettings::threshold` renamed to `BloomPrefilterSettings::threshold`. * The bloom example has been renamed to bloom_3d and improved. A bloom_2d example was added. ## Migration Guide * Refactor mentions of `BloomSettings::knee` and `BloomSettings::threshold` as `BloomSettings::prefilter_settings` where knee is now `softness`. * If defined without `..default()` add `..default()` to definitions of `BloomSettings` instances or manually define missing fields. * Adapt to Bloom looking visually different (if needed). Co-authored-by: Herman Lederer <germans.lederers@gmail.com>
2023-03-04 12:05:26 +00:00
Add move sprite example. (#2414) ## Objective There is no bevy example that shows how to transform a sprite. At least as its singular purpose. This creates an example of how to use transform.translate to move a sprite up and down. The last pull request had issues that I couldn't fix so I created a new one ### Solution I created move_sprite example. Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-02-02 02:44:51 +00:00
[[example]]
name = "move_sprite"
path = "examples/2d/move_sprite.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add move sprite example. (#2414) ## Objective There is no bevy example that shows how to transform a sprite. At least as its singular purpose. This creates an example of how to use transform.translate to move a sprite up and down. The last pull request had issues that I couldn't fix so I created a new one ### Solution I created move_sprite example. Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-02-02 02:44:51 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.move_sprite]
name = "Move Sprite"
description = "Changes the transform of a sprite"
category = "2D Rendering"
wasm = true
Add example for `Camera::viewport_to_world` (#7179) Fixes #7177 --------- Co-authored-by: Rob Parrett <robparrett@gmail.com>
2023-09-11 18:52:11 +00:00
[[example]]
name = "2d_viewport_to_world"
path = "examples/2d/2d_viewport_to_world.rs"
Fix some doc warnings (#12961) # Objective - Fix some doc warnings - Add doc-scrape-examples to all examples Moved from #12692 I run `cargo +nightly doc --workspace --all-features --no-deps -Zunstable-options -Zrustdoc-scrape-examples` <details> ``` warning: public documentation for `GzAssetLoaderError` links to private item `GzAssetLoader` --> examples/asset/asset_decompression.rs:24:47 | 24 | /// Possible errors that can be produced by [`GzAssetLoader`] | ^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: `bevy` (example "asset_decompression") generated 1 warning warning: unresolved link to `shape::Quad` --> examples/2d/mesh2d.rs:3:15 | 3 | //! [`Quad`]: shape::Quad | ^^^^^^^^^^^ no item named `shape` in scope | = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "mesh2d") generated 1 warning warning: unresolved link to `WorldQuery` --> examples/ecs/custom_query_param.rs:1:49 | 1 | //! This example illustrates the usage of the [`WorldQuery`] derive macro, which allows | ^^^^^^^^^^ no item named `WorldQuery` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "custom_query_param") generated 1 warning warning: unresolved link to `shape::Quad` --> examples/2d/mesh2d_vertex_color_texture.rs:4:15 | 4 | //! [`Quad`]: shape::Quad | ^^^^^^^^^^^ no item named `shape` in scope | = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "mesh2d_vertex_color_texture") generated 1 warning warning: public documentation for `TextPlugin` links to private item `CoolText` --> examples/asset/processing/asset_processing.rs:48:9 | 48 | /// * [`CoolText`]: a custom RON text format that supports dependencies and embedded dependencies | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: public documentation for `TextPlugin` links to private item `Text` --> examples/asset/processing/asset_processing.rs:49:9 | 49 | /// * [`Text`]: a "normal" plain text file | ^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: public documentation for `TextPlugin` links to private item `CoolText` --> examples/asset/processing/asset_processing.rs:51:57 | 51 | /// It also defines an asset processor that will load [`CoolText`], resolve embedded dependenc... | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: `bevy` (example "asset_processing") generated 3 warnings warning: public documentation for `CustomAssetLoaderError` links to private item `CustomAssetLoader` --> examples/asset/custom_asset.rs:20:47 | 20 | /// Possible errors that can be produced by [`CustomAssetLoader`] | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: public documentation for `BlobAssetLoaderError` links to private item `CustomAssetLoader` --> examples/asset/custom_asset.rs:61:47 | 61 | /// Possible errors that can be produced by [`CustomAssetLoader`] | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` ``` ``` warning: `bevy` (example "mesh2d") generated 1 warning warning: public documentation for `log_layers_ecs` links to private item `update_subscriber` --> examples/app/log_layers_ecs.rs:6:18 | 6 | //! Inside the [`update_subscriber`] function we will create a [`mpsc::Sender`] and a [`mpsc::R... | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: unresolved link to `AdvancedLayer` --> examples/app/log_layers_ecs.rs:7:72 | 7 | ... will go into the [`AdvancedLayer`] and the [`Receiver`](mpsc::Receiver) will | ^^^^^^^^^^^^^ no item named `AdvancedLayer` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: unresolved link to `LogEvents` --> examples/app/log_layers_ecs.rs:8:42 | 8 | //! go into a non-send resource called [`LogEvents`] (It has to be non-send because [`Receiver`... | ^^^^^^^^^ no item named `LogEvents` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` warning: public documentation for `log_layers_ecs` links to private item `transfer_log_events` --> examples/app/log_layers_ecs.rs:9:30 | 9 | //! From there we will use [`transfer_log_events`] to transfer log events from [`LogEvents`] to... | ^^^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: unresolved link to `LogEvents` --> examples/app/log_layers_ecs.rs:9:82 | 9 | ...nsfer log events from [`LogEvents`] to an ECS event called [`LogEvent`]. | ^^^^^^^^^ no item named `LogEvents` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` warning: public documentation for `log_layers_ecs` links to private item `LogEvent` --> examples/app/log_layers_ecs.rs:9:119 | 9 | ...nts`] to an ECS event called [`LogEvent`]. | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: public documentation for `log_layers_ecs` links to private item `LogEvent` --> examples/app/log_layers_ecs.rs:11:49 | 11 | //! Finally, after all that we can access the [`LogEvent`] event from our systems and use it. | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` ``` <details/>
2024-04-14 15:23:44 +00:00
doc-scrape-examples = true
Add example for `Camera::viewport_to_world` (#7179) Fixes #7177 --------- Co-authored-by: Rob Parrett <robparrett@gmail.com>
2023-09-11 18:52:11 +00:00
[package.metadata.example.2d_viewport_to_world]
name = "2D Viewport To World"
description = "Demonstrates how to use the `Camera::viewport_to_world_2d` method"
category = "2D Rendering"
wasm = true
Simple 2d rotation example (#3065) # Objective Some new bevy users are unfamiliar with quaternions and have trouble working with rotations in 2D. There has been an [issue](https://github.com/bitshifter/glam-rs/issues/226) raised with glam to add helpers to better support these users, however for now I feel could be better to provide examples of how to do this in Bevy as a starting point for new users. ## Solution I've added a 2d_rotation example which demonstrates 3 different rotation examples to try help get people started: - Rotating and translating a player ship based on keyboard input - An enemy ship type that rotates to face the player ship immediately - An enemy ship type that rotates to face the player at a fixed angular velocity I also have a standalone version of this example here https://github.com/bitshifter/bevy-2d-rotation-example but I think it would be more discoverable if it's included with Bevy.
2022-01-25 22:10:11 +00:00
[[example]]
Rename "2d rotation" example name to "rotation" (#3965) All other examples dont have "2d" prefix in their names (even though they are in 2d folder) and reading README makes user think that example is named "rotation" not "2d_rotation" hence rename PR # Objective - Remove discrepancy between example name in documentation and in cargo ## Solution - Rename example in cargo file
2022-02-25 15:54:03 +00:00
name = "rotation"
Simple 2d rotation example (#3065) # Objective Some new bevy users are unfamiliar with quaternions and have trouble working with rotations in 2D. There has been an [issue](https://github.com/bitshifter/glam-rs/issues/226) raised with glam to add helpers to better support these users, however for now I feel could be better to provide examples of how to do this in Bevy as a starting point for new users. ## Solution I've added a 2d_rotation example which demonstrates 3 different rotation examples to try help get people started: - Rotating and translating a player ship based on keyboard input - An enemy ship type that rotates to face the player ship immediately - An enemy ship type that rotates to face the player at a fixed angular velocity I also have a standalone version of this example here https://github.com/bitshifter/bevy-2d-rotation-example but I think it would be more discoverable if it's included with Bevy.
2022-01-25 22:10:11 +00:00
path = "examples/2d/rotation.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Simple 2d rotation example (#3065) # Objective Some new bevy users are unfamiliar with quaternions and have trouble working with rotations in 2D. There has been an [issue](https://github.com/bitshifter/glam-rs/issues/226) raised with glam to add helpers to better support these users, however for now I feel could be better to provide examples of how to do this in Bevy as a starting point for new users. ## Solution I've added a 2d_rotation example which demonstrates 3 different rotation examples to try help get people started: - Rotating and translating a player ship based on keyboard input - An enemy ship type that rotates to face the player ship immediately - An enemy ship type that rotates to face the player at a fixed angular velocity I also have a standalone version of this example here https://github.com/bitshifter/bevy-2d-rotation-example but I think it would be more discoverable if it's included with Bevy.
2022-01-25 22:10:11 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.rotation]
name = "2D Rotation"
description = "Demonstrates rotating entities in 2D with quaternions"
category = "2D Rendering"
wasm = true
Add 2d meshes and materials (#3460) # Objective The current 2d rendering is specialized to render sprites, we need a generic way to render 2d items, using meshes and materials like we have for 3d. ## Solution I cloned a good part of `bevy_pbr` into `bevy_sprite/src/mesh2d`, removed lighting and pbr itself, adapted it to 2d rendering, added a `ColorMaterial`, and modified the sprite rendering to break batches around 2d meshes. ~~The PR is a bit crude; I tried to change as little as I could in both the parts copied from 3d and the current sprite rendering to make reviewing easier. In the future, I expect we could make the sprite rendering a normal 2d material, cleanly integrated with the rest.~~ _edit: see <https://github.com/bevyengine/bevy/pull/3460#issuecomment-1003605194>_ ## Remaining work - ~~don't require mesh normals~~ _out of scope_ - ~~add an example~~ _done_ - support 2d meshes & materials in the UI? - bikeshed names (I didn't think hard about naming, please check if it's fine) ## Remaining questions - ~~should we add a depth buffer to 2d now that there are 2d meshes?~~ _let's revisit that when we have an opaque render phase_ - ~~should we add MSAA support to the sprites, or remove it from the 2d meshes?~~ _I added MSAA to sprites since it's really needed for 2d meshes_ - ~~how to customize vertex attributes?~~ _#3120_ Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-01-08 01:29:08 +00:00
[[example]]
name = "mesh2d"
path = "examples/2d/mesh2d.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add 2d meshes and materials (#3460) # Objective The current 2d rendering is specialized to render sprites, we need a generic way to render 2d items, using meshes and materials like we have for 3d. ## Solution I cloned a good part of `bevy_pbr` into `bevy_sprite/src/mesh2d`, removed lighting and pbr itself, adapted it to 2d rendering, added a `ColorMaterial`, and modified the sprite rendering to break batches around 2d meshes. ~~The PR is a bit crude; I tried to change as little as I could in both the parts copied from 3d and the current sprite rendering to make reviewing easier. In the future, I expect we could make the sprite rendering a normal 2d material, cleanly integrated with the rest.~~ _edit: see <https://github.com/bevyengine/bevy/pull/3460#issuecomment-1003605194>_ ## Remaining work - ~~don't require mesh normals~~ _out of scope_ - ~~add an example~~ _done_ - support 2d meshes & materials in the UI? - bikeshed names (I didn't think hard about naming, please check if it's fine) ## Remaining questions - ~~should we add a depth buffer to 2d now that there are 2d meshes?~~ _let's revisit that when we have an opaque render phase_ - ~~should we add MSAA support to the sprites, or remove it from the 2d meshes?~~ _I added MSAA to sprites since it's really needed for 2d meshes_ - ~~how to customize vertex attributes?~~ _#3120_ Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-01-08 01:29:08 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.mesh2d]
name = "Mesh 2D"
description = "Renders a 2d mesh"
category = "2D Rendering"
wasm = true
Add 2d meshes and materials (#3460) # Objective The current 2d rendering is specialized to render sprites, we need a generic way to render 2d items, using meshes and materials like we have for 3d. ## Solution I cloned a good part of `bevy_pbr` into `bevy_sprite/src/mesh2d`, removed lighting and pbr itself, adapted it to 2d rendering, added a `ColorMaterial`, and modified the sprite rendering to break batches around 2d meshes. ~~The PR is a bit crude; I tried to change as little as I could in both the parts copied from 3d and the current sprite rendering to make reviewing easier. In the future, I expect we could make the sprite rendering a normal 2d material, cleanly integrated with the rest.~~ _edit: see <https://github.com/bevyengine/bevy/pull/3460#issuecomment-1003605194>_ ## Remaining work - ~~don't require mesh normals~~ _out of scope_ - ~~add an example~~ _done_ - support 2d meshes & materials in the UI? - bikeshed names (I didn't think hard about naming, please check if it's fine) ## Remaining questions - ~~should we add a depth buffer to 2d now that there are 2d meshes?~~ _let's revisit that when we have an opaque render phase_ - ~~should we add MSAA support to the sprites, or remove it from the 2d meshes?~~ _I added MSAA to sprites since it's really needed for 2d meshes_ - ~~how to customize vertex attributes?~~ _#3120_ Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-01-08 01:29:08 +00:00
[[example]]
New circular primitives: `Arc2d`, `CircularSector`, `CircularSegment` (#13482) # Objective Adopted #11748 ## Solution I've rebased on main to fix the merge conflicts. ~~Not quite ready to merge yet~~ * Clippy is happy and the tests are passing, but... * ~~The new shapes in `examples/2d/2d_shapes.rs` don't look right at all~~ Never mind, looks like radians and degrees just got mixed up at some point? * I have updated one doc comment based on a review in the original PR. --------- Co-authored-by: Alexis "spectria" Horizon <spectria.limina@gmail.com> Co-authored-by: Alexis "spectria" Horizon <118812919+spectria-limina@users.noreply.github.com> Co-authored-by: Joona Aalto <jondolf.dev@gmail.com> Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Ben Harper <ben@tukom.org>
2024-05-23 16:12:46 +00:00
name = "mesh2d_arcs"
path = "examples/2d/mesh2d_arcs.rs"
doc-scrape-examples = true
[package.metadata.example.mesh2d_arcs]
name = "Arc 2D Meshes"
description = "Demonstrates UV-mapping of the circular segment and sector primitives"
category = "2D Rendering"
wasm = true
[[example]]
Add 2d meshes and materials (#3460) # Objective The current 2d rendering is specialized to render sprites, we need a generic way to render 2d items, using meshes and materials like we have for 3d. ## Solution I cloned a good part of `bevy_pbr` into `bevy_sprite/src/mesh2d`, removed lighting and pbr itself, adapted it to 2d rendering, added a `ColorMaterial`, and modified the sprite rendering to break batches around 2d meshes. ~~The PR is a bit crude; I tried to change as little as I could in both the parts copied from 3d and the current sprite rendering to make reviewing easier. In the future, I expect we could make the sprite rendering a normal 2d material, cleanly integrated with the rest.~~ _edit: see <https://github.com/bevyengine/bevy/pull/3460#issuecomment-1003605194>_ ## Remaining work - ~~don't require mesh normals~~ _out of scope_ - ~~add an example~~ _done_ - support 2d meshes & materials in the UI? - bikeshed names (I didn't think hard about naming, please check if it's fine) ## Remaining questions - ~~should we add a depth buffer to 2d now that there are 2d meshes?~~ _let's revisit that when we have an opaque render phase_ - ~~should we add MSAA support to the sprites, or remove it from the 2d meshes?~~ _I added MSAA to sprites since it's really needed for 2d meshes_ - ~~how to customize vertex attributes?~~ _#3120_ Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-01-08 01:29:08 +00:00
name = "mesh2d_manual"
path = "examples/2d/mesh2d_manual.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add 2d meshes and materials (#3460) # Objective The current 2d rendering is specialized to render sprites, we need a generic way to render 2d items, using meshes and materials like we have for 3d. ## Solution I cloned a good part of `bevy_pbr` into `bevy_sprite/src/mesh2d`, removed lighting and pbr itself, adapted it to 2d rendering, added a `ColorMaterial`, and modified the sprite rendering to break batches around 2d meshes. ~~The PR is a bit crude; I tried to change as little as I could in both the parts copied from 3d and the current sprite rendering to make reviewing easier. In the future, I expect we could make the sprite rendering a normal 2d material, cleanly integrated with the rest.~~ _edit: see <https://github.com/bevyengine/bevy/pull/3460#issuecomment-1003605194>_ ## Remaining work - ~~don't require mesh normals~~ _out of scope_ - ~~add an example~~ _done_ - support 2d meshes & materials in the UI? - bikeshed names (I didn't think hard about naming, please check if it's fine) ## Remaining questions - ~~should we add a depth buffer to 2d now that there are 2d meshes?~~ _let's revisit that when we have an opaque render phase_ - ~~should we add MSAA support to the sprites, or remove it from the 2d meshes?~~ _I added MSAA to sprites since it's really needed for 2d meshes_ - ~~how to customize vertex attributes?~~ _#3120_ Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-01-08 01:29:08 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.mesh2d_manual]
name = "Manual Mesh 2D"
description = "Renders a custom mesh \"manually\" with \"mid-level\" renderer apis"
category = "2D Rendering"
wasm = true
Apply vertex colors to ColorMaterial and Mesh2D (#4812) # Objective - Add Vertex Color support to 2D meshes and ColorMaterial. This extends the work from #4528 (which in turn builds on the excellent tangent handling). ## Solution - Added `#ifdef` wrapped support for vertex colors in the 2D mesh shader and `ColorMaterial` shader. - Added an example, `mesh2d_vertex_color_texture` to demonstrate it in action. ![image](https://user-images.githubusercontent.com/14896751/169530930-6ae0c6be-2f69-40e3-a600-ba91d7178bc3.png) --- ## Changelog - Added optional (ifdef wrapped) vertex color support to the 2dmesh and color material systems.
2022-05-30 16:59:45 +00:00
[[example]]
name = "mesh2d_vertex_color_texture"
path = "examples/2d/mesh2d_vertex_color_texture.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Apply vertex colors to ColorMaterial and Mesh2D (#4812) # Objective - Add Vertex Color support to 2D meshes and ColorMaterial. This extends the work from #4528 (which in turn builds on the excellent tangent handling). ## Solution - Added `#ifdef` wrapped support for vertex colors in the 2D mesh shader and `ColorMaterial` shader. - Added an example, `mesh2d_vertex_color_texture` to demonstrate it in action. ![image](https://user-images.githubusercontent.com/14896751/169530930-6ae0c6be-2f69-40e3-a600-ba91d7178bc3.png) --- ## Changelog - Added optional (ifdef wrapped) vertex color support to the 2dmesh and color material systems.
2022-05-30 16:59:45 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.mesh2d_vertex_color_texture]
name = "Mesh 2D With Vertex Colors"
description = "Renders a 2d mesh with vertex color attributes"
category = "2D Rendering"
wasm = true
Add an example to draw a rectangle (#2957) # Objective Every time I come back to Bevy I face the same issue: how do I draw a rectangle again? How did that work? So I go to https://github.com/bevyengine/bevy/tree/main/examples in the hope of finding literally the simplest possible example that draws something on the screen without any dependency such as an image. I don't want to have to add some image first, I just quickly want to get something on the screen with `main.rs` alone so that I can continue building on from that point on. Such an example is particularly helpful for a quick start for smaller projects that don't even need any assets such as images (this is my case currently). Currently every single example of https://github.com/bevyengine/bevy/tree/main/examples#2d-rendering (which is the first section after hello world that beginners will look for for very minimalistic and quick examples) depends on at least an asset or is too complex. This PR solves this. It also serves as a great comparison for a beginner to realize what Bevy is really like and how different it is from what they may expect Bevy to be. For example for someone coming from [LÖVE](https://love2d.org/), they will have something like this in their head when they think of drawing a rectangle: ```lua function love.draw() love.graphics.setColor(0.25, 0.25, 0.75); love.graphics.rectangle("fill", 0, 0, 50, 50); end ``` This, of course, differs quite a lot from what you do in Bevy. I imagine there will be people that just want to see something as simple as this in comparison to have a better understanding for the amount of differences. ## Solution Add a dead simple example drawing a blue 50x50 rectangle in the center with no more and no less than needed.
2021-12-18 00:52:37 +00:00
[[example]]
Rename shapes examples for consistency (#6082) # Objective I was about to submit a PR to add these two examples to `bevy-website` and re-discovered the inconsistency. Although it's not a major issue on the website where only the filenames are shown, this would help to visually distinguish the two examples in the list because the names are very prominent. This also helps out when fuzzy-searching the codebase for these files. ## Solution Rename `shapes` to `2d_shapes`. Now the filename matches the example name, and the naming structure matches the 3d example. ## Notes @Nilirad proposed this in https://github.com/bevyengine/bevy/pull/4613#discussion_r862455631 but it had slipped away from my brain at that time.
2022-09-25 00:57:07 +00:00
name = "2d_shapes"
path = "examples/2d/2d_shapes.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add an example to draw a rectangle (#2957) # Objective Every time I come back to Bevy I face the same issue: how do I draw a rectangle again? How did that work? So I go to https://github.com/bevyengine/bevy/tree/main/examples in the hope of finding literally the simplest possible example that draws something on the screen without any dependency such as an image. I don't want to have to add some image first, I just quickly want to get something on the screen with `main.rs` alone so that I can continue building on from that point on. Such an example is particularly helpful for a quick start for smaller projects that don't even need any assets such as images (this is my case currently). Currently every single example of https://github.com/bevyengine/bevy/tree/main/examples#2d-rendering (which is the first section after hello world that beginners will look for for very minimalistic and quick examples) depends on at least an asset or is too complex. This PR solves this. It also serves as a great comparison for a beginner to realize what Bevy is really like and how different it is from what they may expect Bevy to be. For example for someone coming from [LÖVE](https://love2d.org/), they will have something like this in their head when they think of drawing a rectangle: ```lua function love.draw() love.graphics.setColor(0.25, 0.25, 0.75); love.graphics.rectangle("fill", 0, 0, 50, 50); end ``` This, of course, differs quite a lot from what you do in Bevy. I imagine there will be people that just want to see something as simple as this in comparison to have a better understanding for the amount of differences. ## Solution Add a dead simple example drawing a blue 50x50 rectangle in the center with no more and no less than needed.
2021-12-18 00:52:37 +00:00
Rename shapes examples for consistency (#6082) # Objective I was about to submit a PR to add these two examples to `bevy-website` and re-discovered the inconsistency. Although it's not a major issue on the website where only the filenames are shown, this would help to visually distinguish the two examples in the list because the names are very prominent. This also helps out when fuzzy-searching the codebase for these files. ## Solution Rename `shapes` to `2d_shapes`. Now the filename matches the example name, and the naming structure matches the 3d example. ## Notes @Nilirad proposed this in https://github.com/bevyengine/bevy/pull/4613#discussion_r862455631 but it had slipped away from my brain at that time.
2022-09-25 00:57:07 +00:00
[package.metadata.example.2d_shapes]
name = "2D Shapes"
Add `Meshable` trait and implement meshing for 2D primitives (#11431) # Objective The first part of #10569, split up from #11007. The goal is to implement meshing support for Bevy's new geometric primitives, starting with 2D primitives. 3D meshing will be added in a follow-up, and we can consider removing the old mesh shapes completely. ## Solution Add a `Meshable` trait that primitives need to implement to support meshing, as suggested by the [RFC](https://github.com/bevyengine/rfcs/blob/main/rfcs/12-primitive-shapes.md#meshing). ```rust /// A trait for shapes that can be turned into a [`Mesh`]. pub trait Meshable { /// The output of [`Self::mesh`]. This can either be a [`Mesh`] /// or a builder used for creating a [`Mesh`]. type Output; /// Creates a [`Mesh`] for a shape. fn mesh(&self) -> Self::Output; } ``` This PR implements it for the following primitives: - `Circle` - `Ellipse` - `Rectangle` - `RegularPolygon` - `Triangle2d` The `mesh` method typically returns a builder-like struct such as `CircleMeshBuilder`. This is needed to support shape-specific configuration for things like mesh resolution or UV configuration: ```rust meshes.add(Circle { radius: 0.5 }.mesh().resolution(64)); ``` Note that if no configuration is needed, you can even skip calling `mesh` because `From<MyPrimitive>` is implemented for `Mesh`: ```rust meshes.add(Circle { radius: 0.5 }); ``` I also updated the `2d_shapes` example to use primitives, and tweaked the colors to have better contrast against the dark background. Before: ![Old 2D shapes](https://github.com/bevyengine/bevy/assets/57632562/f1d8c2d5-55be-495f-8ed4-5890154b81ca) After: ![New 2D shapes](https://github.com/bevyengine/bevy/assets/57632562/f166c013-34b8-4752-800a-5517b284d978) Here you can see the UVs and different facing directions: (taken from #11007, so excuse the 3D primitives at the bottom left) ![UVs and facing directions](https://github.com/bevyengine/bevy/assets/57632562/eaf0be4e-187d-4b6d-8fb8-c996ba295a8a) --- ## Changelog - Added `bevy_render::mesh::primitives` module - Added `Meshable` trait and implemented it for: - `Circle` - `Ellipse` - `Rectangle` - `RegularPolygon` - `Triangle2d` - Implemented `Default` and `Copy` for several 2D primitives - Updated `2d_shapes` example to use primitives - Tweaked colors in `2d_shapes` example to have better contrast against the (new-ish) dark background --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2024-01-29 16:47:47 +00:00
description = "Renders simple 2D primitive shapes like circles and polygons"
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
category = "2D Rendering"
wasm = true
Add support for custom glTF vertex attributes. (#5370) # Objective The objective is to be able to load data from "application-specific" (see glTF spec 3.7.2.1.) vertex attribute semantics from glTF files into Bevy meshes. ## Solution Rather than probe the glTF for the specific attributes supported by Bevy, this PR changes the loader to iterate through all the attributes and map them onto `MeshVertexAttribute`s. This mapping includes all the previously supported attributes, plus it is now possible to add mappings using the `add_custom_vertex_attribute()` method on `GltfPlugin`. ## Changelog - Add support for loading custom vertex attributes from glTF files. - Add the `custom_gltf_vertex_attribute.rs` example to illustrate loading custom vertex attributes. ## Migration Guide - If you were instantiating `GltfPlugin` using the unit-like struct syntax, you must instead use `GltfPlugin::default()` as the type is no longer unit-like.
2023-04-24 14:20:13 +00:00
[[example]]
name = "custom_gltf_vertex_attribute"
path = "examples/2d/custom_gltf_vertex_attribute.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add support for custom glTF vertex attributes. (#5370) # Objective The objective is to be able to load data from "application-specific" (see glTF spec 3.7.2.1.) vertex attribute semantics from glTF files into Bevy meshes. ## Solution Rather than probe the glTF for the specific attributes supported by Bevy, this PR changes the loader to iterate through all the attributes and map them onto `MeshVertexAttribute`s. This mapping includes all the previously supported attributes, plus it is now possible to add mappings using the `add_custom_vertex_attribute()` method on `GltfPlugin`. ## Changelog - Add support for loading custom vertex attributes from glTF files. - Add the `custom_gltf_vertex_attribute.rs` example to illustrate loading custom vertex attributes. ## Migration Guide - If you were instantiating `GltfPlugin` using the unit-like struct syntax, you must instead use `GltfPlugin::default()` as the type is no longer unit-like.
2023-04-24 14:20:13 +00:00
[package.metadata.example.custom_gltf_vertex_attribute]
name = "Custom glTF vertex attribute 2D"
description = "Renders a glTF mesh in 2D with a custom vertex attribute"
category = "2D Rendering"
wasm = true
Add `Image` methods for easy access to a pixel's color (#10392) # Objective If you want to draw / generate images from the CPU, such as: - to create procedurally-generated assets - for games whose artstyle is best implemented by poking pixels directly from the CPU, instead of using shaders It is currently very unergonomic to do in Bevy, because you have to deal with the raw bytes inside `image.data`, take care of the pixel format, etc. ## Solution This PR adds some helper methods to `Image` for pixel manipulation. These methods allow you to use Bevy's user-friendly `Color` struct to read and write the colors of pixels, at arbitrary coordinates (specified as `UVec3` to support any texture dimension). They handle encoding/decoding to the `Image`s `TextureFormat`, incl. any sRGB conversion. While we are at it, also add methods to help with direct access to the raw bytes. It is now easy to compute the offset where the bytes of a specific pixel coordinate are found, or to just get a Rust slice to access them. Caveat: `Color` roundtrips are obviously going to be lossy for non-float `TextureFormat`s. Using `set_color_at` followed by `get_color_at` will return a different value, due to the data conversions involved (such as `f32` -> `u8` -> `f32` for the common `Rgba8UnormSrgb` texture format). Be careful when comparing colors (such as checking for a color you wrote before)! Also adding a new example: `cpu_draw` (under `2d`), to showcase these new APIs. --- ## Changelog ### Added - `Image` APIs for easy access to the colors of specific pixels. --------- Co-authored-by: Pascal Hertleif <killercup@gmail.com> Co-authored-by: François <mockersf@gmail.com> Co-authored-by: ltdk <usr@ltdk.xyz>
2024-10-07 14:38:41 +00:00
[[example]]
name = "cpu_draw"
path = "examples/2d/cpu_draw.rs"
doc-scrape-examples = true
[package.metadata.example.cpu_draw]
name = "CPU Drawing"
description = "Manually read/write the pixels of a texture"
category = "2D Rendering"
wasm = true
sprites
2020-05-04 08:22:25 +00:00
[[example]]
name = "sprite"
path = "examples/2d/sprite.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
sprites
2020-05-04 08:22:25 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.sprite]
name = "Sprite"
description = "Renders a sprite"
category = "2D Rendering"
wasm = true
new example: sprite animation in response to an event (#12996) # Objective - animating a sprite in response to an event is a [common beginner problem](https://www.reddit.com/r/bevy/comments/13xx4v7/sprite_animation_in_bevy/) ## Solution - provide a simple example to show how to animate a sprite in response to an event --------- Co-authored-by: François Mockers <francois.mockers@vleue.com>
2024-04-23 21:44:03 +00:00
[[example]]
name = "sprite_animation"
path = "examples/2d/sprite_animation.rs"
doc-scrape-examples = true
[package.metadata.example.sprite_animation]
name = "Sprite Animation"
description = "Animates a sprite in response to an event"
category = "2D Rendering"
wasm = true
Add Sprite Flipping (#1407) OK, here's my attempt at sprite flipping. There are a couple of points that I need review/help on, but I think the UX is about ideal: ```rust .spawn(SpriteBundle { material: materials.add(texture_handle.into()), sprite: Sprite { // Flip the sprite along the x axis flip: SpriteFlip { x: true, y: false }, ..Default::default() }, ..Default::default() }); ``` Now for the issues. The big issue is that for some reason, when flipping the UVs on the sprite, there is a light "bleeding" or whatever you call it where the UV tries to sample past the texture boundry and ends up clipping. This is only noticed when resizing the window, though. You can see a screenshot below. ![image](https://user-images.githubusercontent.com/25393315/107098172-397aaa00-67d4-11eb-8e02-c90c820cd70e.png) I am quite baffled why the texture sampling is overrunning like it is and could use some guidance if anybody knows what might be wrong. The other issue, which I just worked around, is that I had to remove the `#[render_resources(from_self)]` annotation from the Spritesheet because the `SpriteFlip` render resource wasn't being picked up properly in the shader when using it. I'm not sure what the cause of that was, but by removing the annotation and re-organizing the shader inputs accordingly the problem was fixed. I'm not sure if this is the most efficient way to do this or if there is a better way, but I wanted to try it out if only for the learning experience. Let me know what you think!
2021-03-03 19:26:45 +00:00
[[example]]
name = "sprite_flipping"
path = "examples/2d/sprite_flipping.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add Sprite Flipping (#1407) OK, here's my attempt at sprite flipping. There are a couple of points that I need review/help on, but I think the UX is about ideal: ```rust .spawn(SpriteBundle { material: materials.add(texture_handle.into()), sprite: Sprite { // Flip the sprite along the x axis flip: SpriteFlip { x: true, y: false }, ..Default::default() }, ..Default::default() }); ``` Now for the issues. The big issue is that for some reason, when flipping the UVs on the sprite, there is a light "bleeding" or whatever you call it where the UV tries to sample past the texture boundry and ends up clipping. This is only noticed when resizing the window, though. You can see a screenshot below. ![image](https://user-images.githubusercontent.com/25393315/107098172-397aaa00-67d4-11eb-8e02-c90c820cd70e.png) I am quite baffled why the texture sampling is overrunning like it is and could use some guidance if anybody knows what might be wrong. The other issue, which I just worked around, is that I had to remove the `#[render_resources(from_self)]` annotation from the Spritesheet because the `SpriteFlip` render resource wasn't being picked up properly in the shader when using it. I'm not sure what the cause of that was, but by removing the annotation and re-organizing the shader inputs accordingly the problem was fixed. I'm not sure if this is the most efficient way to do this or if there is a better way, but I wanted to try it out if only for the learning experience. Let me know what you think!
2021-03-03 19:26:45 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.sprite_flipping]
name = "Sprite Flipping"
description = "Renders a sprite flipped along an axis"
category = "2D Rendering"
wasm = true
bytes: AsBytes trait, remove zerocopy, remove glam fork
2020-06-02 02:23:11 +00:00
[[example]]
name = "sprite_sheet"
path = "examples/2d/sprite_sheet.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
bytes: AsBytes trait, remove zerocopy, remove glam fork
2020-06-02 02:23:11 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.sprite_sheet]
name = "Sprite Sheet"
description = "Renders an animated sprite"
category = "2D Rendering"
wasm = true
Sprite slicing and tiling (#10588) > Replaces #5213 # Objective Implement sprite tiling and [9 slice scaling](https://en.wikipedia.org/wiki/9-slice_scaling) for `bevy_sprite`. Allowing slice scaling and texture tiling. Basic scaling vs 9 slice scaling: ![Traditional_scaling_vs_9-slice_scaling](https://user-images.githubusercontent.com/26703856/177335801-27f6fa27-c569-4ce6-b0e6-4f54e8f4e80a.svg) Slicing example: <img width="481" alt="Screenshot 2022-07-05 at 15 05 49" src="https://user-images.githubusercontent.com/26703856/177336112-9e961af0-c0af-4197-aec9-430c1170a79d.png"> Tiling example: <img width="1329" alt="Screenshot 2023-11-16 at 13 53 32" src="https://github.com/bevyengine/bevy/assets/26703856/14db39b7-d9e0-4bc3-ba0e-b1f2db39ae8f"> # Solution - `SpriteBundlue` now has a `scale_mode` component storing a `SpriteScaleMode` enum with three variants: - `Stretched` (default) - `Tiled` to have sprites tile horizontally and/or vertically - `Sliced` allowing 9 slicing the texture and optionally tile some sections with a `Textureslicer`. - `bevy_sprite` has two extra systems to compute a `ComputedTextureSlices` if necessary,: - One system react to changes on `Sprite`, `Handle<Image>` or `SpriteScaleMode` - The other listens to `AssetEvent<Image>` to compute slices on sprites when the texture is ready or changed - I updated the `bevy_sprite` extraction stage to extract potentially multiple textures instead of one, depending on the presence of `ComputedTextureSlices` - I added two examples showcasing the slicing and tiling feature. The addition of `ComputedTextureSlices` as a cache is to avoid querying the image data, to retrieve its dimensions, every frame in a extract or prepare stage. Also it reacts to changes so we can have stuff like this (tiling example): https://github.com/bevyengine/bevy/assets/26703856/a349a9f3-33c3-471f-8ef4-a0e5dfce3b01 # Related - [ ] Once #5103 or #10099 is merged I can enable tiling and slicing for texture sheets as ui # To discuss There is an other option, to consider slice/tiling as part of the asset, using the new asset preprocessing but I have no clue on how to do it. Also, instead of retrieving the Image dimensions, we could use the same system as the sprite sheet and have the user give the image dimensions directly (grid). But I think it's less user friendly --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: ickshonpe <david.curthoys@googlemail.com> Co-authored-by: Alice Cecile <alice.i.cecil@gmail.com>
2024-01-15 15:40:06 +00:00
[[example]]
name = "sprite_tile"
path = "examples/2d/sprite_tile.rs"
Fix some doc warnings (#12961) # Objective - Fix some doc warnings - Add doc-scrape-examples to all examples Moved from #12692 I run `cargo +nightly doc --workspace --all-features --no-deps -Zunstable-options -Zrustdoc-scrape-examples` <details> ``` warning: public documentation for `GzAssetLoaderError` links to private item `GzAssetLoader` --> examples/asset/asset_decompression.rs:24:47 | 24 | /// Possible errors that can be produced by [`GzAssetLoader`] | ^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: `bevy` (example "asset_decompression") generated 1 warning warning: unresolved link to `shape::Quad` --> examples/2d/mesh2d.rs:3:15 | 3 | //! [`Quad`]: shape::Quad | ^^^^^^^^^^^ no item named `shape` in scope | = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "mesh2d") generated 1 warning warning: unresolved link to `WorldQuery` --> examples/ecs/custom_query_param.rs:1:49 | 1 | //! This example illustrates the usage of the [`WorldQuery`] derive macro, which allows | ^^^^^^^^^^ no item named `WorldQuery` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "custom_query_param") generated 1 warning warning: unresolved link to `shape::Quad` --> examples/2d/mesh2d_vertex_color_texture.rs:4:15 | 4 | //! [`Quad`]: shape::Quad | ^^^^^^^^^^^ no item named `shape` in scope | = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "mesh2d_vertex_color_texture") generated 1 warning warning: public documentation for `TextPlugin` links to private item `CoolText` --> examples/asset/processing/asset_processing.rs:48:9 | 48 | /// * [`CoolText`]: a custom RON text format that supports dependencies and embedded dependencies | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: public documentation for `TextPlugin` links to private item `Text` --> examples/asset/processing/asset_processing.rs:49:9 | 49 | /// * [`Text`]: a "normal" plain text file | ^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: public documentation for `TextPlugin` links to private item `CoolText` --> examples/asset/processing/asset_processing.rs:51:57 | 51 | /// It also defines an asset processor that will load [`CoolText`], resolve embedded dependenc... | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: `bevy` (example "asset_processing") generated 3 warnings warning: public documentation for `CustomAssetLoaderError` links to private item `CustomAssetLoader` --> examples/asset/custom_asset.rs:20:47 | 20 | /// Possible errors that can be produced by [`CustomAssetLoader`] | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: public documentation for `BlobAssetLoaderError` links to private item `CustomAssetLoader` --> examples/asset/custom_asset.rs:61:47 | 61 | /// Possible errors that can be produced by [`CustomAssetLoader`] | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` ``` ``` warning: `bevy` (example "mesh2d") generated 1 warning warning: public documentation for `log_layers_ecs` links to private item `update_subscriber` --> examples/app/log_layers_ecs.rs:6:18 | 6 | //! Inside the [`update_subscriber`] function we will create a [`mpsc::Sender`] and a [`mpsc::R... | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: unresolved link to `AdvancedLayer` --> examples/app/log_layers_ecs.rs:7:72 | 7 | ... will go into the [`AdvancedLayer`] and the [`Receiver`](mpsc::Receiver) will | ^^^^^^^^^^^^^ no item named `AdvancedLayer` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: unresolved link to `LogEvents` --> examples/app/log_layers_ecs.rs:8:42 | 8 | //! go into a non-send resource called [`LogEvents`] (It has to be non-send because [`Receiver`... | ^^^^^^^^^ no item named `LogEvents` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` warning: public documentation for `log_layers_ecs` links to private item `transfer_log_events` --> examples/app/log_layers_ecs.rs:9:30 | 9 | //! From there we will use [`transfer_log_events`] to transfer log events from [`LogEvents`] to... | ^^^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: unresolved link to `LogEvents` --> examples/app/log_layers_ecs.rs:9:82 | 9 | ...nsfer log events from [`LogEvents`] to an ECS event called [`LogEvent`]. | ^^^^^^^^^ no item named `LogEvents` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` warning: public documentation for `log_layers_ecs` links to private item `LogEvent` --> examples/app/log_layers_ecs.rs:9:119 | 9 | ...nts`] to an ECS event called [`LogEvent`]. | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: public documentation for `log_layers_ecs` links to private item `LogEvent` --> examples/app/log_layers_ecs.rs:11:49 | 11 | //! Finally, after all that we can access the [`LogEvent`] event from our systems and use it. | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` ``` <details/>
2024-04-14 15:23:44 +00:00
doc-scrape-examples = true
Sprite slicing and tiling (#10588) > Replaces #5213 # Objective Implement sprite tiling and [9 slice scaling](https://en.wikipedia.org/wiki/9-slice_scaling) for `bevy_sprite`. Allowing slice scaling and texture tiling. Basic scaling vs 9 slice scaling: ![Traditional_scaling_vs_9-slice_scaling](https://user-images.githubusercontent.com/26703856/177335801-27f6fa27-c569-4ce6-b0e6-4f54e8f4e80a.svg) Slicing example: <img width="481" alt="Screenshot 2022-07-05 at 15 05 49" src="https://user-images.githubusercontent.com/26703856/177336112-9e961af0-c0af-4197-aec9-430c1170a79d.png"> Tiling example: <img width="1329" alt="Screenshot 2023-11-16 at 13 53 32" src="https://github.com/bevyengine/bevy/assets/26703856/14db39b7-d9e0-4bc3-ba0e-b1f2db39ae8f"> # Solution - `SpriteBundlue` now has a `scale_mode` component storing a `SpriteScaleMode` enum with three variants: - `Stretched` (default) - `Tiled` to have sprites tile horizontally and/or vertically - `Sliced` allowing 9 slicing the texture and optionally tile some sections with a `Textureslicer`. - `bevy_sprite` has two extra systems to compute a `ComputedTextureSlices` if necessary,: - One system react to changes on `Sprite`, `Handle<Image>` or `SpriteScaleMode` - The other listens to `AssetEvent<Image>` to compute slices on sprites when the texture is ready or changed - I updated the `bevy_sprite` extraction stage to extract potentially multiple textures instead of one, depending on the presence of `ComputedTextureSlices` - I added two examples showcasing the slicing and tiling feature. The addition of `ComputedTextureSlices` as a cache is to avoid querying the image data, to retrieve its dimensions, every frame in a extract or prepare stage. Also it reacts to changes so we can have stuff like this (tiling example): https://github.com/bevyengine/bevy/assets/26703856/a349a9f3-33c3-471f-8ef4-a0e5dfce3b01 # Related - [ ] Once #5103 or #10099 is merged I can enable tiling and slicing for texture sheets as ui # To discuss There is an other option, to consider slice/tiling as part of the asset, using the new asset preprocessing but I have no clue on how to do it. Also, instead of retrieving the Image dimensions, we could use the same system as the sprite sheet and have the user give the image dimensions directly (grid). But I think it's less user friendly --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: ickshonpe <david.curthoys@googlemail.com> Co-authored-by: Alice Cecile <alice.i.cecil@gmail.com>
2024-01-15 15:40:06 +00:00
[package.metadata.example.sprite_tile]
name = "Sprite Tile"
description = "Renders a sprite tiled in a grid"
category = "2D Rendering"
wasm = true
[[example]]
name = "sprite_slice"
path = "examples/2d/sprite_slice.rs"
Fix some doc warnings (#12961) # Objective - Fix some doc warnings - Add doc-scrape-examples to all examples Moved from #12692 I run `cargo +nightly doc --workspace --all-features --no-deps -Zunstable-options -Zrustdoc-scrape-examples` <details> ``` warning: public documentation for `GzAssetLoaderError` links to private item `GzAssetLoader` --> examples/asset/asset_decompression.rs:24:47 | 24 | /// Possible errors that can be produced by [`GzAssetLoader`] | ^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: `bevy` (example "asset_decompression") generated 1 warning warning: unresolved link to `shape::Quad` --> examples/2d/mesh2d.rs:3:15 | 3 | //! [`Quad`]: shape::Quad | ^^^^^^^^^^^ no item named `shape` in scope | = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "mesh2d") generated 1 warning warning: unresolved link to `WorldQuery` --> examples/ecs/custom_query_param.rs:1:49 | 1 | //! This example illustrates the usage of the [`WorldQuery`] derive macro, which allows | ^^^^^^^^^^ no item named `WorldQuery` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "custom_query_param") generated 1 warning warning: unresolved link to `shape::Quad` --> examples/2d/mesh2d_vertex_color_texture.rs:4:15 | 4 | //! [`Quad`]: shape::Quad | ^^^^^^^^^^^ no item named `shape` in scope | = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "mesh2d_vertex_color_texture") generated 1 warning warning: public documentation for `TextPlugin` links to private item `CoolText` --> examples/asset/processing/asset_processing.rs:48:9 | 48 | /// * [`CoolText`]: a custom RON text format that supports dependencies and embedded dependencies | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: public documentation for `TextPlugin` links to private item `Text` --> examples/asset/processing/asset_processing.rs:49:9 | 49 | /// * [`Text`]: a "normal" plain text file | ^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: public documentation for `TextPlugin` links to private item `CoolText` --> examples/asset/processing/asset_processing.rs:51:57 | 51 | /// It also defines an asset processor that will load [`CoolText`], resolve embedded dependenc... | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: `bevy` (example "asset_processing") generated 3 warnings warning: public documentation for `CustomAssetLoaderError` links to private item `CustomAssetLoader` --> examples/asset/custom_asset.rs:20:47 | 20 | /// Possible errors that can be produced by [`CustomAssetLoader`] | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: public documentation for `BlobAssetLoaderError` links to private item `CustomAssetLoader` --> examples/asset/custom_asset.rs:61:47 | 61 | /// Possible errors that can be produced by [`CustomAssetLoader`] | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` ``` ``` warning: `bevy` (example "mesh2d") generated 1 warning warning: public documentation for `log_layers_ecs` links to private item `update_subscriber` --> examples/app/log_layers_ecs.rs:6:18 | 6 | //! Inside the [`update_subscriber`] function we will create a [`mpsc::Sender`] and a [`mpsc::R... | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: unresolved link to `AdvancedLayer` --> examples/app/log_layers_ecs.rs:7:72 | 7 | ... will go into the [`AdvancedLayer`] and the [`Receiver`](mpsc::Receiver) will | ^^^^^^^^^^^^^ no item named `AdvancedLayer` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: unresolved link to `LogEvents` --> examples/app/log_layers_ecs.rs:8:42 | 8 | //! go into a non-send resource called [`LogEvents`] (It has to be non-send because [`Receiver`... | ^^^^^^^^^ no item named `LogEvents` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` warning: public documentation for `log_layers_ecs` links to private item `transfer_log_events` --> examples/app/log_layers_ecs.rs:9:30 | 9 | //! From there we will use [`transfer_log_events`] to transfer log events from [`LogEvents`] to... | ^^^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: unresolved link to `LogEvents` --> examples/app/log_layers_ecs.rs:9:82 | 9 | ...nsfer log events from [`LogEvents`] to an ECS event called [`LogEvent`]. | ^^^^^^^^^ no item named `LogEvents` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` warning: public documentation for `log_layers_ecs` links to private item `LogEvent` --> examples/app/log_layers_ecs.rs:9:119 | 9 | ...nts`] to an ECS event called [`LogEvent`]. | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: public documentation for `log_layers_ecs` links to private item `LogEvent` --> examples/app/log_layers_ecs.rs:11:49 | 11 | //! Finally, after all that we can access the [`LogEvent`] event from our systems and use it. | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` ``` <details/>
2024-04-14 15:23:44 +00:00
doc-scrape-examples = true
Sprite slicing and tiling (#10588) > Replaces #5213 # Objective Implement sprite tiling and [9 slice scaling](https://en.wikipedia.org/wiki/9-slice_scaling) for `bevy_sprite`. Allowing slice scaling and texture tiling. Basic scaling vs 9 slice scaling: ![Traditional_scaling_vs_9-slice_scaling](https://user-images.githubusercontent.com/26703856/177335801-27f6fa27-c569-4ce6-b0e6-4f54e8f4e80a.svg) Slicing example: <img width="481" alt="Screenshot 2022-07-05 at 15 05 49" src="https://user-images.githubusercontent.com/26703856/177336112-9e961af0-c0af-4197-aec9-430c1170a79d.png"> Tiling example: <img width="1329" alt="Screenshot 2023-11-16 at 13 53 32" src="https://github.com/bevyengine/bevy/assets/26703856/14db39b7-d9e0-4bc3-ba0e-b1f2db39ae8f"> # Solution - `SpriteBundlue` now has a `scale_mode` component storing a `SpriteScaleMode` enum with three variants: - `Stretched` (default) - `Tiled` to have sprites tile horizontally and/or vertically - `Sliced` allowing 9 slicing the texture and optionally tile some sections with a `Textureslicer`. - `bevy_sprite` has two extra systems to compute a `ComputedTextureSlices` if necessary,: - One system react to changes on `Sprite`, `Handle<Image>` or `SpriteScaleMode` - The other listens to `AssetEvent<Image>` to compute slices on sprites when the texture is ready or changed - I updated the `bevy_sprite` extraction stage to extract potentially multiple textures instead of one, depending on the presence of `ComputedTextureSlices` - I added two examples showcasing the slicing and tiling feature. The addition of `ComputedTextureSlices` as a cache is to avoid querying the image data, to retrieve its dimensions, every frame in a extract or prepare stage. Also it reacts to changes so we can have stuff like this (tiling example): https://github.com/bevyengine/bevy/assets/26703856/a349a9f3-33c3-471f-8ef4-a0e5dfce3b01 # Related - [ ] Once #5103 or #10099 is merged I can enable tiling and slicing for texture sheets as ui # To discuss There is an other option, to consider slice/tiling as part of the asset, using the new asset preprocessing but I have no clue on how to do it. Also, instead of retrieving the Image dimensions, we could use the same system as the sprite sheet and have the user give the image dimensions directly (grid). But I think it's less user friendly --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: ickshonpe <david.curthoys@googlemail.com> Co-authored-by: Alice Cecile <alice.i.cecil@gmail.com>
2024-01-15 15:40:06 +00:00
[package.metadata.example.sprite_slice]
name = "Sprite Slice"
description = "Showcases slicing sprites into sections that can be scaled independently via the 9-patch technique"
category = "2D Rendering"
wasm = true
Render text in 2D scenes (#1122) Render text in 2D scenes
2020-12-27 19:19:03 +00:00
[[example]]
name = "text2d"
path = "examples/2d/text2d.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Render text in 2D scenes (#1122) Render text in 2D scenes
2020-12-27 19:19:03 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.text2d]
name = "Text 2D"
description = "Generates text in 2D"
category = "2D Rendering"
wasm = true
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
[[example]]
name = "texture_atlas"
path = "examples/2d/texture_atlas.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.texture_atlas]
name = "Texture Atlas"
description = "Generates a texture atlas (sprite sheet) from individual sprites"
category = "2D Rendering"
Disable asset_loading and texture_atlas examples when building for wasm / WebGPU (#8683) # Objective Remove the asset_loading and texture_atlas on the WebGPU examples page as they do not function properly. Both examples use folder loading that is not supported in a browser context and currently fail with the follow error: ``` panicked at 'called `Result::unwrap()` on an `Err` value: AssetFolderNotADirectory("textures/rpg")', examples/2d/texture_atlas.rs:31:75 ``` ## Solution Disable these examples when building for WebGPU / wasm.
2023-05-25 21:57:04 +00:00
wasm = false
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
Add transparency examples (#3695) Adds examples demonstrating transparency for 2d, 3d and UI. Fixes #3215.
2022-06-06 17:52:09 +00:00
[[example]]
name = "transparency_2d"
path = "examples/2d/transparency_2d.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add transparency examples (#3695) Adds examples demonstrating transparency for 2d, 3d and UI. Fixes #3215.
2022-06-06 17:52:09 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.transparency_2d]
name = "Transparency in 2D"
description = "Demonstrates transparency in 2d"
category = "2D Rendering"
wasm = true
Add 2d opaque phase with depth buffer (#13069) This PR is based on top of #12982 # Objective - Mesh2d currently only has an alpha blended phase. Most sprites don't need transparency though. - For some 2d games it can be useful to have a 2d depth buffer ## Solution - Add an opaque phase to render Mesh2d that don't need transparency - This phase currently uses the `SortedRenderPhase` to make it easier to implement based on the already existing transparent phase. A follow up PR will switch this to `BinnedRenderPhase`. - Add a 2d depth buffer - Use that depth buffer in the transparent phase to make sure that sprites and transparent mesh2d are displayed correctly ## Testing I added the mesh2d_transforms example that layers many opaque and transparent mesh2d to make sure they all get displayed correctly. I also confirmed it works with sprites by modifying that example locally. --- ## Changelog - Added `AlphaMode2d` - Added `Opaque2d` render phase - Camera2d now have a `ViewDepthTexture` component ## Migration Guide - `ColorMaterial` now contains `AlphaMode2d`. To keep previous behaviour, use `AlphaMode::BLEND`. If you know your sprite is opaque, use `AlphaMode::OPAQUE` ## Follow up PRs - See tracking issue: #13265 --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Christopher Biscardi <chris@christopherbiscardi.com>
2024-08-07 00:22:09 +00:00
[[example]]
name = "mesh2d_alpha_mode"
path = "examples/2d/mesh2d_alpha_mode.rs"
doc-scrape-examples = true
[package.metadata.example.mesh2d_alpha_mode]
name = "Mesh2d Alpha Mode"
description = "Used to test alpha modes with mesh2d"
category = "2D Rendering"
wasm = true
Add pixelated Bevy to assets and an example (#6408) # Objective Fixes #2279 ## Solution Added pixelated Bevy to assets folder and used in a `pixel_perfect` example.
2022-11-14 22:15:46 +00:00
[[example]]
Add example for pixel-perfect grid snapping in 2D (#8112) # Objective Provide an example of how to achieve pixel-perfect "grid snapping" in 2D via rendering to a texture. This is a common use case in retro pixel art game development. ## Solution Render sprites to a canvas via a Camera, then use another (scaled up) Camera to render the resulting canvas to the screen. This example is based on the `3d/render_to_texture.rs` example. Furthermore, this example demonstrates mixing retro-style graphics with high-resolution graphics, as well as pixel-snapped rendering of a `MaterialMesh2dBundle`.
2023-12-26 17:15:50 +00:00
name = "pixel_grid_snap"
path = "examples/2d/pixel_grid_snap.rs"
Fix some doc warnings (#12961) # Objective - Fix some doc warnings - Add doc-scrape-examples to all examples Moved from #12692 I run `cargo +nightly doc --workspace --all-features --no-deps -Zunstable-options -Zrustdoc-scrape-examples` <details> ``` warning: public documentation for `GzAssetLoaderError` links to private item `GzAssetLoader` --> examples/asset/asset_decompression.rs:24:47 | 24 | /// Possible errors that can be produced by [`GzAssetLoader`] | ^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: `bevy` (example "asset_decompression") generated 1 warning warning: unresolved link to `shape::Quad` --> examples/2d/mesh2d.rs:3:15 | 3 | //! [`Quad`]: shape::Quad | ^^^^^^^^^^^ no item named `shape` in scope | = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "mesh2d") generated 1 warning warning: unresolved link to `WorldQuery` --> examples/ecs/custom_query_param.rs:1:49 | 1 | //! This example illustrates the usage of the [`WorldQuery`] derive macro, which allows | ^^^^^^^^^^ no item named `WorldQuery` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "custom_query_param") generated 1 warning warning: unresolved link to `shape::Quad` --> examples/2d/mesh2d_vertex_color_texture.rs:4:15 | 4 | //! [`Quad`]: shape::Quad | ^^^^^^^^^^^ no item named `shape` in scope | = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "mesh2d_vertex_color_texture") generated 1 warning warning: public documentation for `TextPlugin` links to private item `CoolText` --> examples/asset/processing/asset_processing.rs:48:9 | 48 | /// * [`CoolText`]: a custom RON text format that supports dependencies and embedded dependencies | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: public documentation for `TextPlugin` links to private item `Text` --> examples/asset/processing/asset_processing.rs:49:9 | 49 | /// * [`Text`]: a "normal" plain text file | ^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: public documentation for `TextPlugin` links to private item `CoolText` --> examples/asset/processing/asset_processing.rs:51:57 | 51 | /// It also defines an asset processor that will load [`CoolText`], resolve embedded dependenc... | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: `bevy` (example "asset_processing") generated 3 warnings warning: public documentation for `CustomAssetLoaderError` links to private item `CustomAssetLoader` --> examples/asset/custom_asset.rs:20:47 | 20 | /// Possible errors that can be produced by [`CustomAssetLoader`] | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: public documentation for `BlobAssetLoaderError` links to private item `CustomAssetLoader` --> examples/asset/custom_asset.rs:61:47 | 61 | /// Possible errors that can be produced by [`CustomAssetLoader`] | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` ``` ``` warning: `bevy` (example "mesh2d") generated 1 warning warning: public documentation for `log_layers_ecs` links to private item `update_subscriber` --> examples/app/log_layers_ecs.rs:6:18 | 6 | //! Inside the [`update_subscriber`] function we will create a [`mpsc::Sender`] and a [`mpsc::R... | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: unresolved link to `AdvancedLayer` --> examples/app/log_layers_ecs.rs:7:72 | 7 | ... will go into the [`AdvancedLayer`] and the [`Receiver`](mpsc::Receiver) will | ^^^^^^^^^^^^^ no item named `AdvancedLayer` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: unresolved link to `LogEvents` --> examples/app/log_layers_ecs.rs:8:42 | 8 | //! go into a non-send resource called [`LogEvents`] (It has to be non-send because [`Receiver`... | ^^^^^^^^^ no item named `LogEvents` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` warning: public documentation for `log_layers_ecs` links to private item `transfer_log_events` --> examples/app/log_layers_ecs.rs:9:30 | 9 | //! From there we will use [`transfer_log_events`] to transfer log events from [`LogEvents`] to... | ^^^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: unresolved link to `LogEvents` --> examples/app/log_layers_ecs.rs:9:82 | 9 | ...nsfer log events from [`LogEvents`] to an ECS event called [`LogEvent`]. | ^^^^^^^^^ no item named `LogEvents` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` warning: public documentation for `log_layers_ecs` links to private item `LogEvent` --> examples/app/log_layers_ecs.rs:9:119 | 9 | ...nts`] to an ECS event called [`LogEvent`]. | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: public documentation for `log_layers_ecs` links to private item `LogEvent` --> examples/app/log_layers_ecs.rs:11:49 | 11 | //! Finally, after all that we can access the [`LogEvent`] event from our systems and use it. | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` ``` <details/>
2024-04-14 15:23:44 +00:00
doc-scrape-examples = true
Add pixelated Bevy to assets and an example (#6408) # Objective Fixes #2279 ## Solution Added pixelated Bevy to assets folder and used in a `pixel_perfect` example.
2022-11-14 22:15:46 +00:00
Add example for pixel-perfect grid snapping in 2D (#8112) # Objective Provide an example of how to achieve pixel-perfect "grid snapping" in 2D via rendering to a texture. This is a common use case in retro pixel art game development. ## Solution Render sprites to a canvas via a Camera, then use another (scaled up) Camera to render the resulting canvas to the screen. This example is based on the `3d/render_to_texture.rs` example. Furthermore, this example demonstrates mixing retro-style graphics with high-resolution graphics, as well as pixel-snapped rendering of a `MaterialMesh2dBundle`.
2023-12-26 17:15:50 +00:00
[package.metadata.example.pixel_grid_snap]
name = "Pixel Grid Snapping"
description = "Shows how to create graphics that snap to the pixel grid by rendering to a texture in 2D"
Add pixelated Bevy to assets and an example (#6408) # Objective Fixes #2279 ## Solution Added pixelated Bevy to assets folder and used in a `pixel_perfect` example.
2022-11-14 22:15:46 +00:00
category = "2D Rendering"
wasm = true
Add example for bounding volumes and intersection tests (#11666) # Objective - Create an example for bounding volumes and intersection tests ## Solution - Add an example with a few bounding volumes, created from primitives - Allow the user to cycle trough the different intersection tests
2024-02-03 17:11:01 +00:00
[[example]]
name = "bounding_2d"
path = "examples/2d/bounding_2d.rs"
doc-scrape-examples = true
[package.metadata.example.bounding_2d]
name = "2D Bounding Volume Intersections"
description = "Showcases bounding volumes and intersection tests"
category = "2D Rendering"
wasm = true
Support wireframes for 2D meshes (#12135) # Objective Wireframes are currently supported for 3D meshes using the `WireframePlugin` in `bevy_pbr`. This PR adds the same functionality for 2D meshes. Closes #5881. ## Solution Since there's no easy way to share material implementations between 2D, 3D, and UI, this is mostly a straight copy and rename from the original plugin into `bevy_sprite`. <img width="1392" alt="image" src="https://github.com/bevyengine/bevy/assets/3961616/7aca156f-448a-4c7e-89b8-0a72c5919769"> --- ## Changelog - Added `Wireframe2dPlugin` and related types to support 2D wireframes. - Added an example to demonstrate how to use 2D wireframes --------- Co-authored-by: IceSentry <IceSentry@users.noreply.github.com>
2024-03-29 18:34:04 +00:00
[[example]]
name = "wireframe_2d"
path = "examples/2d/wireframe_2d.rs"
doc-scrape-examples = true
[package.metadata.example.wireframe_2d]
name = "2D Wireframe"
description = "Showcases wireframes for 2d meshes"
category = "2D Rendering"
wasm = false
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
# 3D Rendering
add scene instance entity iteration (#1058) add scene instance entity iteration
2021-01-01 20:58:49 +00:00
[[example]]
name = "3d_scene"
path = "examples/3d/3d_scene.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
add scene instance entity iteration (#1058) add scene instance entity iteration
2021-01-01 20:58:49 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.3d_scene]
name = "3D Scene"
description = "Simple 3D scene with basic shapes and lighting"
category = "3D Rendering"
wasm = true
Camera Driven Viewports (#4898) # Objective Users should be able to render cameras to specific areas of a render target, which enables scenarios like split screen, minimaps, etc. Builds on the new Camera Driven Rendering added here: #4745 Fixes: #202 Alternative to #1389 and #3626 (which are incompatible with the new Camera Driven Rendering) ## Solution ![image](https://user-images.githubusercontent.com/2694663/171560044-f0694f67-0cd9-4598-83e2-a9658c4fed57.png) Cameras can now configure an optional "viewport", which defines a rectangle within their render target to draw to. If a `Viewport` is defined, the camera's `CameraProjection`, `View`, and visibility calculations will use the viewport configuration instead of the full render target. ```rust // This camera will render to the first half of the primary window (on the left side). commands.spawn_bundle(Camera3dBundle { camera: Camera { viewport: Some(Viewport { physical_position: UVec2::new(0, 0), physical_size: UVec2::new(window.physical_width() / 2, window.physical_height()), depth: 0.0..1.0, }), ..default() }, ..default() }); ``` To account for this, the `Camera` component has received a few adjustments: * `Camera` now has some new getter functions: * `logical_viewport_size`, `physical_viewport_size`, `logical_target_size`, `physical_target_size`, `projection_matrix` * All computed camera values are now private and live on the `ComputedCameraValues` field (logical/physical width/height, the projection matrix). They are now exposed on `Camera` via getters/setters This wasn't _needed_ for viewports, but it was long overdue. --- ## Changelog ### Added * `Camera` components now have a `viewport` field, which can be set to draw to a portion of a render target instead of the full target. * `Camera` component has some new functions: `logical_viewport_size`, `physical_viewport_size`, `logical_target_size`, `physical_target_size`, and `projection_matrix` * Added a new split_screen example illustrating how to render two cameras to the same scene ## Migration Guide `Camera::projection_matrix` is no longer a public field. Use the new `Camera::projection_matrix()` method instead: ```rust // Bevy 0.7 let projection = camera.projection_matrix; // Bevy 0.8 let projection = camera.projection_matrix(); ```
2022-06-05 00:27:49 +00:00
[[example]]
name = "3d_shapes"
Rename shapes examples for consistency (#6082) # Objective I was about to submit a PR to add these two examples to `bevy-website` and re-discovered the inconsistency. Although it's not a major issue on the website where only the filenames are shown, this would help to visually distinguish the two examples in the list because the names are very prominent. This also helps out when fuzzy-searching the codebase for these files. ## Solution Rename `shapes` to `2d_shapes`. Now the filename matches the example name, and the naming structure matches the 3d example. ## Notes @Nilirad proposed this in https://github.com/bevyengine/bevy/pull/4613#discussion_r862455631 but it had slipped away from my brain at that time.
2022-09-25 00:57:07 +00:00
path = "examples/3d/3d_shapes.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Camera Driven Viewports (#4898) # Objective Users should be able to render cameras to specific areas of a render target, which enables scenarios like split screen, minimaps, etc. Builds on the new Camera Driven Rendering added here: #4745 Fixes: #202 Alternative to #1389 and #3626 (which are incompatible with the new Camera Driven Rendering) ## Solution ![image](https://user-images.githubusercontent.com/2694663/171560044-f0694f67-0cd9-4598-83e2-a9658c4fed57.png) Cameras can now configure an optional "viewport", which defines a rectangle within their render target to draw to. If a `Viewport` is defined, the camera's `CameraProjection`, `View`, and visibility calculations will use the viewport configuration instead of the full render target. ```rust // This camera will render to the first half of the primary window (on the left side). commands.spawn_bundle(Camera3dBundle { camera: Camera { viewport: Some(Viewport { physical_position: UVec2::new(0, 0), physical_size: UVec2::new(window.physical_width() / 2, window.physical_height()), depth: 0.0..1.0, }), ..default() }, ..default() }); ``` To account for this, the `Camera` component has received a few adjustments: * `Camera` now has some new getter functions: * `logical_viewport_size`, `physical_viewport_size`, `logical_target_size`, `physical_target_size`, `projection_matrix` * All computed camera values are now private and live on the `ComputedCameraValues` field (logical/physical width/height, the projection matrix). They are now exposed on `Camera` via getters/setters This wasn't _needed_ for viewports, but it was long overdue. --- ## Changelog ### Added * `Camera` components now have a `viewport` field, which can be set to draw to a portion of a render target instead of the full target. * `Camera` component has some new functions: `logical_viewport_size`, `physical_viewport_size`, `logical_target_size`, `physical_target_size`, and `projection_matrix` * Added a new split_screen example illustrating how to render two cameras to the same scene ## Migration Guide `Camera::projection_matrix` is no longer a public field. Use the new `Camera::projection_matrix()` method instead: ```rust // Bevy 0.7 let projection = camera.projection_matrix; // Bevy 0.8 let projection = camera.projection_matrix(); ```
2022-06-05 00:27:49 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.3d_shapes]
name = "3D Shapes"
description = "A scene showcasing the built-in 3D shapes"
category = "3D Rendering"
wasm = true
Add example for `Camera::viewport_to_world` (#7179) Fixes #7177 --------- Co-authored-by: Rob Parrett <robparrett@gmail.com>
2023-09-11 18:52:11 +00:00
[[example]]
name = "3d_viewport_to_world"
path = "examples/3d/3d_viewport_to_world.rs"
doc-scrape-examples = true
[package.metadata.example.3d_viewport_to_world]
name = "3D Viewport To World"
description = "Demonstrates how to use the `Camera::viewport_to_world` method"
category = "3D Rendering"
wasm = true
Add Animated Material example (#11524) # Objective - Fixes #11516 ## Solution - Add Animated Material example (colors are hue-cycling smoothly per-mesh) ![image](https://github.com/bevyengine/bevy/assets/11307157/c75b9e66-0019-41b8-85ec-647559c6ba01) Note: this example reproduces the perf issue found in #10610 pretty consistently, with and without the changes from that PR included. Frame time is sometimes around 4.3ms, other times around 12-14ms. Its pretty random per run. I think this clears #10610 for merge.
2024-01-26 13:34:46 +00:00
[[example]]
name = "animated_material"
path = "examples/3d/animated_material.rs"
doc-scrape-examples = true
[package.metadata.example.animated_material]
name = "Animated Material"
description = "Shows how to animate material properties"
category = "3D Rendering"
wasm = true
Add example to demonstrate manual generation and UV mapping of 3D mesh (generate_custom_mesh) solve #4922 (#8909) # Objective - Fixes #4922 ## Solution - Add an example that maps a custom texture on a 3D mesh. --- ## Changelog > Added the texture itself (confirmed with mod on discord before it should be ok) to the assets folder, added to the README and Cargo.toml. --------- Co-authored-by: Nicola Papale <nicopap@users.noreply.github.com> Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Sélène Amanita <134181069+Selene-Amanita@users.noreply.github.com>
2023-06-23 19:26:37 +00:00
[[example]]
name = "generate_custom_mesh"
path = "examples/3d/generate_custom_mesh.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add example to demonstrate manual generation and UV mapping of 3D mesh (generate_custom_mesh) solve #4922 (#8909) # Objective - Fixes #4922 ## Solution - Add an example that maps a custom texture on a 3D mesh. --- ## Changelog > Added the texture itself (confirmed with mod on discord before it should be ok) to the assets folder, added to the README and Cargo.toml. --------- Co-authored-by: Nicola Papale <nicopap@users.noreply.github.com> Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Sélène Amanita <134181069+Selene-Amanita@users.noreply.github.com>
2023-06-23 19:26:37 +00:00
[package.metadata.example.generate_custom_mesh]
name = "Generate Custom Mesh"
description = "Simple showcase of how to generate a custom mesh with a custom texture"
category = "3D Rendering"
wasm = true
Temporal Antialiasing (TAA) (#7291) ![image](https://user-images.githubusercontent.com/47158642/214374911-412f0986-3927-4f7a-9a6c-413bdee6b389.png) # Objective - Implement an alternative antialias technique - TAA scales based off of view resolution, not geometry complexity - TAA filters textures, firefly pixels, and other aliasing not covered by MSAA - TAA additionally will reduce noise / increase quality in future stochastic rendering techniques - Closes https://github.com/bevyengine/bevy/issues/3663 ## Solution - Add a temporal jitter component - Add a motion vector prepass - Add a TemporalAntialias component and plugin - Combine existing MSAA and FXAA examples and add TAA ## Followup Work - Prepass motion vector support for skinned meshes - Move uniforms needed for motion vectors into a separate bind group, instead of using different bind group layouts - Reuse previous frame's GPU view buffer for motion vectors, instead of recomputing - Mip biasing for sharper textures, and or unjitter texture UVs https://github.com/bevyengine/bevy/issues/7323 - Compute shader for better performance - Investigate FSR techniques - Historical depth based disocclusion tests, for geometry disocclusion - Historical luminance/hue based tests, for shading disocclusion - Pixel "locks" to reduce blending rate / revamp history confidence mechanism - Orthographic camera support for TemporalJitter - Figure out COD's 1-tap bicubic filter --- ## Changelog - Added MotionVectorPrepass and TemporalJitter - Added TemporalAntialiasPlugin, TemporalAntialiasBundle, and TemporalAntialiasSettings --------- Co-authored-by: IceSentry <c.giguere42@gmail.com> Co-authored-by: IceSentry <IceSentry@users.noreply.github.com> Co-authored-by: Robert Swain <robert.swain@gmail.com> Co-authored-by: Daniel Chia <danstryder@gmail.com> Co-authored-by: robtfm <50659922+robtfm@users.noreply.github.com> Co-authored-by: Brandon Dyer <brandondyer64@gmail.com> Co-authored-by: Edgar Geier <geieredgar@gmail.com>
2023-03-27 22:22:40 +00:00
[[example]]
name = "anti_aliasing"
path = "examples/3d/anti_aliasing.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Temporal Antialiasing (TAA) (#7291) ![image](https://user-images.githubusercontent.com/47158642/214374911-412f0986-3927-4f7a-9a6c-413bdee6b389.png) # Objective - Implement an alternative antialias technique - TAA scales based off of view resolution, not geometry complexity - TAA filters textures, firefly pixels, and other aliasing not covered by MSAA - TAA additionally will reduce noise / increase quality in future stochastic rendering techniques - Closes https://github.com/bevyengine/bevy/issues/3663 ## Solution - Add a temporal jitter component - Add a motion vector prepass - Add a TemporalAntialias component and plugin - Combine existing MSAA and FXAA examples and add TAA ## Followup Work - Prepass motion vector support for skinned meshes - Move uniforms needed for motion vectors into a separate bind group, instead of using different bind group layouts - Reuse previous frame's GPU view buffer for motion vectors, instead of recomputing - Mip biasing for sharper textures, and or unjitter texture UVs https://github.com/bevyengine/bevy/issues/7323 - Compute shader for better performance - Investigate FSR techniques - Historical depth based disocclusion tests, for geometry disocclusion - Historical luminance/hue based tests, for shading disocclusion - Pixel "locks" to reduce blending rate / revamp history confidence mechanism - Orthographic camera support for TemporalJitter - Figure out COD's 1-tap bicubic filter --- ## Changelog - Added MotionVectorPrepass and TemporalJitter - Added TemporalAntialiasPlugin, TemporalAntialiasBundle, and TemporalAntialiasSettings --------- Co-authored-by: IceSentry <c.giguere42@gmail.com> Co-authored-by: IceSentry <IceSentry@users.noreply.github.com> Co-authored-by: Robert Swain <robert.swain@gmail.com> Co-authored-by: Daniel Chia <danstryder@gmail.com> Co-authored-by: robtfm <50659922+robtfm@users.noreply.github.com> Co-authored-by: Brandon Dyer <brandondyer64@gmail.com> Co-authored-by: Edgar Geier <geieredgar@gmail.com>
2023-03-27 22:22:40 +00:00
[package.metadata.example.anti_aliasing]
name = "Anti-aliasing"
description = "Compares different anti-aliasing methods"
category = "3D Rendering"
wasm = false
Add Distance and Atmospheric Fog support (#6412) <img width="1392" alt="image" src="https://user-images.githubusercontent.com/418473/203873533-44c029af-13b7-4740-8ea3-af96bd5867c9.png"> <img width="1392" alt="image" src="https://user-images.githubusercontent.com/418473/203873549-36be7a23-b341-42a2-8a9f-ceea8ac7a2b8.png"> # Objective - Add support for the “classic” distance fog effect, as well as a more advanced atmospheric fog effect. ## Solution This PR: - Introduces a new `FogSettings` component that controls distance fog per-camera. - Adds support for three widely used “traditional” fog falloff modes: `Linear`, `Exponential` and `ExponentialSquared`, as well as a more advanced `Atmospheric` fog; - Adds support for directional light influence over fog color; - Extracts fog via `ExtractComponent`, then uses a prepare system that sets up a new dynamic uniform struct (`Fog`), similar to other mesh view types; - Renders fog in PBR material shader, as a final adjustment to the `output_color`, after PBR is computed (but before tone mapping); - Adds a new `StandardMaterial` flag to enable fog; (`fog_enabled`) - Adds convenience methods for easier artistic control when creating non-linear fog types; - Adds documentation around fog. --- ## Changelog ### Added - Added support for distance-based fog effects for PBR materials, controllable per-camera via the new `FogSettings` component; - Added `FogFalloff` enum for selecting between three widely used “traditional” fog falloff modes: `Linear`, `Exponential` and `ExponentialSquared`, as well as a more advanced `Atmospheric` fog;
2023-01-29 15:28:56 +00:00
[[example]]
name = "atmospheric_fog"
path = "examples/3d/atmospheric_fog.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add Distance and Atmospheric Fog support (#6412) <img width="1392" alt="image" src="https://user-images.githubusercontent.com/418473/203873533-44c029af-13b7-4740-8ea3-af96bd5867c9.png"> <img width="1392" alt="image" src="https://user-images.githubusercontent.com/418473/203873549-36be7a23-b341-42a2-8a9f-ceea8ac7a2b8.png"> # Objective - Add support for the “classic” distance fog effect, as well as a more advanced atmospheric fog effect. ## Solution This PR: - Introduces a new `FogSettings` component that controls distance fog per-camera. - Adds support for three widely used “traditional” fog falloff modes: `Linear`, `Exponential` and `ExponentialSquared`, as well as a more advanced `Atmospheric` fog; - Adds support for directional light influence over fog color; - Extracts fog via `ExtractComponent`, then uses a prepare system that sets up a new dynamic uniform struct (`Fog`), similar to other mesh view types; - Renders fog in PBR material shader, as a final adjustment to the `output_color`, after PBR is computed (but before tone mapping); - Adds a new `StandardMaterial` flag to enable fog; (`fog_enabled`) - Adds convenience methods for easier artistic control when creating non-linear fog types; - Adds documentation around fog. --- ## Changelog ### Added - Added support for distance-based fog effects for PBR materials, controllable per-camera via the new `FogSettings` component; - Added `FogFalloff` enum for selecting between three widely used “traditional” fog falloff modes: `Linear`, `Exponential` and `ExponentialSquared`, as well as a more advanced `Atmospheric` fog;
2023-01-29 15:28:56 +00:00
[package.metadata.example.atmospheric_fog]
name = "Atmospheric Fog"
description = "A scene showcasing the atmospheric fog effect"
category = "3D Rendering"
wasm = true
[[example]]
name = "fog"
path = "examples/3d/fog.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add Distance and Atmospheric Fog support (#6412) <img width="1392" alt="image" src="https://user-images.githubusercontent.com/418473/203873533-44c029af-13b7-4740-8ea3-af96bd5867c9.png"> <img width="1392" alt="image" src="https://user-images.githubusercontent.com/418473/203873549-36be7a23-b341-42a2-8a9f-ceea8ac7a2b8.png"> # Objective - Add support for the “classic” distance fog effect, as well as a more advanced atmospheric fog effect. ## Solution This PR: - Introduces a new `FogSettings` component that controls distance fog per-camera. - Adds support for three widely used “traditional” fog falloff modes: `Linear`, `Exponential` and `ExponentialSquared`, as well as a more advanced `Atmospheric` fog; - Adds support for directional light influence over fog color; - Extracts fog via `ExtractComponent`, then uses a prepare system that sets up a new dynamic uniform struct (`Fog`), similar to other mesh view types; - Renders fog in PBR material shader, as a final adjustment to the `output_color`, after PBR is computed (but before tone mapping); - Adds a new `StandardMaterial` flag to enable fog; (`fog_enabled`) - Adds convenience methods for easier artistic control when creating non-linear fog types; - Adds documentation around fog. --- ## Changelog ### Added - Added support for distance-based fog effects for PBR materials, controllable per-camera via the new `FogSettings` component; - Added `FogFalloff` enum for selecting between three widely used “traditional” fog falloff modes: `Linear`, `Exponential` and `ExponentialSquared`, as well as a more advanced `Atmospheric` fog;
2023-01-29 15:28:56 +00:00
[package.metadata.example.fog]
name = "Fog"
description = "A scene showcasing the distance fog effect"
category = "3D Rendering"
wasm = true
Implement Auto Exposure plugin (#12792) # Objective - Add auto exposure/eye adaptation to the bevy render pipeline. - Support features that users might expect from other engines: - Metering masks - Compensation curves - Smooth exposure transitions This PR is based on an implementation I already built for a personal project before https://github.com/bevyengine/bevy/pull/8809 was submitted, so I wasn't able to adopt that PR in the proper way. I've still drawn inspiration from it, so @fintelia should be credited as well. ## Solution An auto exposure compute shader builds a 64 bin histogram of the scene's luminance, and then adjusts the exposure based on that histogram. Using a histogram allows the system to ignore outliers like shadows and specular highlights, and it allows to give more weight to certain areas based on a mask. --- ## Changelog - Added: AutoExposure plugin that allows to adjust a camera's exposure based on it's scene's luminance. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2024-05-03 17:45:17 +00:00
[[example]]
name = "auto_exposure"
path = "examples/3d/auto_exposure.rs"
doc-scrape-examples = true
[package.metadata.example.auto_exposure]
name = "Auto Exposure"
description = "A scene showcasing auto exposure"
category = "3D Rendering"
wasm = false
Standard Material Blend Modes (#6644) # Objective - This PR adds support for blend modes to the PBR `StandardMaterial`. <img width="1392" alt="Screenshot 2022-11-18 at 20 00 56" src="https://user-images.githubusercontent.com/418473/202820627-0636219a-a1e5-437a-b08b-b08c6856bf9c.png"> <img width="1392" alt="Screenshot 2022-11-18 at 20 01 01" src="https://user-images.githubusercontent.com/418473/202820615-c8d43301-9a57-49c4-bd21-4ae343c3e9ec.png"> ## Solution - The existing `AlphaMode` enum is extended, adding three more modes: `AlphaMode::Premultiplied`, `AlphaMode::Add` and `AlphaMode::Multiply`; - All new modes are rendered in the existing `Transparent3d` phase; - The existing mesh flags for alpha mode are reorganized for a more compact/efficient representation, and new values are added; - `MeshPipelineKey::TRANSPARENT_MAIN_PASS` is refactored into `MeshPipelineKey::BLEND_BITS`. - `AlphaMode::Opaque` and `AlphaMode::Mask(f32)` share a single opaque pipeline key: `MeshPipelineKey::BLEND_OPAQUE`; - `Blend`, `Premultiplied` and `Add` share a single premultiplied alpha pipeline key, `MeshPipelineKey::BLEND_PREMULTIPLIED_ALPHA`. In the shader, color values are premultiplied accordingly (or not) depending on the blend mode to produce the three different results after PBR/tone mapping/dithering; - `Multiply` uses its own independent pipeline key, `MeshPipelineKey::BLEND_MULTIPLY`; - Example and documentation are provided. --- ## Changelog ### Added - Added support for additive and multiplicative blend modes in the PBR `StandardMaterial`, via `AlphaMode::Add` and `AlphaMode::Multiply`; - Added support for premultiplied alpha in the PBR `StandardMaterial`, via `AlphaMode::Premultiplied`;
2023-01-21 21:46:53 +00:00
[[example]]
name = "blend_modes"
path = "examples/3d/blend_modes.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Standard Material Blend Modes (#6644) # Objective - This PR adds support for blend modes to the PBR `StandardMaterial`. <img width="1392" alt="Screenshot 2022-11-18 at 20 00 56" src="https://user-images.githubusercontent.com/418473/202820627-0636219a-a1e5-437a-b08b-b08c6856bf9c.png"> <img width="1392" alt="Screenshot 2022-11-18 at 20 01 01" src="https://user-images.githubusercontent.com/418473/202820615-c8d43301-9a57-49c4-bd21-4ae343c3e9ec.png"> ## Solution - The existing `AlphaMode` enum is extended, adding three more modes: `AlphaMode::Premultiplied`, `AlphaMode::Add` and `AlphaMode::Multiply`; - All new modes are rendered in the existing `Transparent3d` phase; - The existing mesh flags for alpha mode are reorganized for a more compact/efficient representation, and new values are added; - `MeshPipelineKey::TRANSPARENT_MAIN_PASS` is refactored into `MeshPipelineKey::BLEND_BITS`. - `AlphaMode::Opaque` and `AlphaMode::Mask(f32)` share a single opaque pipeline key: `MeshPipelineKey::BLEND_OPAQUE`; - `Blend`, `Premultiplied` and `Add` share a single premultiplied alpha pipeline key, `MeshPipelineKey::BLEND_PREMULTIPLIED_ALPHA`. In the shader, color values are premultiplied accordingly (or not) depending on the blend mode to produce the three different results after PBR/tone mapping/dithering; - `Multiply` uses its own independent pipeline key, `MeshPipelineKey::BLEND_MULTIPLY`; - Example and documentation are provided. --- ## Changelog ### Added - Added support for additive and multiplicative blend modes in the PBR `StandardMaterial`, via `AlphaMode::Add` and `AlphaMode::Multiply`; - Added support for premultiplied alpha in the PBR `StandardMaterial`, via `AlphaMode::Premultiplied`;
2023-01-21 21:46:53 +00:00
[package.metadata.example.blend_modes]
name = "Blend Modes"
description = "Showcases different blend modes"
category = "3D Rendering"
Option to enable deterministic rendering (#11248) # Objective Issue #10243: rendering multiple triangles in the same place results in flickering. ## Solution Considered these alternatives: - `depth_bias` may not work, because of high number of entities, so creating a material per entity is practically not possible - rendering at slightly different positions does not work, because when camera is far, float rounding causes the same issues (edit: assuming we have to use the same `depth_bias`) - considered implementing deterministic operation like `query.par_iter().flat_map(...).collect()` to be used in `check_visibility` system (which would solve the issue since query is deterministic), and could not figure out how to make it as cheap as current approach with thread-local collectors (#11249) So adding an option to sort entities after `check_visibility` system run. Should not be too bad, because after visibility check, only a handful entities remain. This is probably not the only source of non-determinism in Bevy, but this is one I could find so far. At least it fixes the repro example. ## Changelog - `DeterministicRenderingConfig` option to enable deterministic rendering ## Test <img width="1392" alt="image" src="https://github.com/bevyengine/bevy/assets/28969/c735bce1-3a71-44cd-8677-c19f6c0ee6bd"> --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2024-01-09 00:46:01 +00:00
wasm = true
SubGraphs, Views, Shadows, and more
2021-06-02 02:59:17 +00:00
[[example]]
Replace old renderer with new renderer (#3312) This makes the [New Bevy Renderer](#2535) the default (and only) renderer. The new renderer isn't _quite_ ready for the final release yet, but I want as many people as possible to start testing it so we can identify bugs and address feedback prior to release. The examples are all ported over and operational with a few exceptions: * I removed a good portion of the examples in the `shader` folder. We still have some work to do in order to make these examples possible / ergonomic / worthwhile: #3120 and "high level shader material plugins" are the big ones. This is a temporary measure. * Temporarily removed the multiple_windows example: doing this properly in the new renderer will require the upcoming "render targets" changes. Same goes for the render_to_texture example. * Removed z_sort_debug: entity visibility sort info is no longer available in app logic. we could do this on the "render app" side, but i dont consider it a priority.
2021-12-14 03:58:23 +00:00
name = "lighting"
path = "examples/3d/lighting.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Directional light and shadow (#6) Directional light and shadow
2021-07-08 02:49:33 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.lighting]
name = "Lighting"
description = "Illustrates various lighting options in a simple scene"
category = "3D Rendering"
wasm = true
add a 3d lines example (#5319) # Objective - Showcase how to use a `Material` and `Mesh` to spawn 3d lines ![image](https://user-images.githubusercontent.com/8348954/179034236-ebc07f90-3eb5-46cc-8fc1-be7e6bf983fb.png) ## Solution - Add an example using a simple `Material` and `Mesh` definition to draw a 3d line - Shows how to use `LineList` and `LineStrip` in combination with a specialized `Material` ## Notes This isn't just a primitive shape because it needs a special Material, but I think it's a good showcase of the power of the `Material` and `AsBindGroup` abstractions. All of this is easy to figure out when you know these options are a thing, but I think they are hard to discover which is why I think this should be an example and not shipped with bevy. Co-authored-by: Charles <IceSentry@users.noreply.github.com>
2022-07-15 22:37:05 +00:00
[[example]]
name = "lines"
path = "examples/3d/lines.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
add a 3d lines example (#5319) # Objective - Showcase how to use a `Material` and `Mesh` to spawn 3d lines ![image](https://user-images.githubusercontent.com/8348954/179034236-ebc07f90-3eb5-46cc-8fc1-be7e6bf983fb.png) ## Solution - Add an example using a simple `Material` and `Mesh` definition to draw a 3d line - Shows how to use `LineList` and `LineStrip` in combination with a specialized `Material` ## Notes This isn't just a primitive shape because it needs a special Material, but I think it's a good showcase of the power of the `Material` and `AsBindGroup` abstractions. All of this is easy to figure out when you know these options are a thing, but I think they are hard to discover which is why I think this should be an example and not shipped with bevy. Co-authored-by: Charles <IceSentry@users.noreply.github.com>
2022-07-15 22:37:05 +00:00
[package.metadata.example.lines]
name = "Lines"
description = "Create a custom material to draw 3d lines"
category = "3D Rendering"
Fix common capitalization errors in documentation (#14562) WASM -> Wasm MacOS -> macOS Nothing important, just something that annoyed me for a while :)
2024-07-31 21:16:05 +00:00
# Wasm does not support the `POLYGON_MODE_LINE` feature.
Disabled usage of the POLYGON_MODE_LINE gpu feature in the examples (#14402) Fixes #14353 Fixes #14371 --------- Signed-off-by: Sarthak Singh <sarthak.singh99@gmail.com> Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: BD103 <59022059+BD103@users.noreply.github.com>
2024-07-29 23:40:39 +00:00
wasm = false
add a 3d lines example (#5319) # Objective - Showcase how to use a `Material` and `Mesh` to spawn 3d lines ![image](https://user-images.githubusercontent.com/8348954/179034236-ebc07f90-3eb5-46cc-8fc1-be7e6bf983fb.png) ## Solution - Add an example using a simple `Material` and `Mesh` definition to draw a 3d line - Shows how to use `LineList` and `LineStrip` in combination with a specialized `Material` ## Notes This isn't just a primitive shape because it needs a special Material, but I think it's a good showcase of the power of the `Material` and `AsBindGroup` abstractions. All of this is easy to figure out when you know these options are a thing, but I think they are hard to discover which is why I think this should be an example and not shipped with bevy. Co-authored-by: Charles <IceSentry@users.noreply.github.com>
2022-07-15 22:37:05 +00:00
Screen Space Ambient Occlusion (SSAO) MVP (#7402) ![image](https://github.com/bevyengine/bevy/assets/47158642/dbb62645-f639-4f2b-b84b-26fd915c186d) # Objective - Add Screen space ambient occlusion (SSAO). SSAO approximates small-scale, local occlusion of _indirect_ diffuse light between objects. SSAO does not apply to direct lighting, such as point or directional lights. - This darkens creases, e.g. on staircases, and gives nice contact shadows where objects meet, giving entities a more "grounded" feel. - Closes https://github.com/bevyengine/bevy/issues/3632. ## Solution - Implement the GTAO algorithm. - https://www.activision.com/cdn/research/Practical_Real_Time_Strategies_for_Accurate_Indirect_Occlusion_NEW%20VERSION_COLOR.pdf - https://blog.selfshadow.com/publications/s2016-shading-course/activision/s2016_pbs_activision_occlusion.pdf - Source code heavily based on [Intel's XeGTAO](https://github.com/GameTechDev/XeGTAO/blob/0d177ce06bfa642f64d8af4de1197ad1bcb862d4/Source/Rendering/Shaders/XeGTAO.hlsli). - Add an SSAO bevy example. ## Algorithm Overview * Run a depth and normal prepass * Create downscaled mips of the depth texture (preprocess_depths pass) * GTAO pass - for each pixel, take several random samples from the depth+normal buffers, reconstruct world position, raytrace in screen space to estimate occlusion. Rather then doing completely random samples on a hemisphere, you choose random _slices_ of the hemisphere, and then can analytically compute the full occlusion of that slice. Also compute edges based on depth differences here. * Spatial denoise pass - bilateral blur, using edge detection to not blur over edges. This is the final SSAO result. * Main pass - if SSAO exists, sample the SSAO texture, and set occlusion to be the minimum of ssao/material occlusion. This then feeds into the rest of the PBR shader as normal. --- ## Future Improvements - Maybe remove the low quality preset for now (too noisy) - WebGPU fallback (see below) - Faster depth->world position (see reverted code) - Bent normals - Try interleaved gradient noise or spatiotemporal blue noise - Replace the spatial denoiser with a combined spatial+temporal denoiser - Render at half resolution and use a bilateral upsample - Better multibounce approximation (https://drive.google.com/file/d/1SyagcEVplIm2KkRD3WQYSO9O0Iyi1hfy/view) ## Far-Future Performance Improvements - F16 math (missing naga-wgsl support https://github.com/gfx-rs/naga/issues/1884) - Faster coordinate space conversion for normals - Faster depth mipchain creation (https://github.com/GPUOpen-Effects/FidelityFX-SPD) (wgpu/naga does not currently support subgroup ops) - Deinterleaved SSAO for better cache efficiency (https://developer.nvidia.com/sites/default/files/akamai/gameworks/samples/DeinterleavedTexturing.pdf) ## Other Interesting Papers - Visibility bitmask (https://link.springer.com/article/10.1007/s00371-022-02703-y, https://cdrinmatane.github.io/posts/cgspotlight-slides/) - Screen space diffuse lighting (https://github.com/Patapom/GodComplex/blob/master/Tests/TestHBIL/2018%20Mayaux%20-%20Horizon-Based%20Indirect%20Lighting%20(HBIL).pdf) ## Platform Support * SSAO currently does not work on DirectX12 due to issues with wgpu and naga: * https://github.com/gfx-rs/wgpu/pull/3798 * https://github.com/gfx-rs/naga/pull/2353 * SSAO currently does not work on WebGPU because r16float is not a valid storage texture format https://gpuweb.github.io/gpuweb/wgsl/#storage-texel-formats. We can fix this with a fallback to r32float. --- ## Changelog - Added ScreenSpaceAmbientOcclusionSettings, ScreenSpaceAmbientOcclusionQualityLevel, and ScreenSpaceAmbientOcclusionBundle --------- Co-authored-by: IceSentry <c.giguere42@gmail.com> Co-authored-by: IceSentry <IceSentry@users.noreply.github.com> Co-authored-by: Daniel Chia <danstryder@gmail.com> Co-authored-by: Elabajaba <Elabajaba@users.noreply.github.com> Co-authored-by: Robert Swain <robert.swain@gmail.com> Co-authored-by: robtfm <50659922+robtfm@users.noreply.github.com> Co-authored-by: Brandon Dyer <brandondyer64@gmail.com> Co-authored-by: Edgar Geier <geieredgar@gmail.com> Co-authored-by: Nicola Papale <nicopap@users.noreply.github.com> Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-06-18 21:05:55 +00:00
[[example]]
name = "ssao"
path = "examples/3d/ssao.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Screen Space Ambient Occlusion (SSAO) MVP (#7402) ![image](https://github.com/bevyengine/bevy/assets/47158642/dbb62645-f639-4f2b-b84b-26fd915c186d) # Objective - Add Screen space ambient occlusion (SSAO). SSAO approximates small-scale, local occlusion of _indirect_ diffuse light between objects. SSAO does not apply to direct lighting, such as point or directional lights. - This darkens creases, e.g. on staircases, and gives nice contact shadows where objects meet, giving entities a more "grounded" feel. - Closes https://github.com/bevyengine/bevy/issues/3632. ## Solution - Implement the GTAO algorithm. - https://www.activision.com/cdn/research/Practical_Real_Time_Strategies_for_Accurate_Indirect_Occlusion_NEW%20VERSION_COLOR.pdf - https://blog.selfshadow.com/publications/s2016-shading-course/activision/s2016_pbs_activision_occlusion.pdf - Source code heavily based on [Intel's XeGTAO](https://github.com/GameTechDev/XeGTAO/blob/0d177ce06bfa642f64d8af4de1197ad1bcb862d4/Source/Rendering/Shaders/XeGTAO.hlsli). - Add an SSAO bevy example. ## Algorithm Overview * Run a depth and normal prepass * Create downscaled mips of the depth texture (preprocess_depths pass) * GTAO pass - for each pixel, take several random samples from the depth+normal buffers, reconstruct world position, raytrace in screen space to estimate occlusion. Rather then doing completely random samples on a hemisphere, you choose random _slices_ of the hemisphere, and then can analytically compute the full occlusion of that slice. Also compute edges based on depth differences here. * Spatial denoise pass - bilateral blur, using edge detection to not blur over edges. This is the final SSAO result. * Main pass - if SSAO exists, sample the SSAO texture, and set occlusion to be the minimum of ssao/material occlusion. This then feeds into the rest of the PBR shader as normal. --- ## Future Improvements - Maybe remove the low quality preset for now (too noisy) - WebGPU fallback (see below) - Faster depth->world position (see reverted code) - Bent normals - Try interleaved gradient noise or spatiotemporal blue noise - Replace the spatial denoiser with a combined spatial+temporal denoiser - Render at half resolution and use a bilateral upsample - Better multibounce approximation (https://drive.google.com/file/d/1SyagcEVplIm2KkRD3WQYSO9O0Iyi1hfy/view) ## Far-Future Performance Improvements - F16 math (missing naga-wgsl support https://github.com/gfx-rs/naga/issues/1884) - Faster coordinate space conversion for normals - Faster depth mipchain creation (https://github.com/GPUOpen-Effects/FidelityFX-SPD) (wgpu/naga does not currently support subgroup ops) - Deinterleaved SSAO for better cache efficiency (https://developer.nvidia.com/sites/default/files/akamai/gameworks/samples/DeinterleavedTexturing.pdf) ## Other Interesting Papers - Visibility bitmask (https://link.springer.com/article/10.1007/s00371-022-02703-y, https://cdrinmatane.github.io/posts/cgspotlight-slides/) - Screen space diffuse lighting (https://github.com/Patapom/GodComplex/blob/master/Tests/TestHBIL/2018%20Mayaux%20-%20Horizon-Based%20Indirect%20Lighting%20(HBIL).pdf) ## Platform Support * SSAO currently does not work on DirectX12 due to issues with wgpu and naga: * https://github.com/gfx-rs/wgpu/pull/3798 * https://github.com/gfx-rs/naga/pull/2353 * SSAO currently does not work on WebGPU because r16float is not a valid storage texture format https://gpuweb.github.io/gpuweb/wgsl/#storage-texel-formats. We can fix this with a fallback to r32float. --- ## Changelog - Added ScreenSpaceAmbientOcclusionSettings, ScreenSpaceAmbientOcclusionQualityLevel, and ScreenSpaceAmbientOcclusionBundle --------- Co-authored-by: IceSentry <c.giguere42@gmail.com> Co-authored-by: IceSentry <IceSentry@users.noreply.github.com> Co-authored-by: Daniel Chia <danstryder@gmail.com> Co-authored-by: Elabajaba <Elabajaba@users.noreply.github.com> Co-authored-by: Robert Swain <robert.swain@gmail.com> Co-authored-by: robtfm <50659922+robtfm@users.noreply.github.com> Co-authored-by: Brandon Dyer <brandondyer64@gmail.com> Co-authored-by: Edgar Geier <geieredgar@gmail.com> Co-authored-by: Nicola Papale <nicopap@users.noreply.github.com> Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-06-18 21:05:55 +00:00
[package.metadata.example.ssao]
name = "Screen Space Ambient Occlusion"
description = "A scene showcasing screen space ambient occlusion"
category = "3D Rendering"
wasm = false
Spotlights (#4715) # Objective add spotlight support ## Solution / Changelog - add spotlight angles (inner, outer) to ``PointLight`` struct. emitted light is linearly attenuated from 100% to 0% as angle tends from inner to outer. Direction is taken from the existing transform rotation. - add spotlight direction (vec3) and angles (f32,f32) to ``GpuPointLight`` struct (60 bytes -> 80 bytes) in ``pbr/render/lights.rs`` and ``mesh_view_bind_group.wgsl`` - reduce no-buffer-support max point light count to 204 due to above - use spotlight data to attenuate light in ``pbr.wgsl`` - do additional cluster culling on spotlights to minimise cost in ``assign_lights_to_clusters`` - changed one of the lights in the lighting demo to a spotlight - also added a ``spotlight`` demo - probably not justified but so reviewers can see it more easily ## notes increasing the size of the GpuPointLight struct on my machine reduces the FPS of ``many_lights -- sphere`` from ~150fps to 140fps. i thought this was a reasonable tradeoff, and felt better than handling spotlights separately which is possible but would mean introducing a new bind group, refactoring light-assignment code and adding new spotlight-specific code in pbr.wgsl. the FPS impact for smaller numbers of lights should be very small. the cluster culling strategy reintroduces the cluster aabb code which was recently removed... sorry. the aabb is used to get a cluster bounding sphere, which can then be tested fairly efficiently using the strategy described at the end of https://bartwronski.com/2017/04/13/cull-that-cone/. this works well with roughly cubic clusters (where the cluster z size is close to the same as x/y size), less well for other cases like single Z slice / tiled forward rendering. In the worst case we will end up just keeping the culling of the equivalent point light. Co-authored-by: François <mockersf@gmail.com>
2022-07-08 19:57:43 +00:00
[[example]]
name = "spotlight"
path = "examples/3d/spotlight.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Spotlights (#4715) # Objective add spotlight support ## Solution / Changelog - add spotlight angles (inner, outer) to ``PointLight`` struct. emitted light is linearly attenuated from 100% to 0% as angle tends from inner to outer. Direction is taken from the existing transform rotation. - add spotlight direction (vec3) and angles (f32,f32) to ``GpuPointLight`` struct (60 bytes -> 80 bytes) in ``pbr/render/lights.rs`` and ``mesh_view_bind_group.wgsl`` - reduce no-buffer-support max point light count to 204 due to above - use spotlight data to attenuate light in ``pbr.wgsl`` - do additional cluster culling on spotlights to minimise cost in ``assign_lights_to_clusters`` - changed one of the lights in the lighting demo to a spotlight - also added a ``spotlight`` demo - probably not justified but so reviewers can see it more easily ## notes increasing the size of the GpuPointLight struct on my machine reduces the FPS of ``many_lights -- sphere`` from ~150fps to 140fps. i thought this was a reasonable tradeoff, and felt better than handling spotlights separately which is possible but would mean introducing a new bind group, refactoring light-assignment code and adding new spotlight-specific code in pbr.wgsl. the FPS impact for smaller numbers of lights should be very small. the cluster culling strategy reintroduces the cluster aabb code which was recently removed... sorry. the aabb is used to get a cluster bounding sphere, which can then be tested fairly efficiently using the strategy described at the end of https://bartwronski.com/2017/04/13/cull-that-cone/. this works well with roughly cubic clusters (where the cluster z size is close to the same as x/y size), less well for other cases like single Z slice / tiled forward rendering. In the worst case we will end up just keeping the culling of the equivalent point light. Co-authored-by: François <mockersf@gmail.com>
2022-07-08 19:57:43 +00:00
[package.metadata.example.spotlight]
name = "Spotlight"
description = "Illustrates spot lights"
category = "3D Rendering"
wasm = true
Bloom (#6397) # Objective - Adds a bloom pass for HDR-enabled Camera3ds. - Supersedes (and all credit due to!) https://github.com/bevyengine/bevy/pull/3430 and https://github.com/bevyengine/bevy/pull/2876 ![image](https://user-images.githubusercontent.com/47158642/198698783-228edc00-20b5-4218-a613-331ccd474f38.png) ## Solution - A threshold is applied to isolate emissive samples, and then a series of downscale and upscaling passes are applied and composited together. - Bloom is applied to 2d or 3d Cameras with hdr: true and a BloomSettings component. --- ## Changelog - Added a `core_pipeline::bloom::BloomSettings` component. - Added `BloomNode` that runs between the main pass and tonemapping. - Added a `BloomPlugin` that is loaded as part of CorePipelinePlugin. - Added a bloom example project. Co-authored-by: JMS55 <47158642+JMS55@users.noreply.github.com> Co-authored-by: Carter Anderson <mcanders1@gmail.com> Co-authored-by: DGriffin91 <github@dgdigital.net>
2022-11-04 01:34:12 +00:00
[[example]]
Revamp Bloom (#6677) ![image](https://user-images.githubusercontent.com/47158642/220197588-25e11022-02e4-45f3-b2e5-392c4ce7a025.png) Huge credit to @StarLederer, who did almost all of the work on this. We're just reusing this PR to keep everything in one place. # Objective 1. Make bloom more physically based. 1. Improve artistic control. 1. Allow to use bloom as screen blur. 1. Fix #6634. 1. Address #6655 (although the author makes incorrect conclusions). ## Solution 1. Set the default threshold to 0. 2. Lerp between bloom textures when `composite_mode: BloomCompositeMode::EnergyConserving`. 1. Use [a parametric function](https://starlederer.github.io/bloom) to control blend levels for each bloom texture. In the future this can be controlled per-pixel for things like lens dirt. 3. Implement BloomCompositeMode::Additive` for situations where the old school look is desired. ## Changelog * Bloom now looks different. * Added `BloomSettings:lf_boost`, `BloomSettings:lf_boost_curvature`, `BloomSettings::high_pass_frequency` and `BloomSettings::composite_mode`. * `BloomSettings::scale` removed. * `BloomSettings::knee` renamed to `BloomPrefilterSettings::softness`. * `BloomSettings::threshold` renamed to `BloomPrefilterSettings::threshold`. * The bloom example has been renamed to bloom_3d and improved. A bloom_2d example was added. ## Migration Guide * Refactor mentions of `BloomSettings::knee` and `BloomSettings::threshold` as `BloomSettings::prefilter_settings` where knee is now `softness`. * If defined without `..default()` add `..default()` to definitions of `BloomSettings` instances or manually define missing fields. * Adapt to Bloom looking visually different (if needed). Co-authored-by: Herman Lederer <germans.lederers@gmail.com>
2023-03-04 12:05:26 +00:00
name = "bloom_3d"
path = "examples/3d/bloom_3d.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Bloom (#6397) # Objective - Adds a bloom pass for HDR-enabled Camera3ds. - Supersedes (and all credit due to!) https://github.com/bevyengine/bevy/pull/3430 and https://github.com/bevyengine/bevy/pull/2876 ![image](https://user-images.githubusercontent.com/47158642/198698783-228edc00-20b5-4218-a613-331ccd474f38.png) ## Solution - A threshold is applied to isolate emissive samples, and then a series of downscale and upscaling passes are applied and composited together. - Bloom is applied to 2d or 3d Cameras with hdr: true and a BloomSettings component. --- ## Changelog - Added a `core_pipeline::bloom::BloomSettings` component. - Added `BloomNode` that runs between the main pass and tonemapping. - Added a `BloomPlugin` that is loaded as part of CorePipelinePlugin. - Added a bloom example project. Co-authored-by: JMS55 <47158642+JMS55@users.noreply.github.com> Co-authored-by: Carter Anderson <mcanders1@gmail.com> Co-authored-by: DGriffin91 <github@dgdigital.net>
2022-11-04 01:34:12 +00:00
Revamp Bloom (#6677) ![image](https://user-images.githubusercontent.com/47158642/220197588-25e11022-02e4-45f3-b2e5-392c4ce7a025.png) Huge credit to @StarLederer, who did almost all of the work on this. We're just reusing this PR to keep everything in one place. # Objective 1. Make bloom more physically based. 1. Improve artistic control. 1. Allow to use bloom as screen blur. 1. Fix #6634. 1. Address #6655 (although the author makes incorrect conclusions). ## Solution 1. Set the default threshold to 0. 2. Lerp between bloom textures when `composite_mode: BloomCompositeMode::EnergyConserving`. 1. Use [a parametric function](https://starlederer.github.io/bloom) to control blend levels for each bloom texture. In the future this can be controlled per-pixel for things like lens dirt. 3. Implement BloomCompositeMode::Additive` for situations where the old school look is desired. ## Changelog * Bloom now looks different. * Added `BloomSettings:lf_boost`, `BloomSettings:lf_boost_curvature`, `BloomSettings::high_pass_frequency` and `BloomSettings::composite_mode`. * `BloomSettings::scale` removed. * `BloomSettings::knee` renamed to `BloomPrefilterSettings::softness`. * `BloomSettings::threshold` renamed to `BloomPrefilterSettings::threshold`. * The bloom example has been renamed to bloom_3d and improved. A bloom_2d example was added. ## Migration Guide * Refactor mentions of `BloomSettings::knee` and `BloomSettings::threshold` as `BloomSettings::prefilter_settings` where knee is now `softness`. * If defined without `..default()` add `..default()` to definitions of `BloomSettings` instances or manually define missing fields. * Adapt to Bloom looking visually different (if needed). Co-authored-by: Herman Lederer <germans.lederers@gmail.com>
2023-03-04 12:05:26 +00:00
[package.metadata.example.bloom_3d]
name = "3D Bloom"
Bloom (#6397) # Objective - Adds a bloom pass for HDR-enabled Camera3ds. - Supersedes (and all credit due to!) https://github.com/bevyengine/bevy/pull/3430 and https://github.com/bevyengine/bevy/pull/2876 ![image](https://user-images.githubusercontent.com/47158642/198698783-228edc00-20b5-4218-a613-331ccd474f38.png) ## Solution - A threshold is applied to isolate emissive samples, and then a series of downscale and upscaling passes are applied and composited together. - Bloom is applied to 2d or 3d Cameras with hdr: true and a BloomSettings component. --- ## Changelog - Added a `core_pipeline::bloom::BloomSettings` component. - Added `BloomNode` that runs between the main pass and tonemapping. - Added a `BloomPlugin` that is loaded as part of CorePipelinePlugin. - Added a bloom example project. Co-authored-by: JMS55 <47158642+JMS55@users.noreply.github.com> Co-authored-by: Carter Anderson <mcanders1@gmail.com> Co-authored-by: DGriffin91 <github@dgdigital.net>
2022-11-04 01:34:12 +00:00
description = "Illustrates bloom configuration using HDR and emissive materials"
category = "3D Rendering"
Fix bloom wasm support (#8631) # Objective - Fixes #7352 ## Solution GLES doesn't support binding specific mip levels for sampling. Fallback to using separate textures instead. - [wgpu-hal/src/gles/device.rs](https://github.com/gfx-rs/wgpu/blob/628a95cd1c27abce4d4ff2ffe4558cc4ef1e7fd3/wgpu-hal/src/gles/device.rs#L1038) --- --------- Co-authored-by: Wilhelm Vallrand <>
2023-05-19 20:11:41 +00:00
wasm = true
Bloom (#6397) # Objective - Adds a bloom pass for HDR-enabled Camera3ds. - Supersedes (and all credit due to!) https://github.com/bevyengine/bevy/pull/3430 and https://github.com/bevyengine/bevy/pull/2876 ![image](https://user-images.githubusercontent.com/47158642/198698783-228edc00-20b5-4218-a613-331ccd474f38.png) ## Solution - A threshold is applied to isolate emissive samples, and then a series of downscale and upscaling passes are applied and composited together. - Bloom is applied to 2d or 3d Cameras with hdr: true and a BloomSettings component. --- ## Changelog - Added a `core_pipeline::bloom::BloomSettings` component. - Added `BloomNode` that runs between the main pass and tonemapping. - Added a `BloomPlugin` that is loaded as part of CorePipelinePlugin. - Added a bloom example project. Co-authored-by: JMS55 <47158642+JMS55@users.noreply.github.com> Co-authored-by: Carter Anderson <mcanders1@gmail.com> Co-authored-by: DGriffin91 <github@dgdigital.net>
2022-11-04 01:34:12 +00:00
Deferred Renderer (#9258) # Objective - Add a [Deferred Renderer](https://en.wikipedia.org/wiki/Deferred_shading) to Bevy. - This allows subsequent passes to access per pixel material information before/during shading. - Accessing this per pixel material information is needed for some features, like GI. It also makes other features (ex. Decals) simpler to implement and/or improves their capability. There are multiple approaches to accomplishing this. The deferred shading approach works well given the limitations of WebGPU and WebGL2. Motivation: [I'm working on a GI solution for Bevy](https://youtu.be/eH1AkL-mwhI) # Solution - The deferred renderer is implemented with a prepass and a deferred lighting pass. - The prepass renders opaque objects into the Gbuffer attachment (`Rgba32Uint`). The PBR shader generates a `PbrInput` in mostly the same way as the forward implementation and then [packs it into the Gbuffer](https://github.com/DGriffin91/bevy/blob/ec1465559f2c82001830e908fc02ff1d7c2efe51/crates/bevy_pbr/src/render/pbr.wgsl#L168). - The deferred lighting pass unpacks the `PbrInput` and [feeds it into the pbr() function](https://github.com/DGriffin91/bevy/blob/ec1465559f2c82001830e908fc02ff1d7c2efe51/crates/bevy_pbr/src/deferred/deferred_lighting.wgsl#L65), then outputs the shaded color data. - There is now a resource [DefaultOpaqueRendererMethod](https://github.com/DGriffin91/bevy/blob/ec1465559f2c82001830e908fc02ff1d7c2efe51/crates/bevy_pbr/src/material.rs#L599) that can be used to set the default render method for opaque materials. If materials return `None` from [opaque_render_method()](https://github.com/DGriffin91/bevy/blob/ec1465559f2c82001830e908fc02ff1d7c2efe51/crates/bevy_pbr/src/material.rs#L131) the `DefaultOpaqueRendererMethod` will be used. Otherwise, custom materials can also explicitly choose to only support Deferred or Forward by returning the respective [OpaqueRendererMethod](https://github.com/DGriffin91/bevy/blob/ec1465559f2c82001830e908fc02ff1d7c2efe51/crates/bevy_pbr/src/material.rs#L603) - Deferred materials can be used seamlessly along with both opaque and transparent forward rendered materials in the same scene. The [deferred rendering example](https://github.com/DGriffin91/bevy/blob/deferred/examples/3d/deferred_rendering.rs) does this. - The deferred renderer does not support MSAA. If any deferred materials are used, MSAA must be disabled. Both TAA and FXAA are supported. - Deferred rendering supports WebGL2/WebGPU. ## Custom deferred materials - Custom materials can support both deferred and forward at the same time. The [StandardMaterial](https://github.com/DGriffin91/bevy/blob/ec1465559f2c82001830e908fc02ff1d7c2efe51/crates/bevy_pbr/src/render/pbr.wgsl#L166) does this. So does [this example](https://github.com/DGriffin91/bevy_glowy_orb_tutorial/blob/deferred/assets/shaders/glowy.wgsl#L56). - Custom deferred materials that require PBR lighting can create a `PbrInput`, write it to the deferred GBuffer and let it be rendered by the `PBRDeferredLightingPlugin`. - Custom deferred materials that require custom lighting have two options: 1. Use the base_color channel of the `PbrInput` combined with the `STANDARD_MATERIAL_FLAGS_UNLIT_BIT` flag. [Example.](https://github.com/DGriffin91/bevy_glowy_orb_tutorial/blob/deferred/assets/shaders/glowy.wgsl#L56) (If the unlit bit is set, the base_color is stored as RGB9E5 for extra precision) 2. A Custom Deferred Lighting pass can be created, either overriding the default, or running in addition. The a depth buffer is used to limit rendering to only the required fragments for each deferred lighting pass. Materials can set their respective depth id via the [deferred_lighting_pass_id](https://github.com/DGriffin91/bevy/blob/b79182d2a32cac28c4213c2457a53ac2cc885332/crates/bevy_pbr/src/prepass/prepass_io.wgsl#L95) attachment. The custom deferred lighting pass plugin can then set [its corresponding depth](https://github.com/DGriffin91/bevy/blob/ec1465559f2c82001830e908fc02ff1d7c2efe51/crates/bevy_pbr/src/deferred/deferred_lighting.wgsl#L37). Then with the lighting pass using [CompareFunction::Equal](https://github.com/DGriffin91/bevy/blob/ec1465559f2c82001830e908fc02ff1d7c2efe51/crates/bevy_pbr/src/deferred/mod.rs#L335), only the fragments with a depth that equal the corresponding depth written in the material will be rendered. Custom deferred lighting plugins can also be created to render the StandardMaterial. The default deferred lighting plugin can be bypassed with `DefaultPlugins.set(PBRDeferredLightingPlugin { bypass: true })` --------- Co-authored-by: nickrart <nickolas.g.russell@gmail.com>
2023-10-12 22:10:38 +00:00
[[example]]
name = "deferred_rendering"
path = "examples/3d/deferred_rendering.rs"
Fix some doc warnings (#12961) # Objective - Fix some doc warnings - Add doc-scrape-examples to all examples Moved from #12692 I run `cargo +nightly doc --workspace --all-features --no-deps -Zunstable-options -Zrustdoc-scrape-examples` <details> ``` warning: public documentation for `GzAssetLoaderError` links to private item `GzAssetLoader` --> examples/asset/asset_decompression.rs:24:47 | 24 | /// Possible errors that can be produced by [`GzAssetLoader`] | ^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: `bevy` (example "asset_decompression") generated 1 warning warning: unresolved link to `shape::Quad` --> examples/2d/mesh2d.rs:3:15 | 3 | //! [`Quad`]: shape::Quad | ^^^^^^^^^^^ no item named `shape` in scope | = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "mesh2d") generated 1 warning warning: unresolved link to `WorldQuery` --> examples/ecs/custom_query_param.rs:1:49 | 1 | //! This example illustrates the usage of the [`WorldQuery`] derive macro, which allows | ^^^^^^^^^^ no item named `WorldQuery` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "custom_query_param") generated 1 warning warning: unresolved link to `shape::Quad` --> examples/2d/mesh2d_vertex_color_texture.rs:4:15 | 4 | //! [`Quad`]: shape::Quad | ^^^^^^^^^^^ no item named `shape` in scope | = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "mesh2d_vertex_color_texture") generated 1 warning warning: public documentation for `TextPlugin` links to private item `CoolText` --> examples/asset/processing/asset_processing.rs:48:9 | 48 | /// * [`CoolText`]: a custom RON text format that supports dependencies and embedded dependencies | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: public documentation for `TextPlugin` links to private item `Text` --> examples/asset/processing/asset_processing.rs:49:9 | 49 | /// * [`Text`]: a "normal" plain text file | ^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: public documentation for `TextPlugin` links to private item `CoolText` --> examples/asset/processing/asset_processing.rs:51:57 | 51 | /// It also defines an asset processor that will load [`CoolText`], resolve embedded dependenc... | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: `bevy` (example "asset_processing") generated 3 warnings warning: public documentation for `CustomAssetLoaderError` links to private item `CustomAssetLoader` --> examples/asset/custom_asset.rs:20:47 | 20 | /// Possible errors that can be produced by [`CustomAssetLoader`] | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: public documentation for `BlobAssetLoaderError` links to private item `CustomAssetLoader` --> examples/asset/custom_asset.rs:61:47 | 61 | /// Possible errors that can be produced by [`CustomAssetLoader`] | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` ``` ``` warning: `bevy` (example "mesh2d") generated 1 warning warning: public documentation for `log_layers_ecs` links to private item `update_subscriber` --> examples/app/log_layers_ecs.rs:6:18 | 6 | //! Inside the [`update_subscriber`] function we will create a [`mpsc::Sender`] and a [`mpsc::R... | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: unresolved link to `AdvancedLayer` --> examples/app/log_layers_ecs.rs:7:72 | 7 | ... will go into the [`AdvancedLayer`] and the [`Receiver`](mpsc::Receiver) will | ^^^^^^^^^^^^^ no item named `AdvancedLayer` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: unresolved link to `LogEvents` --> examples/app/log_layers_ecs.rs:8:42 | 8 | //! go into a non-send resource called [`LogEvents`] (It has to be non-send because [`Receiver`... | ^^^^^^^^^ no item named `LogEvents` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` warning: public documentation for `log_layers_ecs` links to private item `transfer_log_events` --> examples/app/log_layers_ecs.rs:9:30 | 9 | //! From there we will use [`transfer_log_events`] to transfer log events from [`LogEvents`] to... | ^^^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: unresolved link to `LogEvents` --> examples/app/log_layers_ecs.rs:9:82 | 9 | ...nsfer log events from [`LogEvents`] to an ECS event called [`LogEvent`]. | ^^^^^^^^^ no item named `LogEvents` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` warning: public documentation for `log_layers_ecs` links to private item `LogEvent` --> examples/app/log_layers_ecs.rs:9:119 | 9 | ...nts`] to an ECS event called [`LogEvent`]. | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: public documentation for `log_layers_ecs` links to private item `LogEvent` --> examples/app/log_layers_ecs.rs:11:49 | 11 | //! Finally, after all that we can access the [`LogEvent`] event from our systems and use it. | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` ``` <details/>
2024-04-14 15:23:44 +00:00
doc-scrape-examples = true
Deferred Renderer (#9258) # Objective - Add a [Deferred Renderer](https://en.wikipedia.org/wiki/Deferred_shading) to Bevy. - This allows subsequent passes to access per pixel material information before/during shading. - Accessing this per pixel material information is needed for some features, like GI. It also makes other features (ex. Decals) simpler to implement and/or improves their capability. There are multiple approaches to accomplishing this. The deferred shading approach works well given the limitations of WebGPU and WebGL2. Motivation: [I'm working on a GI solution for Bevy](https://youtu.be/eH1AkL-mwhI) # Solution - The deferred renderer is implemented with a prepass and a deferred lighting pass. - The prepass renders opaque objects into the Gbuffer attachment (`Rgba32Uint`). The PBR shader generates a `PbrInput` in mostly the same way as the forward implementation and then [packs it into the Gbuffer](https://github.com/DGriffin91/bevy/blob/ec1465559f2c82001830e908fc02ff1d7c2efe51/crates/bevy_pbr/src/render/pbr.wgsl#L168). - The deferred lighting pass unpacks the `PbrInput` and [feeds it into the pbr() function](https://github.com/DGriffin91/bevy/blob/ec1465559f2c82001830e908fc02ff1d7c2efe51/crates/bevy_pbr/src/deferred/deferred_lighting.wgsl#L65), then outputs the shaded color data. - There is now a resource [DefaultOpaqueRendererMethod](https://github.com/DGriffin91/bevy/blob/ec1465559f2c82001830e908fc02ff1d7c2efe51/crates/bevy_pbr/src/material.rs#L599) that can be used to set the default render method for opaque materials. If materials return `None` from [opaque_render_method()](https://github.com/DGriffin91/bevy/blob/ec1465559f2c82001830e908fc02ff1d7c2efe51/crates/bevy_pbr/src/material.rs#L131) the `DefaultOpaqueRendererMethod` will be used. Otherwise, custom materials can also explicitly choose to only support Deferred or Forward by returning the respective [OpaqueRendererMethod](https://github.com/DGriffin91/bevy/blob/ec1465559f2c82001830e908fc02ff1d7c2efe51/crates/bevy_pbr/src/material.rs#L603) - Deferred materials can be used seamlessly along with both opaque and transparent forward rendered materials in the same scene. The [deferred rendering example](https://github.com/DGriffin91/bevy/blob/deferred/examples/3d/deferred_rendering.rs) does this. - The deferred renderer does not support MSAA. If any deferred materials are used, MSAA must be disabled. Both TAA and FXAA are supported. - Deferred rendering supports WebGL2/WebGPU. ## Custom deferred materials - Custom materials can support both deferred and forward at the same time. The [StandardMaterial](https://github.com/DGriffin91/bevy/blob/ec1465559f2c82001830e908fc02ff1d7c2efe51/crates/bevy_pbr/src/render/pbr.wgsl#L166) does this. So does [this example](https://github.com/DGriffin91/bevy_glowy_orb_tutorial/blob/deferred/assets/shaders/glowy.wgsl#L56). - Custom deferred materials that require PBR lighting can create a `PbrInput`, write it to the deferred GBuffer and let it be rendered by the `PBRDeferredLightingPlugin`. - Custom deferred materials that require custom lighting have two options: 1. Use the base_color channel of the `PbrInput` combined with the `STANDARD_MATERIAL_FLAGS_UNLIT_BIT` flag. [Example.](https://github.com/DGriffin91/bevy_glowy_orb_tutorial/blob/deferred/assets/shaders/glowy.wgsl#L56) (If the unlit bit is set, the base_color is stored as RGB9E5 for extra precision) 2. A Custom Deferred Lighting pass can be created, either overriding the default, or running in addition. The a depth buffer is used to limit rendering to only the required fragments for each deferred lighting pass. Materials can set their respective depth id via the [deferred_lighting_pass_id](https://github.com/DGriffin91/bevy/blob/b79182d2a32cac28c4213c2457a53ac2cc885332/crates/bevy_pbr/src/prepass/prepass_io.wgsl#L95) attachment. The custom deferred lighting pass plugin can then set [its corresponding depth](https://github.com/DGriffin91/bevy/blob/ec1465559f2c82001830e908fc02ff1d7c2efe51/crates/bevy_pbr/src/deferred/deferred_lighting.wgsl#L37). Then with the lighting pass using [CompareFunction::Equal](https://github.com/DGriffin91/bevy/blob/ec1465559f2c82001830e908fc02ff1d7c2efe51/crates/bevy_pbr/src/deferred/mod.rs#L335), only the fragments with a depth that equal the corresponding depth written in the material will be rendered. Custom deferred lighting plugins can also be created to render the StandardMaterial. The default deferred lighting plugin can be bypassed with `DefaultPlugins.set(PBRDeferredLightingPlugin { bypass: true })` --------- Co-authored-by: nickrart <nickolas.g.russell@gmail.com>
2023-10-12 22:10:38 +00:00
[package.metadata.example.deferred_rendering]
name = "Deferred Rendering"
description = "Renders meshes with both forward and deferred pipelines"
category = "3D Rendering"
wasm = true
organize examples and add ecs guide
2020-05-01 20:12:47 +00:00
[[example]]
Asset system rework and GLTF scene loading (#693)
2020-10-18 20:48:15 +00:00
name = "load_gltf"
path = "examples/3d/load_gltf.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
organize examples and add ecs guide
2020-05-01 20:12:47 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.load_gltf]
name = "Load glTF"
description = "Loads and renders a glTF file as a scene"
category = "3D Rendering"
wasm = true
add handling of all missing gltf extras: scene, mesh & materials (#13453) # Objective - fixes #4823 ## Solution As outlined in the discussion in the linked issue as the best current solution, this PR adds specific GltfExtras for - scenes - meshes - materials - As it is , it is not a breaking change, I hesitated to rename the current "GltfExtras" component to "PrimitiveGltfExtras", but that would result in a breaking change and might be a bit confusing as to what "primitive" that refers to. ## Testing - I included a bare-bones example & asset (exported gltf file from Blender) with gltf extras at all the relevant levels : scene, mesh, material --- ## Changelog - adds "SceneGltfExtras" injected at the scene level if any - adds "MeshGltfExtras", injected at the mesh level if any - adds "MaterialGltfExtras", injected at the mesh level if any: ie if a mesh has a material that has gltf extras, the component will be injected there.
2024-06-03 13:16:38 +00:00
[[example]]
name = "load_gltf_extras"
path = "examples/3d/load_gltf_extras.rs"
doc-scrape-examples = true
[package.metadata.example.load_gltf_extras]
name = "Load glTF extras"
description = "Loads and renders a glTF file as a scene, including the gltf extras"
category = "3D Rendering"
wasm = true
feat(gltf): add name component to gltf mesh primitive (#13912) # Objective - fixes https://github.com/bevyengine/bevy/issues/13473 ## Solution - When a single mesh is assigned multiple materials, it is divided into several primitive nodes, with each primitive assigned a unique material. Presently, these primitives are named using the format Mesh.index, which complicates querying. To improve this, we can assign a specific name to each primitive based on the material’s name, since each primitive corresponds to one material exclusively. ## Testing - I have included a simple example which shows how to query a material and mesh part based on the new name component. ## Changelog - adds `GltfMaterialName` component to the mesh entity of the gltf primitive node. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2024-09-30 16:51:52 +00:00
[[example]]
name = "query_gltf_primitives"
path = "examples/3d/query_gltf_primitives.rs"
doc-scrape-examples = true
[package.metadata.example.query_gltf_primitives]
name = "Query glTF primitives"
description = "Query primitives in a glTF scene"
category = "3D Rendering"
wasm = true
Per-Object Motion Blur (#9924) https://github.com/bevyengine/bevy/assets/2632925/e046205e-3317-47c3-9959-fc94c529f7e0 # Objective - Adds per-object motion blur to the core 3d pipeline. This is a common effect used in games and other simulations. - Partially resolves #4710 ## Solution - This is a post-process effect that uses the depth and motion vector buffers to estimate per-object motion blur. The implementation is combined from knowledge from multiple papers and articles. The approach itself, and the shader are quite simple. Most of the effort was in wiring up the bevy rendering plumbing, and properly specializing for HDR and MSAA. - To work with MSAA, the MULTISAMPLED_SHADING wgpu capability is required. I've extracted this code from #9000. This is because the prepass buffers are multisampled, and require accessing with `textureLoad` as opposed to the widely compatible `textureSample`. - Added an example to demonstrate the effect of motion blur parameters. ## Future Improvements - While this approach does have limitations, it's one of the most commonly used, and is much better than camera motion blur, which does not consider object velocity. For example, this implementation allows a dolly to track an object, and that object will remain unblurred while the background is blurred. The biggest issue with this implementation is that blur is constrained to the boundaries of objects which results in hard edges. There are solutions to this by either dilating the object or the motion vector buffer, or by taking a different approach such as https://casual-effects.com/research/McGuire2012Blur/index.html - I'm using a noise PRNG function to jitter samples. This could be replaced with a blue noise texture lookup or similar, however after playing with the parameters, it gives quite nice results with 4 samples, and is significantly better than the artifacts generated when not jittering. --- ## Changelog - Added: per-object motion blur. This can be enabled and configured by adding the `MotionBlurBundle` to a camera entity. --------- Co-authored-by: Torstein Grindvik <52322338+torsteingrindvik@users.noreply.github.com>
2024-04-25 01:16:02 +00:00
[[example]]
name = "motion_blur"
path = "examples/3d/motion_blur.rs"
doc-scrape-examples = true
[package.metadata.example.motion_blur]
name = "Motion Blur"
description = "Demonstrates per-pixel motion blur"
category = "3D Rendering"
wasm = false
Add Order Independent Transparency (#14876) # Objective - Alpha blending can easily fail in many situations and requires sorting on the cpu ## Solution - Implement order independent transparency (OIT) as an alternative to alpha blending - The implementation uses 2 passes - The first pass records all the fragments colors and position to a buffer that is the size of N layers * the render target resolution. - The second pass sorts the fragments, blends them and draws them to the screen. It also currently does manual depth testing because early-z fails in too many cases in the first pass. ## Testing - We've been using this implementation at foresight in production for many months now and we haven't had any issues related to OIT. --- ## Showcase ![image](https://github.com/user-attachments/assets/157f3e32-adaf-4782-b25b-c10313b9bc43) ![image](https://github.com/user-attachments/assets/bef23258-0c22-4b67-a0b8-48a9f571c44f) ## Future work - Add an example showing how to use OIT for a custom material - Next step would be to implement a per-pixel linked list to reduce memory use - I'd also like to investigate using a BinnedRenderPhase instead of a SortedRenderPhase. If it works, it would make the transparent pass significantly faster. --------- Co-authored-by: Kristoffer Søholm <k.soeholm@gmail.com> Co-authored-by: JMS55 <47158642+JMS55@users.noreply.github.com> Co-authored-by: Charlotte McElwain <charlotte.c.mcelwain@gmail.com>
2024-10-07 23:50:28 +00:00
[[example]]
name = "order_independent_transparency"
path = "examples/3d/order_independent_transparency.rs"
doc-scrape-examples = true
[package.metadata.example.order_independent_transparency]
name = "Order Independent Transparency"
description = "Demonstrates how to use OIT"
category = "3D Rendering"
wasm = false
Initial tonemapping options (#7594) # Objective Splits tone mapping from https://github.com/bevyengine/bevy/pull/6677 into a separate PR. Address https://github.com/bevyengine/bevy/issues/2264. Adds tone mapping options: - None: Bypasses tonemapping for instances where users want colors output to match those set. - Reinhard - Reinhard Luminance: Bevy's exiting tonemapping - [ACES](https://github.com/TheRealMJP/BakingLab/blob/master/BakingLab/ACES.hlsl) (Fitted version, based on the same implementation that Godot 4 uses) see https://github.com/bevyengine/bevy/issues/2264 - [AgX](https://github.com/sobotka/AgX) - SomewhatBoringDisplayTransform - TonyMcMapface - Blender Filmic This PR also adds support for EXR images so they can be used to compare tonemapping options with reference images. ## Migration Guide - Tonemapping is now an enum with NONE and the various tonemappers. - The DebandDither is now a separate component. Co-authored-by: JMS55 <47158642+JMS55@users.noreply.github.com>
2023-02-19 20:38:13 +00:00
[[example]]
name = "tonemapping"
path = "examples/3d/tonemapping.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Initial tonemapping options (#7594) # Objective Splits tone mapping from https://github.com/bevyengine/bevy/pull/6677 into a separate PR. Address https://github.com/bevyengine/bevy/issues/2264. Adds tone mapping options: - None: Bypasses tonemapping for instances where users want colors output to match those set. - Reinhard - Reinhard Luminance: Bevy's exiting tonemapping - [ACES](https://github.com/TheRealMJP/BakingLab/blob/master/BakingLab/ACES.hlsl) (Fitted version, based on the same implementation that Godot 4 uses) see https://github.com/bevyengine/bevy/issues/2264 - [AgX](https://github.com/sobotka/AgX) - SomewhatBoringDisplayTransform - TonyMcMapface - Blender Filmic This PR also adds support for EXR images so they can be used to compare tonemapping options with reference images. ## Migration Guide - Tonemapping is now an enum with NONE and the various tonemappers. - The DebandDither is now a separate component. Co-authored-by: JMS55 <47158642+JMS55@users.noreply.github.com>
2023-02-19 20:38:13 +00:00
[package.metadata.example.tonemapping]
name = "Tonemapping"
description = "Compares tonemapping options"
category = "3D Rendering"
wasm = true
3D OrthographicProjection improvements + new example (#1361) * use `length_squared` for visible entities * ortho projection 2d/3d different depth calculation * use ScalingMode::FixedVertical for 3d ortho * new example: 3d orthographic
2021-02-01 00:22:06 +00:00
[[example]]
name = "orthographic"
path = "examples/3d/orthographic.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
3D OrthographicProjection improvements + new example (#1361) * use `length_squared` for visible entities * ortho projection 2d/3d different depth calculation * use ScalingMode::FixedVertical for 3d ortho * new example: 3d orthographic
2021-02-01 00:22:06 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.orthographic]
name = "Orthographic View"
description = "Shows how to create a 3D orthographic view (for isometric-look in games or CAD applications)"
category = "3D Rendering"
wasm = true
organize examples and add ecs guide
2020-05-01 20:12:47 +00:00
[[example]]
name = "parenting"
path = "examples/3d/parenting.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
organize examples and add ecs guide
2020-05-01 20:12:47 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.parenting]
name = "Parenting"
description = "Demonstrates parent->child relationships and relative transformations"
category = "3D Rendering"
wasm = true
Rebase of existing PBR work (#1554) This is a rebase of StarArawns PBR work from #261 with IngmarBitters work from #1160 cherry-picked on top. I had to make a few minor changes to make some intermediate commits compile and the end result is not yet 100% what I expected, so there's a bit more work to do. Co-authored-by: John Mitchell <toasterthegamer@gmail.com> Co-authored-by: Ingmar Bitter <ingmar.bitter@gmail.com>
2021-03-20 03:22:33 +00:00
[[example]]
name = "pbr"
path = "examples/3d/pbr.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Rebase of existing PBR work (#1554) This is a rebase of StarArawns PBR work from #261 with IngmarBitters work from #1160 cherry-picked on top. I had to make a few minor changes to make some intermediate commits compile and the end result is not yet 100% what I expected, so there's a bit more work to do. Co-authored-by: John Mitchell <toasterthegamer@gmail.com> Co-authored-by: Ingmar Bitter <ingmar.bitter@gmail.com>
2021-03-20 03:22:33 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.pbr]
name = "Physically Based Rendering"
description = "Demonstrates use of Physically Based Rendering (PBR) properties"
category = "3D Rendering"
wasm = true
Add parallax mapping to bevy PBR (#5928) # Objective Add a [parallax mapping] shader to bevy. Please note that this is a 3d technique, NOT a 2d sidescroller feature. ## Solution - Add related fields to `StandardMaterial` - update the pbr shader - Add an example taking advantage of parallax mapping A pre-existing implementation exists at: https://github.com/nicopap/bevy_mod_paramap/ The implementation is derived from: https://web.archive.org/web/20150419215321/http://sunandblackcat.com/tipFullView.php?l=eng&topicid=28 Further discussion on literature is found in the `bevy_mod_paramap` README. ### Limitations - The mesh silhouette isn't affected by the depth map. - The depth of the pixel does not reflect its visual position, resulting in artifacts for depth-dependent features such as fog or SSAO - GLTF does not define a height map texture, so somehow the user will always need to work around this limitation, though [an extension is in the works][gltf] ### Future work - It's possible to update the depth in the depth buffer to follow the parallaxed texture. This would enable interop with depth-based visual effects, it also allows `discard`ing pixels of materials when computed depth is higher than the one in depth buffer - Cheap lower quality single-sample method using [offset limiting] - Add distance fading, to disable parallaxing (relatively expensive) on distant objects - GLTF extension to allow defining height maps. Or a workaround implemented through a blender plugin to the GLTF exporter that uses the `extras` field to add height map. - [Quadratic surface vertex attributes][oliveira_3] to enable parallax mapping on bending surfaces and allow clean silhouetting. - noise based sampling, to limit the pancake artifacts. - Cone mapping ([GPU gems], [Simcity (2013)][simcity]). Requires preprocessing, increase depth map size, reduces sample count greatly. - [Quadtree parallax mapping][qpm] (also requires preprocessing) - Self-shadowing of parallax-mapped surfaces by modifying the shadow map - Generate depth map from normal map [link to slides], [blender question] https://user-images.githubusercontent.com/26321040/223563792-dffcc6ab-70e8-4ff9-90d1-b36c338695ad.mp4 [blender question]: https://blender.stackexchange.com/questions/89278/how-to-get-a-smooth-curvature-map-from-a-normal-map [link to slides]: https://developer.download.nvidia.com/assets/gamedev/docs/nmap2displacement.pdf [oliveira_3]: https://www.inf.ufrgs.br/~oliveira/pubs_files/Oliveira_Policarpo_RP-351_Jan_2005.pdf [GPU gems]: https://developer.nvidia.com/gpugems/gpugems3/part-iii-rendering/chapter-18-relaxed-cone-stepping-relief-mapping [simcity]: https://community.simtropolis.com/omnibus/other-games/building-and-rendering-simcity-2013-r247/ [offset limiting]: https://raw.githubusercontent.com/marcusstenbeck/tncg14-parallax-mapping/master/documents/Parallax%20Mapping%20with%20Offset%20Limiting%20-%20A%20Per-Pixel%20Approximation%20of%20Uneven%20Surfaces.pdf [gltf]: https://github.com/KhronosGroup/glTF/pull/2196 [qpm]: https://www.gamedevs.org/uploads/quadtree-displacement-mapping-with-height-blending.pdf --- ## Changelog - Add a `depth_map` field to the `StandardMaterial`, it is a grayscale image where white represents bottom and black the top. If `depth_map` is set, bevy's pbr shader will use it to do [parallax mapping] to give an increased feel of depth to the material. This is similar to a displacement map, but with infinite precision at fairly low cost. - The fields `parallax_mapping_method`, `parallax_depth_scale` and `max_parallax_layer_count` allow finer grained control over the behavior of the parallax shader. - Add the `parallax_mapping` example to show off the effect. [parallax mapping]: https://en.wikipedia.org/wiki/Parallax_mapping --------- Co-authored-by: Robert Swain <robert.swain@gmail.com>
2023-04-15 10:25:14 +00:00
[[example]]
name = "parallax_mapping"
path = "examples/3d/parallax_mapping.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add parallax mapping to bevy PBR (#5928) # Objective Add a [parallax mapping] shader to bevy. Please note that this is a 3d technique, NOT a 2d sidescroller feature. ## Solution - Add related fields to `StandardMaterial` - update the pbr shader - Add an example taking advantage of parallax mapping A pre-existing implementation exists at: https://github.com/nicopap/bevy_mod_paramap/ The implementation is derived from: https://web.archive.org/web/20150419215321/http://sunandblackcat.com/tipFullView.php?l=eng&topicid=28 Further discussion on literature is found in the `bevy_mod_paramap` README. ### Limitations - The mesh silhouette isn't affected by the depth map. - The depth of the pixel does not reflect its visual position, resulting in artifacts for depth-dependent features such as fog or SSAO - GLTF does not define a height map texture, so somehow the user will always need to work around this limitation, though [an extension is in the works][gltf] ### Future work - It's possible to update the depth in the depth buffer to follow the parallaxed texture. This would enable interop with depth-based visual effects, it also allows `discard`ing pixels of materials when computed depth is higher than the one in depth buffer - Cheap lower quality single-sample method using [offset limiting] - Add distance fading, to disable parallaxing (relatively expensive) on distant objects - GLTF extension to allow defining height maps. Or a workaround implemented through a blender plugin to the GLTF exporter that uses the `extras` field to add height map. - [Quadratic surface vertex attributes][oliveira_3] to enable parallax mapping on bending surfaces and allow clean silhouetting. - noise based sampling, to limit the pancake artifacts. - Cone mapping ([GPU gems], [Simcity (2013)][simcity]). Requires preprocessing, increase depth map size, reduces sample count greatly. - [Quadtree parallax mapping][qpm] (also requires preprocessing) - Self-shadowing of parallax-mapped surfaces by modifying the shadow map - Generate depth map from normal map [link to slides], [blender question] https://user-images.githubusercontent.com/26321040/223563792-dffcc6ab-70e8-4ff9-90d1-b36c338695ad.mp4 [blender question]: https://blender.stackexchange.com/questions/89278/how-to-get-a-smooth-curvature-map-from-a-normal-map [link to slides]: https://developer.download.nvidia.com/assets/gamedev/docs/nmap2displacement.pdf [oliveira_3]: https://www.inf.ufrgs.br/~oliveira/pubs_files/Oliveira_Policarpo_RP-351_Jan_2005.pdf [GPU gems]: https://developer.nvidia.com/gpugems/gpugems3/part-iii-rendering/chapter-18-relaxed-cone-stepping-relief-mapping [simcity]: https://community.simtropolis.com/omnibus/other-games/building-and-rendering-simcity-2013-r247/ [offset limiting]: https://raw.githubusercontent.com/marcusstenbeck/tncg14-parallax-mapping/master/documents/Parallax%20Mapping%20with%20Offset%20Limiting%20-%20A%20Per-Pixel%20Approximation%20of%20Uneven%20Surfaces.pdf [gltf]: https://github.com/KhronosGroup/glTF/pull/2196 [qpm]: https://www.gamedevs.org/uploads/quadtree-displacement-mapping-with-height-blending.pdf --- ## Changelog - Add a `depth_map` field to the `StandardMaterial`, it is a grayscale image where white represents bottom and black the top. If `depth_map` is set, bevy's pbr shader will use it to do [parallax mapping] to give an increased feel of depth to the material. This is similar to a displacement map, but with infinite precision at fairly low cost. - The fields `parallax_mapping_method`, `parallax_depth_scale` and `max_parallax_layer_count` allow finer grained control over the behavior of the parallax shader. - Add the `parallax_mapping` example to show off the effect. [parallax mapping]: https://en.wikipedia.org/wiki/Parallax_mapping --------- Co-authored-by: Robert Swain <robert.swain@gmail.com>
2023-04-15 10:25:14 +00:00
[package.metadata.example.parallax_mapping]
name = "Parallax Mapping"
description = "Demonstrates use of a normal map and depth map for parallax mapping"
category = "3D Rendering"
wasm = true
Add support for vertex colors (#4528) # Objective Add support for vertex colors ## Solution This change is modeled after how vertex tangents are handled, so the shader is conditionally compiled with vertex color support if the mesh has the corresponding attribute set. Vertex colors are multiplied by the base color. I'm not sure if this is the best for all cases, but may be useful for modifying vertex colors without creating a new mesh. I chose `VertexFormat::Float32x4`, but I'd prefer 16-bit floats if/when support is added. ## Changelog ### Added - Vertex colors can be specified using the `Mesh::ATTRIBUTE_COLOR` mesh attribute.
2022-05-05 00:46:32 +00:00
[[example]]
name = "render_to_texture"
path = "examples/3d/render_to_texture.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add support for vertex colors (#4528) # Objective Add support for vertex colors ## Solution This change is modeled after how vertex tangents are handled, so the shader is conditionally compiled with vertex color support if the mesh has the corresponding attribute set. Vertex colors are multiplied by the base color. I'm not sure if this is the best for all cases, but may be useful for modifying vertex colors without creating a new mesh. I chose `VertexFormat::Float32x4`, but I'd prefer 16-bit floats if/when support is added. ## Changelog ### Added - Vertex colors can be specified using the `Mesh::ATTRIBUTE_COLOR` mesh attribute.
2022-05-05 00:46:32 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.render_to_texture]
name = "Render to Texture"
description = "Shows how to render to a texture, useful for mirrors, UI, or exporting images"
category = "3D Rendering"
wasm = true
bevy_pbr2: Add support for most of the StandardMaterial textures (#4) * bevy_pbr2: Add support for most of the StandardMaterial textures Normal maps are not included here as they require tangents in a vertex attribute. * bevy_pbr2: Ensure RenderCommandQueue is ready for PbrShaders init * texture_pipelined: Add a light to the scene so we can see stuff * WIP bevy_pbr2: back to front sorting hack * bevy_pbr2: Uniform control flow for texture sampling in pbr.frag From 'fintelia' on the Bevy Render Rework Round 2 discussion: "My understanding is that GPUs these days never use the "execute both branches and select the result" strategy. Rather, what they do is evaluate the branch condition on all threads of a warp, and jump over it if all of them evaluate to false. If even a single thread needs to execute the if statement body, however, then the remaining threads are paused until that is completed." * bevy_pbr2: Simplify texture and sampler names The StandardMaterial_ prefix is no longer needed * bevy_pbr2: Match default 'AmbientColor' of current bevy_pbr for now * bevy_pbr2: Convert from non-linear to linear sRGB for the color uniform * bevy_pbr2: Add pbr_pipelined example * Fix view vector in pbr frag to work in ortho * bevy_pbr2: Use a 90 degree y fov and light range projection for lights * bevy_pbr2: Add AmbientLight resource * bevy_pbr2: Convert PointLight color to linear sRGB for use in fragment shader * bevy_pbr2: pbr.frag: Rename PointLight.projection to view_projection The uniform contains the view_projection matrix so this was incorrect. * bevy_pbr2: PointLight is an OmniLight as it has a radius * bevy_pbr2: Factoring out duplicated code * bevy_pbr2: Implement RenderAsset for StandardMaterial * Remove unnecessary texture and sampler clones * fix comment formatting * remove redundant Buffer:from * Don't extract meshes when their material textures aren't ready * make missing textures in the queue step an error Co-authored-by: Aevyrie <aevyrie@gmail.com> Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2021-06-27 23:10:23 +00:00
[[example]]
Replace old renderer with new renderer (#3312) This makes the [New Bevy Renderer](#2535) the default (and only) renderer. The new renderer isn't _quite_ ready for the final release yet, but I want as many people as possible to start testing it so we can identify bugs and address feedback prior to release. The examples are all ported over and operational with a few exceptions: * I removed a good portion of the examples in the `shader` folder. We still have some work to do in order to make these examples possible / ergonomic / worthwhile: #3120 and "high level shader material plugins" are the big ones. This is a temporary measure. * Temporarily removed the multiple_windows example: doing this properly in the new renderer will require the upcoming "render targets" changes. Same goes for the render_to_texture example. * Removed z_sort_debug: entity visibility sort info is no longer available in app logic. we could do this on the "render app" side, but i dont consider it a priority.
2021-12-14 03:58:23 +00:00
name = "shadow_biases"
path = "examples/3d/shadow_biases.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Scale normal bias by texel size (#26) * 3d_scene_pipelined: Use a shallower directional light angle to provoke acne * cornell_box_pipelined: Remove bias tweaks * bevy_pbr2: Simplify shadow biases by moving them to linear depth * bevy_pbr2: Do not use DepthBiasState * bevy_pbr2: Do not use bilinear filtering for sampling depth textures * pbr.wgsl: Remove unnecessary comment * bevy_pbr2: Do manual shadow map depth comparisons for more flexibility * examples: Add shadow_biases_pipelined example This is useful for stress testing biases. * bevy_pbr2: Scale the point light normal bias by the shadow map texel size This allows the normal bias to be small close to the light source where the shadow map texel to screen texel ratio is high, but is appropriately large further away from the light source where the shadow map texel can easily cover multiple screen texels. * shadow_biases_pipelined: Add support for toggling directional / point light * shadow_biases_pipelined: Cleanup * bevy_pbr2: Scale the directional light normal bias by the shadow map texel size * shadow_biases_pipelined: Fit the orthographic projection around the scene * bevy_pbr2: Directional lights should have no shadows outside their projection Before this change, sampling a fragment position from outside the ndc volume would result in the return sample being clamped to the edge in x,y or possibly always casting a shadow for fragment positions past the orthographic projection's far plane. * bevy_pbr2: Fix the default directional light normal bias * Revert "bevy_pbr2: Do manual shadow map depth comparisons for more flexibility" This reverts commit 7df1bab38a42d8a33bc50ca583d4be37bd9c9f0d. * shadow_biases_pipelined: Adjust directional light normal bias in 0.1 increments * pbr.wgsl: Add a couple of clarifying comments * Revert "bevy_pbr2: Do not use bilinear filtering for sampling depth textures" This reverts commit f53baab0232ce218866a45cad6902b470f4cf2c4. * shadow_biases_pipelined: Print usage to terminal
2021-07-19 19:20:59 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.shadow_biases]
name = "Shadow Biases"
description = "Demonstrates how shadow biases affect shadows in a 3d scene"
category = "3D Rendering"
wasm = true
bevy_pbr2: Add support for not casting/receiving shadows (#2726) # Objective Allow marking meshes as not casting / receiving shadows. ## Solution - Added `NotShadowCaster` and `NotShadowReceiver` zero-sized type components. - Extract these components into `bool`s in `ExtractedMesh` - Only generate `DrawShadowMesh` `Drawable`s for meshes _without_ `NotShadowCaster` - Add a `u32` bit `flags` member to `MeshUniform` with one flag indicating whether the mesh is a shadow receiver - If a mesh does _not_ have the `NotShadowReceiver` component, then it is a shadow receiver, and so the bit in the `MeshUniform` is set, otherwise it is not set. - Added an example illustrating the functionality. NOTE: I wanted to have the default state of a mesh as being a shadow caster and shadow receiver, hence the `Not*` components. However, I am on the fence about this. I don't want to have a negative performance impact, nor have people wondering why their custom meshes don't have shadows because they forgot to add `ShadowCaster` and `ShadowReceiver` components, but I also really don't like the double negatives the `Not*` approach incurs. What do you think? Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2021-08-25 19:44:20 +00:00
[[example]]
Replace old renderer with new renderer (#3312) This makes the [New Bevy Renderer](#2535) the default (and only) renderer. The new renderer isn't _quite_ ready for the final release yet, but I want as many people as possible to start testing it so we can identify bugs and address feedback prior to release. The examples are all ported over and operational with a few exceptions: * I removed a good portion of the examples in the `shader` folder. We still have some work to do in order to make these examples possible / ergonomic / worthwhile: #3120 and "high level shader material plugins" are the big ones. This is a temporary measure. * Temporarily removed the multiple_windows example: doing this properly in the new renderer will require the upcoming "render targets" changes. Same goes for the render_to_texture example. * Removed z_sort_debug: entity visibility sort info is no longer available in app logic. we could do this on the "render app" side, but i dont consider it a priority.
2021-12-14 03:58:23 +00:00
name = "shadow_caster_receiver"
path = "examples/3d/shadow_caster_receiver.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
organize examples and add ecs guide
2020-05-01 20:12:47 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.shadow_caster_receiver]
name = "Shadow Caster and Receiver"
description = "Demonstrates how to prevent meshes from casting/receiving shadows in a 3d scene"
category = "3D Rendering"
wasm = true
Support array / cubemap / cubemap array textures in KTX2 (#5325) # Objective - Fix / support KTX2 array / cubemap / cubemap array textures - Fixes #4495 . Supersedes #4514 . ## Solution - Add `Option<TextureViewDescriptor>` to `Image` to enable configuration of the `TextureViewDimension` of a texture. - This allows users to set `D2Array`, `D3`, `Cube`, `CubeArray` or whatever they need - Automatically configure this when loading KTX2 - Transcode all layers and faces instead of just one - Use the UASTC block size of 128 bits, and the number of blocks in x/y for a given mip level in order to determine the offset of the layer and face within the KTX2 mip level data - `wgpu` wants data ordered as layer 0 mip 0..n, layer 1 mip 0..n, etc. See https://docs.rs/wgpu/latest/wgpu/util/trait.DeviceExt.html#tymethod.create_texture_with_data - Reorder the data KTX2 mip X layer Y face Z to `wgpu` layer Y face Z mip X order - Add a `skybox` example to demonstrate / test loading cubemaps from PNG and KTX2, including ASTC 4x4, BC7, and ETC2 compression for support everywhere. Note that you need to enable the `ktx2,zstd` features to be able to load the compressed textures. --- ## Changelog - Fixed: KTX2 array / cubemap / cubemap array textures - Fixes: Validation failure for compressed textures stored in KTX2 where the width/height are not a multiple of the block dimensions. - Added: `Image` now has an `Option<TextureViewDescriptor>` field to enable configuration of the texture view. This is useful for configuring the `TextureViewDimension` when it is not just a plain 2D texture and the loader could/did not identify what it should be. Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-07-30 07:02:58 +00:00
[[example]]
name = "skybox"
path = "examples/3d/skybox.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Support array / cubemap / cubemap array textures in KTX2 (#5325) # Objective - Fix / support KTX2 array / cubemap / cubemap array textures - Fixes #4495 . Supersedes #4514 . ## Solution - Add `Option<TextureViewDescriptor>` to `Image` to enable configuration of the `TextureViewDimension` of a texture. - This allows users to set `D2Array`, `D3`, `Cube`, `CubeArray` or whatever they need - Automatically configure this when loading KTX2 - Transcode all layers and faces instead of just one - Use the UASTC block size of 128 bits, and the number of blocks in x/y for a given mip level in order to determine the offset of the layer and face within the KTX2 mip level data - `wgpu` wants data ordered as layer 0 mip 0..n, layer 1 mip 0..n, etc. See https://docs.rs/wgpu/latest/wgpu/util/trait.DeviceExt.html#tymethod.create_texture_with_data - Reorder the data KTX2 mip X layer Y face Z to `wgpu` layer Y face Z mip X order - Add a `skybox` example to demonstrate / test loading cubemaps from PNG and KTX2, including ASTC 4x4, BC7, and ETC2 compression for support everywhere. Note that you need to enable the `ktx2,zstd` features to be able to load the compressed textures. --- ## Changelog - Fixed: KTX2 array / cubemap / cubemap array textures - Fixes: Validation failure for compressed textures stored in KTX2 where the width/height are not a multiple of the block dimensions. - Added: `Image` now has an `Option<TextureViewDescriptor>` field to enable configuration of the texture view. This is useful for configuring the `TextureViewDimension` when it is not just a plain 2D texture and the loader could/did not identify what it should be. Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-07-30 07:02:58 +00:00
[package.metadata.example.skybox]
name = "Skybox"
description = "Load a cubemap texture onto a cube like a skybox and cycle through different compressed texture formats."
category = "3D Rendering"
wasm = false
Spherical area lights example (#3498) I was putting together the Bevy 0.6 release blog post and wanted a simple area light radius example, so here we are :) ![image](https://user-images.githubusercontent.com/2694663/147786883-63454290-b5b1-4456-9762-0b0b47e16bb5.png)
2021-12-30 21:07:26 +00:00
[[example]]
name = "spherical_area_lights"
path = "examples/3d/spherical_area_lights.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Spherical area lights example (#3498) I was putting together the Bevy 0.6 release blog post and wanted a simple area light radius example, so here we are :) ![image](https://user-images.githubusercontent.com/2694663/147786883-63454290-b5b1-4456-9762-0b0b47e16bb5.png)
2021-12-30 21:07:26 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.spherical_area_lights]
name = "Spherical Area Lights"
description = "Demonstrates how point light radius values affect light behavior"
category = "3D Rendering"
wasm = true
Camera Driven Viewports (#4898) # Objective Users should be able to render cameras to specific areas of a render target, which enables scenarios like split screen, minimaps, etc. Builds on the new Camera Driven Rendering added here: #4745 Fixes: #202 Alternative to #1389 and #3626 (which are incompatible with the new Camera Driven Rendering) ## Solution ![image](https://user-images.githubusercontent.com/2694663/171560044-f0694f67-0cd9-4598-83e2-a9658c4fed57.png) Cameras can now configure an optional "viewport", which defines a rectangle within their render target to draw to. If a `Viewport` is defined, the camera's `CameraProjection`, `View`, and visibility calculations will use the viewport configuration instead of the full render target. ```rust // This camera will render to the first half of the primary window (on the left side). commands.spawn_bundle(Camera3dBundle { camera: Camera { viewport: Some(Viewport { physical_position: UVec2::new(0, 0), physical_size: UVec2::new(window.physical_width() / 2, window.physical_height()), depth: 0.0..1.0, }), ..default() }, ..default() }); ``` To account for this, the `Camera` component has received a few adjustments: * `Camera` now has some new getter functions: * `logical_viewport_size`, `physical_viewport_size`, `logical_target_size`, `physical_target_size`, `projection_matrix` * All computed camera values are now private and live on the `ComputedCameraValues` field (logical/physical width/height, the projection matrix). They are now exposed on `Camera` via getters/setters This wasn't _needed_ for viewports, but it was long overdue. --- ## Changelog ### Added * `Camera` components now have a `viewport` field, which can be set to draw to a portion of a render target instead of the full target. * `Camera` component has some new functions: `logical_viewport_size`, `physical_viewport_size`, `logical_target_size`, `physical_target_size`, and `projection_matrix` * Added a new split_screen example illustrating how to render two cameras to the same scene ## Migration Guide `Camera::projection_matrix` is no longer a public field. Use the new `Camera::projection_matrix()` method instead: ```rust // Bevy 0.7 let projection = camera.projection_matrix; // Bevy 0.8 let projection = camera.projection_matrix(); ```
2022-06-05 00:27:49 +00:00
[[example]]
name = "split_screen"
path = "examples/3d/split_screen.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Camera Driven Viewports (#4898) # Objective Users should be able to render cameras to specific areas of a render target, which enables scenarios like split screen, minimaps, etc. Builds on the new Camera Driven Rendering added here: #4745 Fixes: #202 Alternative to #1389 and #3626 (which are incompatible with the new Camera Driven Rendering) ## Solution ![image](https://user-images.githubusercontent.com/2694663/171560044-f0694f67-0cd9-4598-83e2-a9658c4fed57.png) Cameras can now configure an optional "viewport", which defines a rectangle within their render target to draw to. If a `Viewport` is defined, the camera's `CameraProjection`, `View`, and visibility calculations will use the viewport configuration instead of the full render target. ```rust // This camera will render to the first half of the primary window (on the left side). commands.spawn_bundle(Camera3dBundle { camera: Camera { viewport: Some(Viewport { physical_position: UVec2::new(0, 0), physical_size: UVec2::new(window.physical_width() / 2, window.physical_height()), depth: 0.0..1.0, }), ..default() }, ..default() }); ``` To account for this, the `Camera` component has received a few adjustments: * `Camera` now has some new getter functions: * `logical_viewport_size`, `physical_viewport_size`, `logical_target_size`, `physical_target_size`, `projection_matrix` * All computed camera values are now private and live on the `ComputedCameraValues` field (logical/physical width/height, the projection matrix). They are now exposed on `Camera` via getters/setters This wasn't _needed_ for viewports, but it was long overdue. --- ## Changelog ### Added * `Camera` components now have a `viewport` field, which can be set to draw to a portion of a render target instead of the full target. * `Camera` component has some new functions: `logical_viewport_size`, `physical_viewport_size`, `logical_target_size`, `physical_target_size`, and `projection_matrix` * Added a new split_screen example illustrating how to render two cameras to the same scene ## Migration Guide `Camera::projection_matrix` is no longer a public field. Use the new `Camera::projection_matrix()` method instead: ```rust // Bevy 0.7 let projection = camera.projection_matrix; // Bevy 0.8 let projection = camera.projection_matrix(); ```
2022-06-05 00:27:49 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.split_screen]
name = "Split Screen"
description = "Demonstrates how to render two cameras to the same window to accomplish \"split screen\""
category = "3D Rendering"
wasm = true
organize examples and add ecs guide
2020-05-01 20:12:47 +00:00
[[example]]
name = "texture"
path = "examples/3d/texture.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
organize examples and add ecs guide
2020-05-01 20:12:47 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.texture]
name = "Texture"
description = "Shows configuration of texture materials"
category = "3D Rendering"
wasm = true
Add transparency examples (#3695) Adds examples demonstrating transparency for 2d, 3d and UI. Fixes #3215.
2022-06-06 17:52:09 +00:00
[[example]]
name = "transparency_3d"
path = "examples/3d/transparency_3d.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add transparency examples (#3695) Adds examples demonstrating transparency for 2d, 3d and UI. Fixes #3215.
2022-06-06 17:52:09 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.transparency_3d]
name = "Transparency in 3D"
description = "Demonstrates transparency in 3d"
category = "3D Rendering"
wasm = true
`StandardMaterial` Light Transmission (#8015) # Objective <img width="1920" alt="Screenshot 2023-04-26 at 01 07 34" src="https://user-images.githubusercontent.com/418473/234467578-0f34187b-5863-4ea1-88e9-7a6bb8ce8da3.png"> This PR adds both diffuse and specular light transmission capabilities to the `StandardMaterial`, with support for screen space refractions. This enables realistically representing a wide range of real-world materials, such as: - Glass; (Including frosted glass) - Transparent and translucent plastics; - Various liquids and gels; - Gemstones; - Marble; - Wax; - Paper; - Leaves; - Porcelain. Unlike existing support for transparency, light transmission does not rely on fixed function alpha blending, and therefore works with both `AlphaMode::Opaque` and `AlphaMode::Mask` materials. ## Solution - Introduces a number of transmission related fields in the `StandardMaterial`; - For specular transmission: - Adds logic to take a view main texture snapshot after the opaque phase; (in order to perform screen space refractions) - Introduces a new `Transmissive3d` phase to the renderer, to which all meshes with `transmission > 0.0` materials are sent. - Calculates a light exit point (of the approximate mesh volume) using `ior` and `thickness` properties - Samples the snapshot texture with an adaptive number of taps across a `roughness`-controlled radius enabling “blurry” refractions - For diffuse transmission: - Approximates transmitted diffuse light by using a second, flipped + displaced, diffuse-only Lambertian lobe for each light source. ## To Do - [x] Figure out where `fresnel_mix()` is taking place, if at all, and where `dielectric_specular` is being calculated, if at all, and update them to use the `ior` value (Not a blocker, just a nice-to-have for more correct BSDF) - To the _best of my knowledge, this is now taking place, after 964340cdd. The fresnel mix is actually "split" into two parts in our implementation, one `(1 - fresnel(...))` in the transmission, and `fresnel()` in the light implementations. A surface with more reflectance now will produce slightly dimmer transmission towards the grazing angle, as more of the light gets reflected. - [x] Add `transmission_texture` - [x] Add `diffuse_transmission_texture` - [x] Add `thickness_texture` - [x] Add `attenuation_distance` and `attenuation_color` - [x] Connect values to glTF loader - [x] `transmission` and `transmission_texture` - [x] `thickness` and `thickness_texture` - [x] `ior` - [ ] `diffuse_transmission` and `diffuse_transmission_texture` (needs upstream support in `gltf` crate, not a blocker) - [x] Add support for multiple screen space refraction “steps” - [x] Conditionally create no transmission snapshot texture at all if `steps == 0` - [x] Conditionally enable/disable screen space refraction transmission snapshots - [x] Read from depth pre-pass to prevent refracting pixels in front of the light exit point - [x] Use `interleaved_gradient_noise()` function for sampling blur in a way that benefits from TAA - [x] Drill down a TAA `#define`, tweak some aspects of the effect conditionally based on it - [x] Remove const array that's crashing under HLSL (unless a new `naga` release with https://github.com/gfx-rs/naga/pull/2496 comes out before we merge this) - [ ] Look into alternatives to the `switch` hack for dynamically indexing the const array (might not be needed, compilers seem to be decent at expanding it) - [ ] Add pipeline keys for gating transmission (do we really want/need this?) - [x] Tweak some material field/function names? ## A Note on Texture Packing _This was originally added as a comment to the `specular_transmission_texture`, `thickness_texture` and `diffuse_transmission_texture` documentation, I removed it since it was more confusing than helpful, and will likely be made redundant/will need to be updated once we have a better infrastructure for preprocessing assets_ Due to how channels are mapped, you can more efficiently use a single shared texture image for configuring the following: - R - `specular_transmission_texture` - G - `thickness_texture` - B - _unused_ - A - `diffuse_transmission_texture` The `KHR_materials_diffuse_transmission` glTF extension also defines a `diffuseTransmissionColorTexture`, that _we don't currently support_. One might choose to pack the intensity and color textures together, using RGB for the color and A for the intensity, in which case this packing advice doesn't really apply. --- ## Changelog - Added a new `Transmissive3d` render phase for rendering specular transmissive materials with screen space refractions - Added rendering support for transmitted environment map light on the `StandardMaterial` as a fallback for screen space refractions - Added `diffuse_transmission`, `specular_transmission`, `thickness`, `ior`, `attenuation_distance` and `attenuation_color` to the `StandardMaterial` - Added `diffuse_transmission_texture`, `specular_transmission_texture`, `thickness_texture` to the `StandardMaterial`, gated behind a new `pbr_transmission_textures` cargo feature (off by default, for maximum hardware compatibility) - Added `Camera3d::screen_space_specular_transmission_steps` for controlling the number of “layers of transparency” rendered for transmissive objects - Added a `TransmittedShadowReceiver` component for enabling shadows in (diffusely) transmitted light. (disabled by default, as it requires carefully setting up the `thickness` to avoid self-shadow artifacts) - Added support for the `KHR_materials_transmission`, `KHR_materials_ior` and `KHR_materials_volume` glTF extensions - Renamed items related to temporal jitter for greater consistency ## Migration Guide - `SsaoPipelineKey::temporal_noise` has been renamed to `SsaoPipelineKey::temporal_jitter` - The `TAA` shader def (controlled by the presence of the `TemporalAntiAliasSettings` component in the camera) has been replaced with the `TEMPORAL_JITTER` shader def (controlled by the presence of the `TemporalJitter` component in the camera) - `MeshPipelineKey::TAA` has been replaced by `MeshPipelineKey::TEMPORAL_JITTER` - The `TEMPORAL_NOISE` shader def has been consolidated with `TEMPORAL_JITTER`
2023-10-31 20:59:02 +00:00
[[example]]
name = "transmission"
path = "examples/3d/transmission.rs"
Fix some doc warnings (#12961) # Objective - Fix some doc warnings - Add doc-scrape-examples to all examples Moved from #12692 I run `cargo +nightly doc --workspace --all-features --no-deps -Zunstable-options -Zrustdoc-scrape-examples` <details> ``` warning: public documentation for `GzAssetLoaderError` links to private item `GzAssetLoader` --> examples/asset/asset_decompression.rs:24:47 | 24 | /// Possible errors that can be produced by [`GzAssetLoader`] | ^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: `bevy` (example "asset_decompression") generated 1 warning warning: unresolved link to `shape::Quad` --> examples/2d/mesh2d.rs:3:15 | 3 | //! [`Quad`]: shape::Quad | ^^^^^^^^^^^ no item named `shape` in scope | = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "mesh2d") generated 1 warning warning: unresolved link to `WorldQuery` --> examples/ecs/custom_query_param.rs:1:49 | 1 | //! This example illustrates the usage of the [`WorldQuery`] derive macro, which allows | ^^^^^^^^^^ no item named `WorldQuery` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "custom_query_param") generated 1 warning warning: unresolved link to `shape::Quad` --> examples/2d/mesh2d_vertex_color_texture.rs:4:15 | 4 | //! [`Quad`]: shape::Quad | ^^^^^^^^^^^ no item named `shape` in scope | = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "mesh2d_vertex_color_texture") generated 1 warning warning: public documentation for `TextPlugin` links to private item `CoolText` --> examples/asset/processing/asset_processing.rs:48:9 | 48 | /// * [`CoolText`]: a custom RON text format that supports dependencies and embedded dependencies | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: public documentation for `TextPlugin` links to private item `Text` --> examples/asset/processing/asset_processing.rs:49:9 | 49 | /// * [`Text`]: a "normal" plain text file | ^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: public documentation for `TextPlugin` links to private item `CoolText` --> examples/asset/processing/asset_processing.rs:51:57 | 51 | /// It also defines an asset processor that will load [`CoolText`], resolve embedded dependenc... | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: `bevy` (example "asset_processing") generated 3 warnings warning: public documentation for `CustomAssetLoaderError` links to private item `CustomAssetLoader` --> examples/asset/custom_asset.rs:20:47 | 20 | /// Possible errors that can be produced by [`CustomAssetLoader`] | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: public documentation for `BlobAssetLoaderError` links to private item `CustomAssetLoader` --> examples/asset/custom_asset.rs:61:47 | 61 | /// Possible errors that can be produced by [`CustomAssetLoader`] | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` ``` ``` warning: `bevy` (example "mesh2d") generated 1 warning warning: public documentation for `log_layers_ecs` links to private item `update_subscriber` --> examples/app/log_layers_ecs.rs:6:18 | 6 | //! Inside the [`update_subscriber`] function we will create a [`mpsc::Sender`] and a [`mpsc::R... | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: unresolved link to `AdvancedLayer` --> examples/app/log_layers_ecs.rs:7:72 | 7 | ... will go into the [`AdvancedLayer`] and the [`Receiver`](mpsc::Receiver) will | ^^^^^^^^^^^^^ no item named `AdvancedLayer` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: unresolved link to `LogEvents` --> examples/app/log_layers_ecs.rs:8:42 | 8 | //! go into a non-send resource called [`LogEvents`] (It has to be non-send because [`Receiver`... | ^^^^^^^^^ no item named `LogEvents` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` warning: public documentation for `log_layers_ecs` links to private item `transfer_log_events` --> examples/app/log_layers_ecs.rs:9:30 | 9 | //! From there we will use [`transfer_log_events`] to transfer log events from [`LogEvents`] to... | ^^^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: unresolved link to `LogEvents` --> examples/app/log_layers_ecs.rs:9:82 | 9 | ...nsfer log events from [`LogEvents`] to an ECS event called [`LogEvent`]. | ^^^^^^^^^ no item named `LogEvents` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` warning: public documentation for `log_layers_ecs` links to private item `LogEvent` --> examples/app/log_layers_ecs.rs:9:119 | 9 | ...nts`] to an ECS event called [`LogEvent`]. | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: public documentation for `log_layers_ecs` links to private item `LogEvent` --> examples/app/log_layers_ecs.rs:11:49 | 11 | //! Finally, after all that we can access the [`LogEvent`] event from our systems and use it. | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` ``` <details/>
2024-04-14 15:23:44 +00:00
doc-scrape-examples = true
`StandardMaterial` Light Transmission (#8015) # Objective <img width="1920" alt="Screenshot 2023-04-26 at 01 07 34" src="https://user-images.githubusercontent.com/418473/234467578-0f34187b-5863-4ea1-88e9-7a6bb8ce8da3.png"> This PR adds both diffuse and specular light transmission capabilities to the `StandardMaterial`, with support for screen space refractions. This enables realistically representing a wide range of real-world materials, such as: - Glass; (Including frosted glass) - Transparent and translucent plastics; - Various liquids and gels; - Gemstones; - Marble; - Wax; - Paper; - Leaves; - Porcelain. Unlike existing support for transparency, light transmission does not rely on fixed function alpha blending, and therefore works with both `AlphaMode::Opaque` and `AlphaMode::Mask` materials. ## Solution - Introduces a number of transmission related fields in the `StandardMaterial`; - For specular transmission: - Adds logic to take a view main texture snapshot after the opaque phase; (in order to perform screen space refractions) - Introduces a new `Transmissive3d` phase to the renderer, to which all meshes with `transmission > 0.0` materials are sent. - Calculates a light exit point (of the approximate mesh volume) using `ior` and `thickness` properties - Samples the snapshot texture with an adaptive number of taps across a `roughness`-controlled radius enabling “blurry” refractions - For diffuse transmission: - Approximates transmitted diffuse light by using a second, flipped + displaced, diffuse-only Lambertian lobe for each light source. ## To Do - [x] Figure out where `fresnel_mix()` is taking place, if at all, and where `dielectric_specular` is being calculated, if at all, and update them to use the `ior` value (Not a blocker, just a nice-to-have for more correct BSDF) - To the _best of my knowledge, this is now taking place, after 964340cdd. The fresnel mix is actually "split" into two parts in our implementation, one `(1 - fresnel(...))` in the transmission, and `fresnel()` in the light implementations. A surface with more reflectance now will produce slightly dimmer transmission towards the grazing angle, as more of the light gets reflected. - [x] Add `transmission_texture` - [x] Add `diffuse_transmission_texture` - [x] Add `thickness_texture` - [x] Add `attenuation_distance` and `attenuation_color` - [x] Connect values to glTF loader - [x] `transmission` and `transmission_texture` - [x] `thickness` and `thickness_texture` - [x] `ior` - [ ] `diffuse_transmission` and `diffuse_transmission_texture` (needs upstream support in `gltf` crate, not a blocker) - [x] Add support for multiple screen space refraction “steps” - [x] Conditionally create no transmission snapshot texture at all if `steps == 0` - [x] Conditionally enable/disable screen space refraction transmission snapshots - [x] Read from depth pre-pass to prevent refracting pixels in front of the light exit point - [x] Use `interleaved_gradient_noise()` function for sampling blur in a way that benefits from TAA - [x] Drill down a TAA `#define`, tweak some aspects of the effect conditionally based on it - [x] Remove const array that's crashing under HLSL (unless a new `naga` release with https://github.com/gfx-rs/naga/pull/2496 comes out before we merge this) - [ ] Look into alternatives to the `switch` hack for dynamically indexing the const array (might not be needed, compilers seem to be decent at expanding it) - [ ] Add pipeline keys for gating transmission (do we really want/need this?) - [x] Tweak some material field/function names? ## A Note on Texture Packing _This was originally added as a comment to the `specular_transmission_texture`, `thickness_texture` and `diffuse_transmission_texture` documentation, I removed it since it was more confusing than helpful, and will likely be made redundant/will need to be updated once we have a better infrastructure for preprocessing assets_ Due to how channels are mapped, you can more efficiently use a single shared texture image for configuring the following: - R - `specular_transmission_texture` - G - `thickness_texture` - B - _unused_ - A - `diffuse_transmission_texture` The `KHR_materials_diffuse_transmission` glTF extension also defines a `diffuseTransmissionColorTexture`, that _we don't currently support_. One might choose to pack the intensity and color textures together, using RGB for the color and A for the intensity, in which case this packing advice doesn't really apply. --- ## Changelog - Added a new `Transmissive3d` render phase for rendering specular transmissive materials with screen space refractions - Added rendering support for transmitted environment map light on the `StandardMaterial` as a fallback for screen space refractions - Added `diffuse_transmission`, `specular_transmission`, `thickness`, `ior`, `attenuation_distance` and `attenuation_color` to the `StandardMaterial` - Added `diffuse_transmission_texture`, `specular_transmission_texture`, `thickness_texture` to the `StandardMaterial`, gated behind a new `pbr_transmission_textures` cargo feature (off by default, for maximum hardware compatibility) - Added `Camera3d::screen_space_specular_transmission_steps` for controlling the number of “layers of transparency” rendered for transmissive objects - Added a `TransmittedShadowReceiver` component for enabling shadows in (diffusely) transmitted light. (disabled by default, as it requires carefully setting up the `thickness` to avoid self-shadow artifacts) - Added support for the `KHR_materials_transmission`, `KHR_materials_ior` and `KHR_materials_volume` glTF extensions - Renamed items related to temporal jitter for greater consistency ## Migration Guide - `SsaoPipelineKey::temporal_noise` has been renamed to `SsaoPipelineKey::temporal_jitter` - The `TAA` shader def (controlled by the presence of the `TemporalAntiAliasSettings` component in the camera) has been replaced with the `TEMPORAL_JITTER` shader def (controlled by the presence of the `TemporalJitter` component in the camera) - `MeshPipelineKey::TAA` has been replaced by `MeshPipelineKey::TEMPORAL_JITTER` - The `TEMPORAL_NOISE` shader def has been consolidated with `TEMPORAL_JITTER`
2023-10-31 20:59:02 +00:00
[package.metadata.example.transmission]
name = "Transmission"
description = "Showcases light transmission in the PBR material"
category = "3D Rendering"
wasm = true
Reuse texture when resolving multiple passes (#3552) # Objective Fixes https://github.com/bevyengine/bevy/issues/3499 ## Solution Uses a `HashMap` from `RenderTarget` to sampled textures when preparing `ViewTarget`s to ensure that two passes with the same render target get sampled to the same texture. This builds on and depends on https://github.com/bevyengine/bevy/pull/3412, so this will be a draft PR until #3412 is merged. All changes for this PR are in the last commit.
2022-04-12 19:27:30 +00:00
[[example]]
name = "two_passes"
path = "examples/3d/two_passes.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Reuse texture when resolving multiple passes (#3552) # Objective Fixes https://github.com/bevyengine/bevy/issues/3499 ## Solution Uses a `HashMap` from `RenderTarget` to sampled textures when preparing `ViewTarget`s to ensure that two passes with the same render target get sampled to the same texture. This builds on and depends on https://github.com/bevyengine/bevy/pull/3412, so this will be a draft PR until #3412 is merged. All changes for this PR are in the last commit.
2022-04-12 19:27:30 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.two_passes]
name = "Two Passes"
description = "Renders two 3d passes to the same window from different perspectives"
category = "3D Rendering"
wasm = true
add scene instance entity iteration (#1058) add scene instance entity iteration
2021-01-01 20:58:49 +00:00
[[example]]
name = "update_gltf_scene"
path = "examples/3d/update_gltf_scene.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
add scene instance entity iteration (#1058) add scene instance entity iteration
2021-01-01 20:58:49 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.update_gltf_scene]
name = "Update glTF Scene"
description = "Update a scene from a glTF file, either by spawning the scene as a child of another entity, or by accessing the entities of the scene"
category = "3D Rendering"
wasm = true
Add support for vertex colors (#4528) # Objective Add support for vertex colors ## Solution This change is modeled after how vertex tangents are handled, so the shader is conditionally compiled with vertex color support if the mesh has the corresponding attribute set. Vertex colors are multiplied by the base color. I'm not sure if this is the best for all cases, but may be useful for modifying vertex colors without creating a new mesh. I chose `VertexFormat::Float32x4`, but I'd prefer 16-bit floats if/when support is added. ## Changelog ### Added - Vertex colors can be specified using the `Mesh::ATTRIBUTE_COLOR` mesh attribute.
2022-05-05 00:46:32 +00:00
[[example]]
name = "vertex_colors"
path = "examples/3d/vertex_colors.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add support for vertex colors (#4528) # Objective Add support for vertex colors ## Solution This change is modeled after how vertex tangents are handled, so the shader is conditionally compiled with vertex color support if the mesh has the corresponding attribute set. Vertex colors are multiplied by the base color. I'm not sure if this is the best for all cases, but may be useful for modifying vertex colors without creating a new mesh. I chose `VertexFormat::Float32x4`, but I'd prefer 16-bit floats if/when support is added. ## Changelog ### Added - Vertex colors can be specified using the `Mesh::ATTRIBUTE_COLOR` mesh attribute.
2022-05-05 00:46:32 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.vertex_colors]
name = "Vertex Colors"
description = "Shows the use of vertex colors"
category = "3D Rendering"
wasm = true
Wireframe Rendering Pipeline (#562) This PR implements wireframe rendering. Usage: This is now ready as soon as #1401 gets merged. Usage: ```rust app .insert_resource(WgpuOptions { name: Some("3d_scene"), features: WgpuFeatures::NON_FILL_POLYGON_MODE, ..Default::default() }) // To enable the NON_FILL_POLYGON_MODE feature .add_plugin(WireframePlugin) .run(); ``` Now we just need to add the Wireframe component on an entity, and it'll draw. its wireframe. We can also enable wireframe drawing globally by setting the global property in the `WireframeConfig` resource to `true`. Co-authored-by: Zhixing Zhang <me@neoto.xin>
2021-03-04 01:23:24 +00:00
[[example]]
name = "wireframe"
path = "examples/3d/wireframe.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Wireframe Rendering Pipeline (#562) This PR implements wireframe rendering. Usage: This is now ready as soon as #1401 gets merged. Usage: ```rust app .insert_resource(WgpuOptions { name: Some("3d_scene"), features: WgpuFeatures::NON_FILL_POLYGON_MODE, ..Default::default() }) // To enable the NON_FILL_POLYGON_MODE feature .add_plugin(WireframePlugin) .run(); ``` Now we just need to add the Wireframe component on an entity, and it'll draw. its wireframe. We can also enable wireframe drawing globally by setting the global property in the `WireframeConfig` resource to `true`. Co-authored-by: Zhixing Zhang <me@neoto.xin>
2021-03-04 01:23:24 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.wireframe]
name = "Wireframe"
description = "Showcases wireframe rendering"
category = "3D Rendering"
Disable wasm / webgpu building of wireframe example (#8678) # Objective Remove the wireframe example on the WebGPU examples page as it does not render properly. When run in a browser it will render to all white cube due PolygonMode::LINE not being supported in WebGPU. Relevant docs: https://wgpu.rs/doc/wgpu/struct.Features.html#associatedconstant.POLYGON_MODE_LINE When Rendered with WebGPU: <img width="675" alt="image" src="https://github.com/bevyengine/bevy/assets/644930/86c7623c-3e18-42d2-8231-099da10cf6c4"> ## Solution Disable this example when building for WebGPU / wasm.
2023-05-29 15:32:11 +00:00
wasm = false
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
Implement irradiance volumes. (#10268) # Objective Bevy could benefit from *irradiance volumes*, also known as *voxel global illumination* or simply as light probes (though this term is not preferred, as multiple techniques can be called light probes). Irradiance volumes are a form of baked global illumination; they work by sampling the light at the centers of each voxel within a cuboid. At runtime, the voxels surrounding the fragment center are sampled and interpolated to produce indirect diffuse illumination. ## Solution This is divided into two sections. The first is copied and pasted from the irradiance volume module documentation and describes the technique. The second part consists of notes on the implementation. ### Overview An *irradiance volume* is a cuboid voxel region consisting of regularly-spaced precomputed samples of diffuse indirect light. They're ideal if you have a dynamic object such as a character that can move about static non-moving geometry such as a level in a game, and you want that dynamic object to be affected by the light bouncing off that static geometry. To use irradiance volumes, you need to precompute, or *bake*, the indirect light in your scene. Bevy doesn't currently come with a way to do this. Fortunately, [Blender] provides a [baking tool] as part of the Eevee renderer, and its irradiance volumes are compatible with those used by Bevy. The [`bevy-baked-gi`] project provides a tool, `export-blender-gi`, that can extract the baked irradiance volumes from the Blender `.blend` file and package them up into a `.ktx2` texture for use by the engine. See the documentation in the `bevy-baked-gi` project for more details as to this workflow. Like all light probes in Bevy, irradiance volumes are 1×1×1 cubes that can be arbitrarily scaled, rotated, and positioned in a scene with the [`bevy_transform::components::Transform`] component. The 3D voxel grid will be stretched to fill the interior of the cube, and the illumination from the irradiance volume will apply to all fragments within that bounding region. Bevy's irradiance volumes are based on Valve's [*ambient cubes*] as used in *Half-Life 2* ([Mitchell 2006], slide 27). These encode a single color of light from the six 3D cardinal directions and blend the sides together according to the surface normal. The primary reason for choosing ambient cubes is to match Blender, so that its Eevee renderer can be used for baking. However, they also have some advantages over the common second-order spherical harmonics approach: ambient cubes don't suffer from ringing artifacts, they are smaller (6 colors for ambient cubes as opposed to 9 for spherical harmonics), and evaluation is faster. A smaller basis allows for a denser grid of voxels with the same storage requirements. If you wish to use a tool other than `export-blender-gi` to produce the irradiance volumes, you'll need to pack the irradiance volumes in the following format. The irradiance volume of resolution *(Rx, Ry, Rz)* is expected to be a 3D texture of dimensions *(Rx, 2Ry, 3Rz)*. The unnormalized texture coordinate *(s, t, p)* of the voxel at coordinate *(x, y, z)* with side *S* ∈ *{-X, +X, -Y, +Y, -Z, +Z}* is as follows: ```text s = x t = y + ⎰ 0 if S ∈ {-X, -Y, -Z} ⎱ Ry if S ∈ {+X, +Y, +Z} ⎧ 0 if S ∈ {-X, +X} p = z + ⎨ Rz if S ∈ {-Y, +Y} ⎩ 2Rz if S ∈ {-Z, +Z} ``` Visually, in a left-handed coordinate system with Y up, viewed from the right, the 3D texture looks like a stacked series of voxel grids, one for each cube side, in this order: | **+X** | **+Y** | **+Z** | | ------ | ------ | ------ | | **-X** | **-Y** | **-Z** | A terminology note: Other engines may refer to irradiance volumes as *voxel global illumination*, *VXGI*, or simply as *light probes*. Sometimes *light probe* refers to what Bevy calls a reflection probe. In Bevy, *light probe* is a generic term that encompasses all cuboid bounding regions that capture indirect illumination, whether based on voxels or not. Note that, if binding arrays aren't supported (e.g. on WebGPU or WebGL 2), then only the closest irradiance volume to the view will be taken into account during rendering. [*ambient cubes*]: https://advances.realtimerendering.com/s2006/Mitchell-ShadingInValvesSourceEngine.pdf [Mitchell 2006]: https://advances.realtimerendering.com/s2006/Mitchell-ShadingInValvesSourceEngine.pdf [Blender]: http://blender.org/ [baking tool]: https://docs.blender.org/manual/en/latest/render/eevee/render_settings/indirect_lighting.html [`bevy-baked-gi`]: https://github.com/pcwalton/bevy-baked-gi ### Implementation notes This patch generalizes light probes so as to reuse as much code as possible between irradiance volumes and the existing reflection probes. This approach was chosen because both techniques share numerous similarities: 1. Both irradiance volumes and reflection probes are cuboid bounding regions. 2. Both are responsible for providing baked indirect light. 3. Both techniques involve presenting a variable number of textures to the shader from which indirect light is sampled. (In the current implementation, this uses binding arrays.) 4. Both irradiance volumes and reflection probes require gathering and sorting probes by distance on CPU. 5. Both techniques require the GPU to search through a list of bounding regions. 6. Both will eventually want to have falloff so that we can smoothly blend as objects enter and exit the probes' influence ranges. (This is not implemented yet to keep this patch relatively small and reviewable.) To do this, we generalize most of the methods in the reflection probes patch #11366 to be generic over a trait, `LightProbeComponent`. This trait is implemented by both `EnvironmentMapLight` (for reflection probes) and `IrradianceVolume` (for irradiance volumes). Using a trait will allow us to add more types of light probes in the future. In particular, I highly suspect we will want real-time reflection planes for mirrors in the future, which can be easily slotted into this framework. ## Changelog > This section is optional. If this was a trivial fix, or has no externally-visible impact, you can delete this section. ### Added * A new `IrradianceVolume` asset type is available for baked voxelized light probes. You can bake the global illumination using Blender or another tool of your choice and use it in Bevy to apply indirect illumination to dynamic objects.
2024-02-06 23:23:20 +00:00
[[example]]
name = "irradiance_volumes"
path = "examples/3d/irradiance_volumes.rs"
doc-scrape-examples = true
[package.metadata.example.irradiance_volumes]
name = "Irradiance Volumes"
description = "Demonstrates irradiance volumes"
category = "3D Rendering"
wasm = false
Meshlet rendering (initial feature) (#10164) # Objective - Implements a more efficient, GPU-driven (https://github.com/bevyengine/bevy/issues/1342) rendering pipeline based on meshlets. - Meshes are split into small clusters of triangles called meshlets, each of which acts as a mini index buffer into the larger mesh data. Meshlets can be compressed, streamed, culled, and batched much more efficiently than monolithic meshes. ![image](https://github.com/bevyengine/bevy/assets/47158642/cb2aaad0-7a9a-4e14-93b0-15d4e895b26a) ![image](https://github.com/bevyengine/bevy/assets/47158642/7534035b-1eb7-4278-9b99-5322e4401715) # Misc * Future work: https://github.com/bevyengine/bevy/issues/11518 * Nanite reference: https://advances.realtimerendering.com/s2021/Karis_Nanite_SIGGRAPH_Advances_2021_final.pdf Two pass occlusion culling explained very well: https://medium.com/@mil_kru/two-pass-occlusion-culling-4100edcad501 --------- Co-authored-by: Ricky Taylor <rickytaylor26@gmail.com> Co-authored-by: vero <email@atlasdostal.com> Co-authored-by: François <mockersf@gmail.com> Co-authored-by: atlas dostal <rodol@rivalrebels.com>
2024-03-25 19:08:27 +00:00
[[example]]
name = "meshlet"
path = "examples/3d/meshlet.rs"
doc-scrape-examples = true
required-features = ["meshlet"]
[package.metadata.example.meshlet]
name = "Meshlet"
description = "Meshlet rendering for dense high-poly scenes (experimental)"
category = "3D Rendering"
wasm = false
Example setup for tooling (#13088) # Objective - #12755 introduced the need to download a file to run an example - This means the example fails to run in CI without downloading that file ## Solution - Add a new metadata to examples "setup" that provides setup instructions - Replace the URL in the meshlet example to one that can actually be downloaded - example-showcase execute the setup before running an example
2024-05-02 20:10:09 +00:00
setup = [
[
"curl",
"-o",
"assets/models/bunny.meshlet_mesh",
Meshlet normal-aware LOD and meshoptimizer upgrade (#16111) # Objective - Choose LOD based on normal simplification error in addition to position error - Update meshoptimizer to 0.22, which has a bunch of simplifier improvements ## Testing - Did you test these changes? If so, how? - Visualize normals, and compare LOD changes before and after. Normals no longer visibly change as the LOD cut changes. - Are there any parts that need more testing? - No - How can other people (reviewers) test your changes? Is there anything specific they need to know? - Run the meshlet example in this PR and on main and move around to change the LOD cut. Before running each example, in meshlet_mesh_material.wgsl, replace `let color = vec3(rand_f(&rng), rand_f(&rng), rand_f(&rng));` with `let color = (vertex_output.world_normal + 1.0) / 2.0;`. Make sure to download the appropriate bunny asset for each branch!
2024-11-04 15:20:22 +00:00
"https://raw.githubusercontent.com/JMS55/bevy_meshlet_asset/defbd9b32072624d40d57de7d345c66a9edf5d0b/bunny.meshlet_mesh",
Example setup for tooling (#13088) # Objective - #12755 introduced the need to download a file to run an example - This means the example fails to run in CI without downloading that file ## Solution - Add a new metadata to examples "setup" that provides setup instructions - Replace the URL in the meshlet example to one that can actually be downloaded - example-showcase execute the setup before running an example
2024-05-02 20:10:09 +00:00
],
]
Meshlet rendering (initial feature) (#10164) # Objective - Implements a more efficient, GPU-driven (https://github.com/bevyengine/bevy/issues/1342) rendering pipeline based on meshlets. - Meshes are split into small clusters of triangles called meshlets, each of which acts as a mini index buffer into the larger mesh data. Meshlets can be compressed, streamed, culled, and batched much more efficiently than monolithic meshes. ![image](https://github.com/bevyengine/bevy/assets/47158642/cb2aaad0-7a9a-4e14-93b0-15d4e895b26a) ![image](https://github.com/bevyengine/bevy/assets/47158642/7534035b-1eb7-4278-9b99-5322e4401715) # Misc * Future work: https://github.com/bevyengine/bevy/issues/11518 * Nanite reference: https://advances.realtimerendering.com/s2021/Karis_Nanite_SIGGRAPH_Advances_2021_final.pdf Two pass occlusion culling explained very well: https://medium.com/@mil_kru/two-pass-occlusion-culling-4100edcad501 --------- Co-authored-by: Ricky Taylor <rickytaylor26@gmail.com> Co-authored-by: vero <email@atlasdostal.com> Co-authored-by: François <mockersf@gmail.com> Co-authored-by: atlas dostal <rodol@rivalrebels.com>
2024-03-25 19:08:27 +00:00
Add mesh picking backend and `MeshRayCast` system parameter (#15800) # Objective Closes #15545. `bevy_picking` supports UI and sprite picking, but not mesh picking. Being able to pick meshes would be extremely useful for various games, tools, and our own examples, as well as scene editors and inspectors. So, we need a mesh picking backend! Luckily, [`bevy_mod_picking`](https://github.com/aevyrie/bevy_mod_picking) (which `bevy_picking` is based on) by @aevyrie already has a [backend for it](https://github.com/aevyrie/bevy_mod_picking/blob/74f0c3c0fbc8048632ba46fd8f14e26aaea9c76c/backends/bevy_picking_raycast/src/lib.rs) using [`bevy_mod_raycast`](https://github.com/aevyrie/bevy_mod_raycast). As a side product of adding mesh picking, we also get support for performing ray casts on meshes! ## Solution Upstream a large chunk of the immediate-mode ray casting functionality from `bevy_mod_raycast`, and add a mesh picking backend based on `bevy_mod_picking`. Huge thanks to @aevyrie who did all the hard work on these incredible crates! All meshes are pickable by default. Picking can be disabled for individual entities by adding `PickingBehavior::IGNORE`, like normal. Or, if you want mesh picking to be entirely opt-in, you can set `MeshPickingBackendSettings::require_markers` to `true` and add a `RayCastPickable` component to the desired camera and target entities. You can also use the new `MeshRayCast` system parameter to cast rays into the world manually: ```rust fn ray_cast_system(mut ray_cast: MeshRayCast, foo_query: Query<(), With<Foo>>) { let ray = Ray3d::new(Vec3::ZERO, Dir3::X); // Only ray cast against entities with the `Foo` component. let filter = |entity| foo_query.contains(entity); // Never early-exit. Note that you can change behavior per-entity. let early_exit_test = |_entity| false; // Ignore the visibility of entities. This allows ray casting hidden entities. let visibility = RayCastVisibility::Any; let settings = RayCastSettings::default() .with_filter(&filter) .with_early_exit_test(&early_exit_test) .with_visibility(visibility); // Cast the ray with the settings, returning a list of intersections. let hits = ray_cast.cast_ray(ray, &settings); } ``` This is largely a direct port, but I did make several changes to match our APIs better, remove things we don't need or that I think are unnecessary, and do some general improvements to code quality and documentation. ### Changes Relative to `bevy_mod_raycast` and `bevy_mod_picking` - Every `Raycast` and "raycast" has been renamed to `RayCast` and "ray cast" (similar reasoning as the "Naming" section in #15724) - `Raycast` system param has been renamed to `MeshRayCast` to avoid naming conflicts and to be explicit that it is not for colliders - `RaycastBackend` has been renamed to `MeshPickingBackend` - `RayCastVisibility` variants are now `Any`, `Visible`, and `VisibleInView` instead of `Ignore`, `MustBeVisible`, and `MustBeVisibleAndInView` - `NoBackfaceCulling` has been renamed to `RayCastBackfaces`, to avoid implying that it affects the rendering of backfaces for meshes (it doesn't) - `SimplifiedMesh` and `RayCastBackfaces` live near other ray casting API types, not in their own 10 LoC module - All intersection logic and types are in the same `intersections` module, not split across several modules - Some intersection types have been renamed to be clearer and more consistent - `IntersectionData` -> `RayMeshHit` - `RayHit` -> `RayTriangleHit` - General documentation and code quality improvements ### Removed / Not Ported - Removed unused ray helpers and types, like `PrimitiveIntersection` - Removed getters on intersection types, and made their properties public - There is no `2d` feature, and `Raycast::mesh_query` and `Raycast::mesh2d_query` have been merged into `MeshRayCast::mesh_query`, which handles both 2D and 3D - I assume this existed previously because `Mesh2dHandle` used to be in `bevy_sprite`. Now both the 2D and 3D mesh are in `bevy_render`. - There is no `debug` feature or ray debug rendering - There is no deferred API (`RaycastSource`) - There is no `CursorRayPlugin` (the picking backend handles this) ### Note for Reviewers In case it's helpful, the [first commit](https://github.com/bevyengine/bevy/commit/281638ef10ebd25f783bee2533509fdf756f7ab4) here is essentially a one-to-one port. The rest of the commits are primarily refactoring and cleaning things up in the ways listed earlier, as well as changes to the module structure. It may also be useful to compare the original [picking backend](https://github.com/aevyrie/bevy_mod_picking/blob/74f0c3c0fbc8048632ba46fd8f14e26aaea9c76c/backends/bevy_picking_raycast/src/lib.rs) and [`bevy_mod_raycast`](https://github.com/aevyrie/bevy_mod_raycast) to this PR. Feel free to mention if there are any changes that I should revert or something I should not include in this PR. ## Testing I tested mesh picking and relevant components in some examples, for both 2D and 3D meshes, and added a new `mesh_picking` example. I also ~~stole~~ ported over the [ray-mesh intersection benchmark](https://github.com/aevyrie/bevy_mod_raycast/blob/dbc5ef32fe48997a1a7eeec7434d9dd8b829e52e/benches/ray_mesh_intersection.rs) from `bevy_mod_raycast`. --- ## Showcase Below is a version of the `2d_shapes` example modified to demonstrate 2D mesh picking. This is not included in this PR. https://github.com/user-attachments/assets/7742528c-8630-4c00-bacd-81576ac432bf And below is the new `mesh_picking` example: https://github.com/user-attachments/assets/b65c7a5a-fa3a-4c2d-8bbd-e7a2c772986e There is also a really cool new `mesh_ray_cast` example ported over from `bevy_mod_raycast`: https://github.com/user-attachments/assets/3c5eb6c0-bd94-4fb0-bec6-8a85668a06c9 --------- Co-authored-by: Aevyrie <aevyrie@gmail.com> Co-authored-by: Trent <2771466+tbillington@users.noreply.github.com> Co-authored-by: François Mockers <mockersf@gmail.com>
2024-10-13 17:24:19 +00:00
[[example]]
name = "mesh_ray_cast"
path = "examples/3d/mesh_ray_cast.rs"
doc-scrape-examples = true
[package.metadata.example.mesh_ray_cast]
name = "Mesh Ray Cast"
description = "Demonstrates ray casting with the `MeshRayCast` system parameter"
category = "3D Rendering"
wasm = true
Implement lightmaps. (#10231) ![Screenshot](https://i.imgur.com/A4KzWFq.png) # Objective Lightmaps, textures that store baked global illumination, have been a mainstay of real-time graphics for decades. Bevy currently has no support for them, so this pull request implements them. ## Solution The new `Lightmap` component can be attached to any entity that contains a `Handle<Mesh>` and a `StandardMaterial`. When present, it will be applied in the PBR shader. Because multiple lightmaps are frequently packed into atlases, each lightmap may have its own UV boundaries within its texture. An `exposure` field is also provided, to control the brightness of the lightmap. Note that this PR doesn't provide any way to bake the lightmaps. That can be done with [The Lightmapper] or another solution, such as Unity's Bakery. --- ## Changelog ### Added * A new component, `Lightmap`, is available, for baked global illumination. If your mesh has a second UV channel (UV1), and you attach this component to the entity with that mesh, Bevy will apply the texture referenced in the lightmap. [The Lightmapper]: https://github.com/Naxela/The_Lightmapper --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2024-01-02 20:38:47 +00:00
[[example]]
name = "lightmaps"
path = "examples/3d/lightmaps.rs"
doc-scrape-examples = true
[package.metadata.example.lightmaps]
name = "Lightmaps"
description = "Rendering a scene with baked lightmaps"
category = "3D Rendering"
wasm = false
Fix dependency of shadow mapping on the optional `PrepassPlugin` (#7878) # Objective Unfortunately, there are three issues with my changes introduced by #7784. 1. The changes left some dead code. This is already taken care of here: #7875. 2. Disabling prepass causes failures because the shadow mapping relies on the `PrepassPlugin` now. 3. Custom materials use the `prepass.wgsl` shader, but this does not always define a fragment entry point. This PR fixes 2. and 3. and resolves #7879. ## Solution - Add a regression test with disabled prepass. - Split `PrepassPlugin` into two plugins: - `PrepassPipelinePlugin` contains the part that is required for the shadow mapping to work and is unconditionally added. - `PrepassPlugin` now only adds the systems and resources required for the "real" prepasses. - Add a noop fragment entry point to `prepass.wgsl`, used if `NORMAL_PASS` is not defined. Co-authored-by: Edgar Geier <geieredgar@gmail.com>
2023-03-03 15:08:54 +00:00
[[example]]
name = "no_prepass"
path = "tests/3d/no_prepass.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Fix dependency of shadow mapping on the optional `PrepassPlugin` (#7878) # Objective Unfortunately, there are three issues with my changes introduced by #7784. 1. The changes left some dead code. This is already taken care of here: #7875. 2. Disabling prepass causes failures because the shadow mapping relies on the `PrepassPlugin` now. 3. Custom materials use the `prepass.wgsl` shader, but this does not always define a fragment entry point. This PR fixes 2. and 3. and resolves #7879. ## Solution - Add a regression test with disabled prepass. - Split `PrepassPlugin` into two plugins: - `PrepassPipelinePlugin` contains the part that is required for the shadow mapping to work and is unconditionally added. - `PrepassPlugin` now only adds the systems and resources required for the "real" prepasses. - Add a noop fragment entry point to `prepass.wgsl`, used if `NORMAL_PASS` is not defined. Co-authored-by: Edgar Geier <geieredgar@gmail.com>
2023-03-03 15:08:54 +00:00
[package.metadata.example.no_prepass]
hidden = true
Mesh Skinning. Attempt #3 (#4238) # Objective Load skeletal weights and indices from GLTF files. Animate meshes. ## Solution - Load skeletal weights and indices from GLTF files. - Added `SkinnedMesh` component and ` SkinnedMeshInverseBindPose` asset - Added `extract_skinned_meshes` to extract joint matrices. - Added queue phase systems for enqueuing the buffer writes. Some notes: - This ports part of # #2359 to the current main. - This generates new `BufferVec`s and bind groups every frame. The expectation here is that the number of `Query::get` calls during extract is probably going to be the stronger bottleneck, with up to 256 calls per skinned mesh. Until that is optimized, caching buffers and bind groups is probably a non-concern. - Unfortunately, due to the uniform size requirements, this means a 16KB buffer is allocated for every skinned mesh every frame. There's probably a few ways to get around this, but most of them require either compute shaders or storage buffers, which are both incompatible with WebGL2. Co-authored-by: james7132 <contact@jamessliu.com> Co-authored-by: François <mockersf@gmail.com> Co-authored-by: James Liu <contact@jamessliu.com>
2022-03-29 18:31:13 +00:00
# Animation
Add Support for Triggering Events via `AnimationEvent`s (#15538) # Objective Add support for events that can be triggered from animation clips. This is useful when you need something to happen at a specific time in an animation. For example, playing a sound every time a characters feet hits the ground when walking. Closes #15494 ## Solution Added a new field to `AnimationClip`: `events`, which contains a list of `AnimationEvent`s. These are automatically triggered in `animate_targets` and `trigger_untargeted_animation_events`. ## Testing Added a couple of tests and example (`animation_events.rs`) to make sure events are triggered when expected. --- ## Showcase `Events` need to also implement `AnimationEvent` and `Reflect` to be used with animations. ```rust #[derive(Event, AnimationEvent, Reflect)] struct SomeEvent; ``` Events can be added to an `AnimationClip` by specifying a time and event. ```rust // trigger an event after 1.0 second animation_clip.add_event(1.0, SomeEvent); ``` And optionally, providing a target id. ```rust let id = AnimationTargetId::from_iter(["shoulder", "arm", "hand"]); animation_clip.add_event_to_target(id, 1.0, HandEvent); ``` I modified the `animated_fox` example to show off the feature. ![CleanShot 2024-10-05 at 02 41 57](https://github.com/user-attachments/assets/0bb47db7-24f9-4504-88f1-40e375b89b1b) --------- Co-authored-by: Matty <weatherleymatthew@gmail.com> Co-authored-by: Chris Biscardi <chris@christopherbiscardi.com> Co-authored-by: François Mockers <francois.mockers@vleue.com>
2024-10-06 10:03:05 +00:00
[[example]]
name = "animation_events"
path = "examples/animation/animation_events.rs"
doc-scrape-examples = true
[package.metadata.example.animation_events]
name = "Animation Events"
description = "Demonstrate how to use animation events"
category = "Animation"
wasm = true
animation player (#4375) # Objective - Add a basic animation player - Single track - Not generic, can only animate `Transform`s - With plenty of possible optimisations available - Close-ish to https://github.com/bevyengine/rfcs/pull/49 - https://discord.com/channels/691052431525675048/774027865020039209/958820063148929064 ## Solution - Can play animations - looping or not - Can pause animations - Can seek in animation - Can alter speed of animation - I also removed the previous gltf animation example https://user-images.githubusercontent.com/8672791/161051887-e79283f0-9803-448a-93d0-5f7a62acb02d.mp4
2022-04-02 22:36:02 +00:00
[[example]]
name = "animated_fox"
path = "examples/animation/animated_fox.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
animation player (#4375) # Objective - Add a basic animation player - Single track - Not generic, can only animate `Transform`s - With plenty of possible optimisations available - Close-ish to https://github.com/bevyengine/rfcs/pull/49 - https://discord.com/channels/691052431525675048/774027865020039209/958820063148929064 ## Solution - Can play animations - looping or not - Can pause animations - Can seek in animation - Can alter speed of animation - I also removed the previous gltf animation example https://user-images.githubusercontent.com/8672791/161051887-e79283f0-9803-448a-93d0-5f7a62acb02d.mp4
2022-04-02 22:36:02 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.animated_fox]
name = "Animated Fox"
description = "Plays an animation from a skinned glTF"
category = "Animation"
wasm = true
Implement the `AnimationGraph`, allowing for multiple animations to be blended together. (#11989) This is an implementation of RFC #51: https://github.com/bevyengine/rfcs/blob/main/rfcs/51-animation-composition.md Note that the implementation strategy is different from the one outlined in that RFC, because two-phase animation has now landed. # Objective Bevy needs animation blending. The RFC for this is [RFC 51]. ## Solution This is an implementation of the RFC. Note that the implementation strategy is different from the one outlined there, because two-phase animation has now landed. This is just a draft to get the conversation started. Currently we're missing a few things: - [x] A fully-fleshed-out mechanism for transitions - [x] A serialization format for `AnimationGraph`s - [x] Examples are broken, other than `animated_fox` - [x] Documentation --- ## Changelog ### Added * The `AnimationPlayer` has been reworked to support blending multiple animations together through an `AnimationGraph`, and as such will no longer function unless a `Handle<AnimationGraph>` has been added to the entity containing the player. See [RFC 51] for more details. * Transition functionality has moved from the `AnimationPlayer` to a new component, `AnimationTransitions`, which works in tandem with the `AnimationGraph`. ## Migration Guide * `AnimationPlayer`s can no longer play animations by themselves and need to be paired with a `Handle<AnimationGraph>`. Code that was using `AnimationPlayer` to play animations will need to create an `AnimationGraph` asset first, add a node for the clip (or clips) you want to play, and then supply the index of that node to the `AnimationPlayer`'s `play` method. * The `AnimationPlayer::play_with_transition()` method has been removed and replaced with the `AnimationTransitions` component. If you were previously using `AnimationPlayer::play_with_transition()`, add all animations that you were playing to the `AnimationGraph`, and create an `AnimationTransitions` component to manage the blending between them. [RFC 51]: https://github.com/bevyengine/rfcs/blob/main/rfcs/51-animation-composition.md --------- Co-authored-by: Rob Parrett <robparrett@gmail.com>
2024-03-07 20:22:42 +00:00
[[example]]
name = "animation_graph"
path = "examples/animation/animation_graph.rs"
doc-scrape-examples = true
[package.metadata.example.animation_graph]
name = "Animation Graph"
description = "Blends multiple animations together with a graph"
category = "Animation"
wasm = true
Add morph targets (#8158) # Objective - Add morph targets to `bevy_pbr` (closes #5756) & load them from glTF - Supersedes #3722 - Fixes #6814 [Morph targets][1] (also known as shape interpolation, shape keys, or blend shapes) allow animating individual vertices with fine grained controls. This is typically used for facial expressions. By specifying multiple poses as vertex offset, and providing a set of weight of each pose, it is possible to define surprisingly realistic transitions between poses. Blending between multiple poses also allow composition. Morph targets are part of the [gltf standard][2] and are a feature of Unity and Unreal, and babylone.js, it is only natural to implement them in bevy. ## Solution This implementation of morph targets uses a 3d texture where each pixel is a component of an animated attribute. Each layer is a different target. We use a 2d texture for each target, because the number of attribute×components×animated vertices is expected to always exceed the maximum pixel row size limit of webGL2. It copies fairly closely the way skinning is implemented on the CPU side, while on the GPU side, the shader morph target implementation is a relatively trivial detail. We add an optional `morph_texture` to the `Mesh` struct. The `morph_texture` is built through a method that accepts an iterator over attribute buffers. The `MorphWeights` component, user-accessible, controls the blend of poses used by mesh instances (so that multiple copy of the same mesh may have different weights), all the weights are uploaded to a uniform buffer of 256 `f32`. We limit to 16 poses per mesh, and a total of 256 poses. More literature: * Old babylone.js implementation (vertex attribute-based): https://www.eternalcoding.com/dev-log-1-morph-targets/ * Babylone.js implementation (similar to ours): https://www.youtube.com/watch?v=LBPRmGgU0PE * GPU gems 3: https://developer.nvidia.com/gpugems/gpugems3/part-i-geometry/chapter-3-directx-10-blend-shapes-breaking-limits * Development discord thread https://discord.com/channels/691052431525675048/1083325980615114772 https://user-images.githubusercontent.com/26321040/231181046-3bca2ab2-d4d9-472e-8098-639f1871ce2e.mp4 https://github.com/bevyengine/bevy/assets/26321040/d2a0c544-0ef8-45cf-9f99-8c3792f5a258 ## Acknowledgements * Thanks to `storytold` for sponsoring the feature * Thanks to `superdump` and `james7132` for guidance and help figuring out stuff ## Future work - Handling of less and more attributes (eg: animated uv, animated arbitrary attributes) - Dynamic pose allocation (so that zero-weighted poses aren't uploaded to GPU for example, enables much more total poses) - Better animation API, see #8357 ---- ## Changelog - Add morph targets to bevy meshes - Support up to 64 poses per mesh of individually up to 116508 vertices, animation currently strictly limited to the position, normal and tangent attributes. - Load a morph target using `Mesh::set_morph_targets` - Add `VisitMorphTargets` and `VisitMorphAttributes` traits to `bevy_render`, this allows defining morph targets (a fairly complex and nested data structure) through iterators (ie: single copy instead of passing around buffers), see documentation of those traits for details - Add `MorphWeights` component exported by `bevy_render` - `MorphWeights` control mesh's morph target weights, blending between various poses defined as morph targets. - `MorphWeights` are directly inherited by direct children (single level of hierarchy) of an entity. This allows controlling several mesh primitives through a unique entity _as per GLTF spec_. - Add `MorphTargetNames` component, naming each indices of loaded morph targets. - Load morph targets weights and buffers in `bevy_gltf` - handle morph targets animations in `bevy_animation` (previously, it was a `warn!` log) - Add the `MorphStressTest.gltf` asset for morph targets testing, taken from the glTF samples repo, CC0. - Add morph target manipulation to `scene_viewer` - Separate the animation code in `scene_viewer` from the rest of the code, reducing `#[cfg(feature)]` noise - Add the `morph_targets.rs` example to show off how to manipulate morph targets, loading `MorpStressTest.gltf` ## Migration Guide - (very specialized, unlikely to be touched by 3rd parties) - `MeshPipeline` now has a single `mesh_layouts` field rather than separate `mesh_layout` and `skinned_mesh_layout` fields. You should handle all possible mesh bind group layouts in your implementation - You should also handle properly the new `MORPH_TARGETS` shader def and mesh pipeline key. A new function is exposed to make this easier: `setup_moprh_and_skinning_defs` - The `MeshBindGroup` is now `MeshBindGroups`, cached bind groups are now accessed through the `get` method. [1]: https://en.wikipedia.org/wiki/Morph_target_animation [2]: https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#morph-targets --------- Co-authored-by: François <mockersf@gmail.com> Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-06-22 20:00:01 +00:00
[[example]]
name = "morph_targets"
path = "examples/animation/morph_targets.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add morph targets (#8158) # Objective - Add morph targets to `bevy_pbr` (closes #5756) & load them from glTF - Supersedes #3722 - Fixes #6814 [Morph targets][1] (also known as shape interpolation, shape keys, or blend shapes) allow animating individual vertices with fine grained controls. This is typically used for facial expressions. By specifying multiple poses as vertex offset, and providing a set of weight of each pose, it is possible to define surprisingly realistic transitions between poses. Blending between multiple poses also allow composition. Morph targets are part of the [gltf standard][2] and are a feature of Unity and Unreal, and babylone.js, it is only natural to implement them in bevy. ## Solution This implementation of morph targets uses a 3d texture where each pixel is a component of an animated attribute. Each layer is a different target. We use a 2d texture for each target, because the number of attribute×components×animated vertices is expected to always exceed the maximum pixel row size limit of webGL2. It copies fairly closely the way skinning is implemented on the CPU side, while on the GPU side, the shader morph target implementation is a relatively trivial detail. We add an optional `morph_texture` to the `Mesh` struct. The `morph_texture` is built through a method that accepts an iterator over attribute buffers. The `MorphWeights` component, user-accessible, controls the blend of poses used by mesh instances (so that multiple copy of the same mesh may have different weights), all the weights are uploaded to a uniform buffer of 256 `f32`. We limit to 16 poses per mesh, and a total of 256 poses. More literature: * Old babylone.js implementation (vertex attribute-based): https://www.eternalcoding.com/dev-log-1-morph-targets/ * Babylone.js implementation (similar to ours): https://www.youtube.com/watch?v=LBPRmGgU0PE * GPU gems 3: https://developer.nvidia.com/gpugems/gpugems3/part-i-geometry/chapter-3-directx-10-blend-shapes-breaking-limits * Development discord thread https://discord.com/channels/691052431525675048/1083325980615114772 https://user-images.githubusercontent.com/26321040/231181046-3bca2ab2-d4d9-472e-8098-639f1871ce2e.mp4 https://github.com/bevyengine/bevy/assets/26321040/d2a0c544-0ef8-45cf-9f99-8c3792f5a258 ## Acknowledgements * Thanks to `storytold` for sponsoring the feature * Thanks to `superdump` and `james7132` for guidance and help figuring out stuff ## Future work - Handling of less and more attributes (eg: animated uv, animated arbitrary attributes) - Dynamic pose allocation (so that zero-weighted poses aren't uploaded to GPU for example, enables much more total poses) - Better animation API, see #8357 ---- ## Changelog - Add morph targets to bevy meshes - Support up to 64 poses per mesh of individually up to 116508 vertices, animation currently strictly limited to the position, normal and tangent attributes. - Load a morph target using `Mesh::set_morph_targets` - Add `VisitMorphTargets` and `VisitMorphAttributes` traits to `bevy_render`, this allows defining morph targets (a fairly complex and nested data structure) through iterators (ie: single copy instead of passing around buffers), see documentation of those traits for details - Add `MorphWeights` component exported by `bevy_render` - `MorphWeights` control mesh's morph target weights, blending between various poses defined as morph targets. - `MorphWeights` are directly inherited by direct children (single level of hierarchy) of an entity. This allows controlling several mesh primitives through a unique entity _as per GLTF spec_. - Add `MorphTargetNames` component, naming each indices of loaded morph targets. - Load morph targets weights and buffers in `bevy_gltf` - handle morph targets animations in `bevy_animation` (previously, it was a `warn!` log) - Add the `MorphStressTest.gltf` asset for morph targets testing, taken from the glTF samples repo, CC0. - Add morph target manipulation to `scene_viewer` - Separate the animation code in `scene_viewer` from the rest of the code, reducing `#[cfg(feature)]` noise - Add the `morph_targets.rs` example to show off how to manipulate morph targets, loading `MorpStressTest.gltf` ## Migration Guide - (very specialized, unlikely to be touched by 3rd parties) - `MeshPipeline` now has a single `mesh_layouts` field rather than separate `mesh_layout` and `skinned_mesh_layout` fields. You should handle all possible mesh bind group layouts in your implementation - You should also handle properly the new `MORPH_TARGETS` shader def and mesh pipeline key. A new function is exposed to make this easier: `setup_moprh_and_skinning_defs` - The `MeshBindGroup` is now `MeshBindGroups`, cached bind groups are now accessed through the `get` method. [1]: https://en.wikipedia.org/wiki/Morph_target_animation [2]: https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#morph-targets --------- Co-authored-by: François <mockersf@gmail.com> Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-06-22 20:00:01 +00:00
[package.metadata.example.morph_targets]
name = "Morph Targets"
description = "Plays an animation from a glTF file with meshes with morph targets"
category = "Animation"
wasm = true
example on how to create an animation in code (#4399) # Objective - Animation can be used outside of glTF, but are not obvious on how to create them ## Solution - Add an example creating an animation
2022-04-07 23:53:43 +00:00
[[example]]
name = "animated_transform"
path = "examples/animation/animated_transform.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
example on how to create an animation in code (#4399) # Objective - Animation can be used outside of glTF, but are not obvious on how to create them ## Solution - Add an example creating an animation
2022-04-07 23:53:43 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.animated_transform]
name = "Animated Transform"
description = "Create and play an animation defined by code that operates on the `Transform` component"
category = "Animation"
wasm = true
`Animatable` for colors (#12614) # Objective - Fixes #12202 ## Solution - Implements `Animatable` for all color types implementing arithmetic operations. - the colors returned by `Animatable`s methods are already clamped. - Adds a `color_animation.rs` example. - Implements the `*Assign` operators for color types that already had the corresponding operators. This is just a 'nice to have' and I am happy to remove this if it's not wanted. --- ## Changelog - `bevy_animation` now depends on `bevy_color`. - `LinearRgba`, `Laba`, `Oklaba` and `Xyza` implement `Animatable`. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Zachary Harrold <zac@harrold.com.au>
2024-03-22 00:06:24 +00:00
[[example]]
name = "color_animation"
path = "examples/animation/color_animation.rs"
doc-scrape-examples = true
[package.metadata.example.color_animation]
name = "Color animation"
description = "Demonstrates how to animate colors using mixing and splines in different color spaces"
category = "Animation"
wasm = true
Adding a bezier curve example (#8194) # Objective Examples on how to use the freshly merged `Bezier` struct ( #7653 ) are missing. ## Solution - Added a `bezier_curve.rs` example in the `animation/` folder. --------- Co-authored-by: ira <JustTheCoolDude@gmail.com> Co-authored-by: Aevyrie <aevyrie@gmail.com>
2023-04-17 16:16:56 +00:00
[[example]]
Simplified easing curves (#15711) # Objective Simplify the API surrounding easing curves. Broaden the base of types that support easing. ## Solution There is now a single library function, `easing_curve`, which constructs a unit-parametrized easing curve between two values based on an `EaseFunction`: ```rust /// Given a `start` and `end` value, create a curve parametrized over [the unit interval] /// that connects them, using the given [ease function] to determine the form of the /// curve in between. /// /// [the unit interval]: Interval::UNIT /// [ease function]: EaseFunction pub fn easing_curve<T: Ease>(start: T, end: T, ease_fn: EaseFunction) -> EasingCurve<T> { //... } ``` As this shows, the type of the output curve is generic only in `T`. In particular, as long as `T` is `Reflect` (and `FromReflect` etc. — i.e., a standard "well-behaved" reflectable type), `EasingCurve<T>` is also `Reflect`, and there is no special field handling nonsense. Therefore, `EasingCurve` is the kind of thing that would be able to be easily changed in an editor. This is made possible by storing the actual `EaseFunction` on `EasingCurve<T>` instead of indirecting through some kind of function type (which generally leads to issues with reflection). The types that can be eased are those that implement a trait `Ease`: ```rust /// A type whose values can be eased between. /// /// This requires the construction of an interpolation curve that actually extends /// beyond the curve segment that connects two values, because an easing curve may /// extrapolate before the starting value and after the ending value. This is /// especially common in easing functions that mimic elastic or springlike behavior. pub trait Ease: Sized { /// Given `start` and `end` values, produce a curve with [unlimited domain] /// that: /// - takes a value equivalent to `start` at `t = 0` /// - takes a value equivalent to `end` at `t = 1` /// - has constant speed everywhere, including outside of `[0, 1]` /// /// [unlimited domain]: Interval::EVERYWHERE fn interpolating_curve_unbounded(start: &Self, end: &Self) -> impl Curve<Self>; } ``` (I know, I know, yet *another* interpolation trait. See 'Future direction'.) The other existing easing functions from the previous version of this module have also become new members of `EaseFunction`: `Linear`, `Steps`, and `Elastic` (which maybe needs a different name). The latter two are parametrized. ## Testing Tested using the `easing_functions` example. I also axed the `cubic_curve` example which was of questionable value and replaced it with `eased_motion`, which uses this API in the context of animation: https://github.com/user-attachments/assets/3c802992-6b9b-4b56-aeb1-a47501c29ce2 --- ## Future direction Morally speaking, `Ease` is incredibly similar to `StableInterpolate`. Probably, we should just merge `StableInterpolate` into `Ease`, and then make `SmoothNudge` an automatic extension trait of `Ease`. The reason I didn't do that is that `StableInterpolate` is not implemented for `VectorSpace` because of concerns about the `Color` types, and I wanted to avoid controversy. I think that may be a good idea though. As Alice mentioned before, we should also probably get rid of the `interpolation` dependency. The parametrized `Elastic` variant probably also needs some additional work (e.g. renaming, in/out/in-out variants, etc.) if we want to keep it.
2024-10-08 19:45:13 +00:00
name = "eased_motion"
path = "examples/animation/eased_motion.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Adding a bezier curve example (#8194) # Objective Examples on how to use the freshly merged `Bezier` struct ( #7653 ) are missing. ## Solution - Added a `bezier_curve.rs` example in the `animation/` folder. --------- Co-authored-by: ira <JustTheCoolDude@gmail.com> Co-authored-by: Aevyrie <aevyrie@gmail.com>
2023-04-17 16:16:56 +00:00
Simplified easing curves (#15711) # Objective Simplify the API surrounding easing curves. Broaden the base of types that support easing. ## Solution There is now a single library function, `easing_curve`, which constructs a unit-parametrized easing curve between two values based on an `EaseFunction`: ```rust /// Given a `start` and `end` value, create a curve parametrized over [the unit interval] /// that connects them, using the given [ease function] to determine the form of the /// curve in between. /// /// [the unit interval]: Interval::UNIT /// [ease function]: EaseFunction pub fn easing_curve<T: Ease>(start: T, end: T, ease_fn: EaseFunction) -> EasingCurve<T> { //... } ``` As this shows, the type of the output curve is generic only in `T`. In particular, as long as `T` is `Reflect` (and `FromReflect` etc. — i.e., a standard "well-behaved" reflectable type), `EasingCurve<T>` is also `Reflect`, and there is no special field handling nonsense. Therefore, `EasingCurve` is the kind of thing that would be able to be easily changed in an editor. This is made possible by storing the actual `EaseFunction` on `EasingCurve<T>` instead of indirecting through some kind of function type (which generally leads to issues with reflection). The types that can be eased are those that implement a trait `Ease`: ```rust /// A type whose values can be eased between. /// /// This requires the construction of an interpolation curve that actually extends /// beyond the curve segment that connects two values, because an easing curve may /// extrapolate before the starting value and after the ending value. This is /// especially common in easing functions that mimic elastic or springlike behavior. pub trait Ease: Sized { /// Given `start` and `end` values, produce a curve with [unlimited domain] /// that: /// - takes a value equivalent to `start` at `t = 0` /// - takes a value equivalent to `end` at `t = 1` /// - has constant speed everywhere, including outside of `[0, 1]` /// /// [unlimited domain]: Interval::EVERYWHERE fn interpolating_curve_unbounded(start: &Self, end: &Self) -> impl Curve<Self>; } ``` (I know, I know, yet *another* interpolation trait. See 'Future direction'.) The other existing easing functions from the previous version of this module have also become new members of `EaseFunction`: `Linear`, `Steps`, and `Elastic` (which maybe needs a different name). The latter two are parametrized. ## Testing Tested using the `easing_functions` example. I also axed the `cubic_curve` example which was of questionable value and replaced it with `eased_motion`, which uses this API in the context of animation: https://github.com/user-attachments/assets/3c802992-6b9b-4b56-aeb1-a47501c29ce2 --- ## Future direction Morally speaking, `Ease` is incredibly similar to `StableInterpolate`. Probably, we should just merge `StableInterpolate` into `Ease`, and then make `SmoothNudge` an automatic extension trait of `Ease`. The reason I didn't do that is that `StableInterpolate` is not implemented for `VectorSpace` because of concerns about the `Color` types, and I wanted to avoid controversy. I think that may be a good idea though. As Alice mentioned before, we should also probably get rid of the `interpolation` dependency. The parametrized `Elastic` variant probably also needs some additional work (e.g. renaming, in/out/in-out variants, etc.) if we want to keep it.
2024-10-08 19:45:13 +00:00
[package.metadata.example.eased_motion]
name = "Eased Motion"
description = "Demonstrates the application of easing curves to animate an object"
Adding a bezier curve example (#8194) # Objective Examples on how to use the freshly merged `Bezier` struct ( #7653 ) are missing. ## Solution - Added a `bezier_curve.rs` example in the `animation/` folder. --------- Co-authored-by: ira <JustTheCoolDude@gmail.com> Co-authored-by: Aevyrie <aevyrie@gmail.com>
2023-04-17 16:16:56 +00:00
category = "Animation"
wasm = true
add example for ease functions (#15703) # Objective - Followup to #15675 - Add an example showcasing the functions ## Solution - Add an example showcasing the functions - Some of the functions from the interpolation crate are messed up, fixed in #15706 ![ease](https://github.com/user-attachments/assets/1f3b2b80-23d2-45c7-8b08-95b2e870aa02) --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Joona Aalto <jondolf.dev@gmail.com>
2024-10-07 18:31:43 +00:00
[[example]]
name = "easing_functions"
path = "examples/animation/easing_functions.rs"
doc-scrape-examples = true
[package.metadata.example.easing_functions]
name = "Easing Functions"
description = "Showcases the built-in easing functions"
category = "Animation"
wasm = true
Mesh Skinning. Attempt #3 (#4238) # Objective Load skeletal weights and indices from GLTF files. Animate meshes. ## Solution - Load skeletal weights and indices from GLTF files. - Added `SkinnedMesh` component and ` SkinnedMeshInverseBindPose` asset - Added `extract_skinned_meshes` to extract joint matrices. - Added queue phase systems for enqueuing the buffer writes. Some notes: - This ports part of # #2359 to the current main. - This generates new `BufferVec`s and bind groups every frame. The expectation here is that the number of `Query::get` calls during extract is probably going to be the stronger bottleneck, with up to 256 calls per skinned mesh. Until that is optimized, caching buffers and bind groups is probably a non-concern. - Unfortunately, due to the uniform size requirements, this means a 16KB buffer is allocated for every skinned mesh every frame. There's probably a few ways to get around this, but most of them require either compute shaders or storage buffers, which are both incompatible with WebGL2. Co-authored-by: james7132 <contact@jamessliu.com> Co-authored-by: François <mockersf@gmail.com> Co-authored-by: James Liu <contact@jamessliu.com>
2022-03-29 18:31:13 +00:00
[[example]]
name = "custom_skinned_mesh"
path = "examples/animation/custom_skinned_mesh.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Mesh Skinning. Attempt #3 (#4238) # Objective Load skeletal weights and indices from GLTF files. Animate meshes. ## Solution - Load skeletal weights and indices from GLTF files. - Added `SkinnedMesh` component and ` SkinnedMeshInverseBindPose` asset - Added `extract_skinned_meshes` to extract joint matrices. - Added queue phase systems for enqueuing the buffer writes. Some notes: - This ports part of # #2359 to the current main. - This generates new `BufferVec`s and bind groups every frame. The expectation here is that the number of `Query::get` calls during extract is probably going to be the stronger bottleneck, with up to 256 calls per skinned mesh. Until that is optimized, caching buffers and bind groups is probably a non-concern. - Unfortunately, due to the uniform size requirements, this means a 16KB buffer is allocated for every skinned mesh every frame. There's probably a few ways to get around this, but most of them require either compute shaders or storage buffers, which are both incompatible with WebGL2. Co-authored-by: james7132 <contact@jamessliu.com> Co-authored-by: François <mockersf@gmail.com> Co-authored-by: James Liu <contact@jamessliu.com>
2022-03-29 18:31:13 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.custom_skinned_mesh]
name = "Custom Skinned Mesh"
description = "Skinned mesh example with mesh and joints data defined in code"
category = "Animation"
wasm = true
Mesh Skinning. Attempt #3 (#4238) # Objective Load skeletal weights and indices from GLTF files. Animate meshes. ## Solution - Load skeletal weights and indices from GLTF files. - Added `SkinnedMesh` component and ` SkinnedMeshInverseBindPose` asset - Added `extract_skinned_meshes` to extract joint matrices. - Added queue phase systems for enqueuing the buffer writes. Some notes: - This ports part of # #2359 to the current main. - This generates new `BufferVec`s and bind groups every frame. The expectation here is that the number of `Query::get` calls during extract is probably going to be the stronger bottleneck, with up to 256 calls per skinned mesh. Until that is optimized, caching buffers and bind groups is probably a non-concern. - Unfortunately, due to the uniform size requirements, this means a 16KB buffer is allocated for every skinned mesh every frame. There's probably a few ways to get around this, but most of them require either compute shaders or storage buffers, which are both incompatible with WebGL2. Co-authored-by: james7132 <contact@jamessliu.com> Co-authored-by: François <mockersf@gmail.com> Co-authored-by: James Liu <contact@jamessliu.com>
2022-03-29 18:31:13 +00:00
[[example]]
name = "gltf_skinned_mesh"
path = "examples/animation/gltf_skinned_mesh.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Mesh Skinning. Attempt #3 (#4238) # Objective Load skeletal weights and indices from GLTF files. Animate meshes. ## Solution - Load skeletal weights and indices from GLTF files. - Added `SkinnedMesh` component and ` SkinnedMeshInverseBindPose` asset - Added `extract_skinned_meshes` to extract joint matrices. - Added queue phase systems for enqueuing the buffer writes. Some notes: - This ports part of # #2359 to the current main. - This generates new `BufferVec`s and bind groups every frame. The expectation here is that the number of `Query::get` calls during extract is probably going to be the stronger bottleneck, with up to 256 calls per skinned mesh. Until that is optimized, caching buffers and bind groups is probably a non-concern. - Unfortunately, due to the uniform size requirements, this means a 16KB buffer is allocated for every skinned mesh every frame. There's probably a few ways to get around this, but most of them require either compute shaders or storage buffers, which are both incompatible with WebGL2. Co-authored-by: james7132 <contact@jamessliu.com> Co-authored-by: François <mockersf@gmail.com> Co-authored-by: James Liu <contact@jamessliu.com>
2022-03-29 18:31:13 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.gltf_skinned_mesh]
name = "glTF Skinned Mesh"
description = "Skinned mesh example with mesh and joints data loaded from a glTF file"
category = "Animation"
wasm = true
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
# Application
add basic example of a custom update loop (#799)
2020-11-09 21:04:27 +00:00
[[example]]
name = "custom_loop"
path = "examples/app/custom_loop.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
add basic example of a custom update loop (#799)
2020-11-09 21:04:27 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.custom_loop]
name = "Custom Loop"
description = "Demonstrates how to create a custom runner (to update an app manually)"
category = "Application"
wasm = false
Add basic file drag and drop support (#1096) Add basic file drag and drop support
2021-01-01 21:31:22 +00:00
[[example]]
name = "drag_and_drop"
path = "examples/app/drag_and_drop.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add basic file drag and drop support (#1096) Add basic file drag and drop support
2021-01-01 21:31:22 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.drag_and_drop]
name = "Drag and Drop"
description = "An example that shows how to handle drag and drop in an app"
category = "Application"
wasm = false
organize examples and add ecs guide
2020-05-01 20:12:47 +00:00
[[example]]
name = "empty"
path = "examples/app/empty.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
organize examples and add ecs guide
2020-05-01 20:12:47 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.empty]
name = "Empty"
description = "An empty application (does nothing)"
category = "Application"
wasm = false
Log Plugin (#836) add bevy_log plugin
2020-11-13 01:23:57 +00:00
[[example]]
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
name = "empty_defaults"
path = "examples/app/empty_defaults.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Log Plugin (#836) add bevy_log plugin
2020-11-13 01:23:57 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.empty_defaults]
name = "Empty with Defaults"
description = "An empty application with default plugins"
category = "Application"
wasm = true
organize examples and add ecs guide
2020-05-01 20:12:47 +00:00
[[example]]
name = "headless"
path = "examples/app/headless.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
organize examples and add ecs guide
2020-05-01 20:12:47 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.headless]
name = "Headless"
description = "An application that runs without default plugins"
category = "Application"
wasm = false
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
[[example]]
name = "logs"
path = "examples/app/logs.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.logs]
name = "Logs"
description = "Illustrate how to use generate log output"
category = "Application"
wasm = true
Add support for updating the tracing subscriber in LogPlugin (#10822) # Objective This PR is heavily inspired by https://github.com/bevyengine/bevy/pull/7682 It aims to solve the same problem: allowing the user to extend the tracing subscriber with extra layers. (in my case, I'd like to use `use metrics_tracing_context::{MetricsLayer, TracingContextLayer};`) ## Solution I'm proposing a different api where the user has the opportunity to take the existing `subscriber` and apply any transformations on it. --- ## Changelog - Added a `update_subscriber` option on the `LogPlugin` that lets the user modify the `subscriber` (for example to extend it with more tracing `Layers` ## Migration Guide > This section is optional. If there are no breaking changes, you can delete this section. - Added a new field `update_subscriber` in the `LogPlugin` --------- Co-authored-by: Charles Bournhonesque <cbournhonesque@snapchat.com>
2024-01-15 15:26:13 +00:00
[[example]]
name = "log_layers"
path = "examples/app/log_layers.rs"
Fix some doc warnings (#12961) # Objective - Fix some doc warnings - Add doc-scrape-examples to all examples Moved from #12692 I run `cargo +nightly doc --workspace --all-features --no-deps -Zunstable-options -Zrustdoc-scrape-examples` <details> ``` warning: public documentation for `GzAssetLoaderError` links to private item `GzAssetLoader` --> examples/asset/asset_decompression.rs:24:47 | 24 | /// Possible errors that can be produced by [`GzAssetLoader`] | ^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: `bevy` (example "asset_decompression") generated 1 warning warning: unresolved link to `shape::Quad` --> examples/2d/mesh2d.rs:3:15 | 3 | //! [`Quad`]: shape::Quad | ^^^^^^^^^^^ no item named `shape` in scope | = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "mesh2d") generated 1 warning warning: unresolved link to `WorldQuery` --> examples/ecs/custom_query_param.rs:1:49 | 1 | //! This example illustrates the usage of the [`WorldQuery`] derive macro, which allows | ^^^^^^^^^^ no item named `WorldQuery` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "custom_query_param") generated 1 warning warning: unresolved link to `shape::Quad` --> examples/2d/mesh2d_vertex_color_texture.rs:4:15 | 4 | //! [`Quad`]: shape::Quad | ^^^^^^^^^^^ no item named `shape` in scope | = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "mesh2d_vertex_color_texture") generated 1 warning warning: public documentation for `TextPlugin` links to private item `CoolText` --> examples/asset/processing/asset_processing.rs:48:9 | 48 | /// * [`CoolText`]: a custom RON text format that supports dependencies and embedded dependencies | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: public documentation for `TextPlugin` links to private item `Text` --> examples/asset/processing/asset_processing.rs:49:9 | 49 | /// * [`Text`]: a "normal" plain text file | ^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: public documentation for `TextPlugin` links to private item `CoolText` --> examples/asset/processing/asset_processing.rs:51:57 | 51 | /// It also defines an asset processor that will load [`CoolText`], resolve embedded dependenc... | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: `bevy` (example "asset_processing") generated 3 warnings warning: public documentation for `CustomAssetLoaderError` links to private item `CustomAssetLoader` --> examples/asset/custom_asset.rs:20:47 | 20 | /// Possible errors that can be produced by [`CustomAssetLoader`] | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: public documentation for `BlobAssetLoaderError` links to private item `CustomAssetLoader` --> examples/asset/custom_asset.rs:61:47 | 61 | /// Possible errors that can be produced by [`CustomAssetLoader`] | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` ``` ``` warning: `bevy` (example "mesh2d") generated 1 warning warning: public documentation for `log_layers_ecs` links to private item `update_subscriber` --> examples/app/log_layers_ecs.rs:6:18 | 6 | //! Inside the [`update_subscriber`] function we will create a [`mpsc::Sender`] and a [`mpsc::R... | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: unresolved link to `AdvancedLayer` --> examples/app/log_layers_ecs.rs:7:72 | 7 | ... will go into the [`AdvancedLayer`] and the [`Receiver`](mpsc::Receiver) will | ^^^^^^^^^^^^^ no item named `AdvancedLayer` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: unresolved link to `LogEvents` --> examples/app/log_layers_ecs.rs:8:42 | 8 | //! go into a non-send resource called [`LogEvents`] (It has to be non-send because [`Receiver`... | ^^^^^^^^^ no item named `LogEvents` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` warning: public documentation for `log_layers_ecs` links to private item `transfer_log_events` --> examples/app/log_layers_ecs.rs:9:30 | 9 | //! From there we will use [`transfer_log_events`] to transfer log events from [`LogEvents`] to... | ^^^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: unresolved link to `LogEvents` --> examples/app/log_layers_ecs.rs:9:82 | 9 | ...nsfer log events from [`LogEvents`] to an ECS event called [`LogEvent`]. | ^^^^^^^^^ no item named `LogEvents` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` warning: public documentation for `log_layers_ecs` links to private item `LogEvent` --> examples/app/log_layers_ecs.rs:9:119 | 9 | ...nts`] to an ECS event called [`LogEvent`]. | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: public documentation for `log_layers_ecs` links to private item `LogEvent` --> examples/app/log_layers_ecs.rs:11:49 | 11 | //! Finally, after all that we can access the [`LogEvent`] event from our systems and use it. | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` ``` <details/>
2024-04-14 15:23:44 +00:00
doc-scrape-examples = true
Add support for updating the tracing subscriber in LogPlugin (#10822) # Objective This PR is heavily inspired by https://github.com/bevyengine/bevy/pull/7682 It aims to solve the same problem: allowing the user to extend the tracing subscriber with extra layers. (in my case, I'd like to use `use metrics_tracing_context::{MetricsLayer, TracingContextLayer};`) ## Solution I'm proposing a different api where the user has the opportunity to take the existing `subscriber` and apply any transformations on it. --- ## Changelog - Added a `update_subscriber` option on the `LogPlugin` that lets the user modify the `subscriber` (for example to extend it with more tracing `Layers` ## Migration Guide > This section is optional. If there are no breaking changes, you can delete this section. - Added a new field `update_subscriber` in the `LogPlugin` --------- Co-authored-by: Charles Bournhonesque <cbournhonesque@snapchat.com>
2024-01-15 15:26:13 +00:00
[package.metadata.example.log_layers]
name = "Log layers"
description = "Illustrate how to add custom log layers"
category = "Application"
wasm = false
Add access to `App` within `LogPlugin::update_subscriber` (#12045) # Objective In my library, [`bevy_dev_console`](https://github.com/doonv/bevy_dev_console) I need access to `App` within `LogPlugin::update_subscriber` in order to communicate with the `App` from my custom `Layer`. ## Solution Give access to `App`. --- ## Changelog - Added access to `App` within `LogPlugin::update_subscriber` ## Migration Guide `LogPlugin::update_subscriber` now has a `&mut App` parameter. If you don't need access to `App`, you can ignore the parameter with an underscore (`_`). ```diff,rust - fn update_subscriber(subscriber: BoxedSubscriber) -> BoxedSubscriber { + fn update_subscriber(_: &mut App, subscriber: BoxedSubscriber) -> BoxedSubscriber { Box::new(subscriber.with(CustomLayer)) } ```
2024-03-04 00:01:05 +00:00
[[example]]
name = "log_layers_ecs"
path = "examples/app/log_layers_ecs.rs"
Fix some doc warnings (#12961) # Objective - Fix some doc warnings - Add doc-scrape-examples to all examples Moved from #12692 I run `cargo +nightly doc --workspace --all-features --no-deps -Zunstable-options -Zrustdoc-scrape-examples` <details> ``` warning: public documentation for `GzAssetLoaderError` links to private item `GzAssetLoader` --> examples/asset/asset_decompression.rs:24:47 | 24 | /// Possible errors that can be produced by [`GzAssetLoader`] | ^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: `bevy` (example "asset_decompression") generated 1 warning warning: unresolved link to `shape::Quad` --> examples/2d/mesh2d.rs:3:15 | 3 | //! [`Quad`]: shape::Quad | ^^^^^^^^^^^ no item named `shape` in scope | = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "mesh2d") generated 1 warning warning: unresolved link to `WorldQuery` --> examples/ecs/custom_query_param.rs:1:49 | 1 | //! This example illustrates the usage of the [`WorldQuery`] derive macro, which allows | ^^^^^^^^^^ no item named `WorldQuery` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "custom_query_param") generated 1 warning warning: unresolved link to `shape::Quad` --> examples/2d/mesh2d_vertex_color_texture.rs:4:15 | 4 | //! [`Quad`]: shape::Quad | ^^^^^^^^^^^ no item named `shape` in scope | = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "mesh2d_vertex_color_texture") generated 1 warning warning: public documentation for `TextPlugin` links to private item `CoolText` --> examples/asset/processing/asset_processing.rs:48:9 | 48 | /// * [`CoolText`]: a custom RON text format that supports dependencies and embedded dependencies | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: public documentation for `TextPlugin` links to private item `Text` --> examples/asset/processing/asset_processing.rs:49:9 | 49 | /// * [`Text`]: a "normal" plain text file | ^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: public documentation for `TextPlugin` links to private item `CoolText` --> examples/asset/processing/asset_processing.rs:51:57 | 51 | /// It also defines an asset processor that will load [`CoolText`], resolve embedded dependenc... | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: `bevy` (example "asset_processing") generated 3 warnings warning: public documentation for `CustomAssetLoaderError` links to private item `CustomAssetLoader` --> examples/asset/custom_asset.rs:20:47 | 20 | /// Possible errors that can be produced by [`CustomAssetLoader`] | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: public documentation for `BlobAssetLoaderError` links to private item `CustomAssetLoader` --> examples/asset/custom_asset.rs:61:47 | 61 | /// Possible errors that can be produced by [`CustomAssetLoader`] | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` ``` ``` warning: `bevy` (example "mesh2d") generated 1 warning warning: public documentation for `log_layers_ecs` links to private item `update_subscriber` --> examples/app/log_layers_ecs.rs:6:18 | 6 | //! Inside the [`update_subscriber`] function we will create a [`mpsc::Sender`] and a [`mpsc::R... | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: unresolved link to `AdvancedLayer` --> examples/app/log_layers_ecs.rs:7:72 | 7 | ... will go into the [`AdvancedLayer`] and the [`Receiver`](mpsc::Receiver) will | ^^^^^^^^^^^^^ no item named `AdvancedLayer` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: unresolved link to `LogEvents` --> examples/app/log_layers_ecs.rs:8:42 | 8 | //! go into a non-send resource called [`LogEvents`] (It has to be non-send because [`Receiver`... | ^^^^^^^^^ no item named `LogEvents` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` warning: public documentation for `log_layers_ecs` links to private item `transfer_log_events` --> examples/app/log_layers_ecs.rs:9:30 | 9 | //! From there we will use [`transfer_log_events`] to transfer log events from [`LogEvents`] to... | ^^^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: unresolved link to `LogEvents` --> examples/app/log_layers_ecs.rs:9:82 | 9 | ...nsfer log events from [`LogEvents`] to an ECS event called [`LogEvent`]. | ^^^^^^^^^ no item named `LogEvents` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` warning: public documentation for `log_layers_ecs` links to private item `LogEvent` --> examples/app/log_layers_ecs.rs:9:119 | 9 | ...nts`] to an ECS event called [`LogEvent`]. | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: public documentation for `log_layers_ecs` links to private item `LogEvent` --> examples/app/log_layers_ecs.rs:11:49 | 11 | //! Finally, after all that we can access the [`LogEvent`] event from our systems and use it. | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` ``` <details/>
2024-04-14 15:23:44 +00:00
doc-scrape-examples = true
Add access to `App` within `LogPlugin::update_subscriber` (#12045) # Objective In my library, [`bevy_dev_console`](https://github.com/doonv/bevy_dev_console) I need access to `App` within `LogPlugin::update_subscriber` in order to communicate with the `App` from my custom `Layer`. ## Solution Give access to `App`. --- ## Changelog - Added access to `App` within `LogPlugin::update_subscriber` ## Migration Guide `LogPlugin::update_subscriber` now has a `&mut App` parameter. If you don't need access to `App`, you can ignore the parameter with an underscore (`_`). ```diff,rust - fn update_subscriber(subscriber: BoxedSubscriber) -> BoxedSubscriber { + fn update_subscriber(_: &mut App, subscriber: BoxedSubscriber) -> BoxedSubscriber { Box::new(subscriber.with(CustomLayer)) } ```
2024-03-04 00:01:05 +00:00
[package.metadata.example.log_layers_ecs]
name = "Advanced log layers"
description = "Illustrate how to transfer data between log layers and Bevy's ECS"
category = "Application"
wasm = false
add plugin example
2020-05-03 08:30:10 +00:00
[[example]]
name = "plugin"
path = "examples/app/plugin.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
add plugin example
2020-05-03 08:30:10 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.plugin]
name = "Plugin"
description = "Demonstrates the creation and registration of a custom plugin"
category = "Application"
wasm = true
app: PluginGroups and DefaultPlugins (#744)
2020-10-29 20:04:28 +00:00
[[example]]
name = "plugin_group"
path = "examples/app/plugin_group.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
app: PluginGroups and DefaultPlugins (#744)
2020-10-29 20:04:28 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.plugin_group]
name = "Plugin Group"
description = "Demonstrates the creation and registration of a custom plugin group"
category = "Application"
wasm = true
Allow calling winit with the 'run_return' variant of the run function (#243) This adds a new WinitConfig resource that can be used to configure the behavior of winit. When `return_from_run` is set to `true`, `App::run()` will return on `target_os` configurations that support it. Closes bevyengine/bevy#167.
2020-08-21 05:37:19 +00:00
[[example]]
name = "return_after_run"
path = "examples/app/return_after_run.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Allow calling winit with the 'run_return' variant of the run function (#243) This adds a new WinitConfig resource that can be used to configure the behavior of winit. When `return_from_run` is set to `true`, `App::run()` will return on `target_os` configurations that support it. Closes bevyengine/bevy#167.
2020-08-21 05:37:19 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.return_after_run]
name = "Return after Run"
description = "Show how to return to main after the Bevy app has exited"
category = "Application"
wasm = false
Add possibility to control num_threads and stack_size of rayon::ThreadPool
2020-08-14 17:15:29 +00:00
[[example]]
name = "thread_pool_resources"
path = "examples/app/thread_pool_resources.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add possibility to control num_threads and stack_size of rayon::ThreadPool
2020-08-14 17:15:29 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.thread_pool_resources]
name = "Thread Pool Resources"
description = "Creates and customizes the internal thread pool"
category = "Application"
wasm = false
Add headless mode (#3439) # Objective In this PR I added the ability to opt-out graphical backends. Closes #3155. ## Solution I turned backends into `Option` ~~and removed panicking sub app API to force users handle the error (was suggested by `@cart`)~~.
2022-01-08 10:39:43 +00:00
[[example]]
Rename `headless_defaults` example to `no_renderer` for clarity (#5263) # Objective - Reduce confusion as the example opens a window and isn't truly "headless" - Fixes https://github.com/bevyengine/bevy/issues/5260. ## Solution - Rename the example and add to the docs that the window is expected.
2022-07-11 14:11:32 +00:00
name = "no_renderer"
path = "examples/app/no_renderer.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add headless mode (#3439) # Objective In this PR I added the ability to opt-out graphical backends. Closes #3155. ## Solution I turned backends into `Option` ~~and removed panicking sub app API to force users handle the error (was suggested by `@cart`)~~.
2022-01-08 10:39:43 +00:00
Rename `headless_defaults` example to `no_renderer` for clarity (#5263) # Objective - Reduce confusion as the example opens a window and isn't truly "headless" - Fixes https://github.com/bevyengine/bevy/issues/5260. ## Solution - Rename the example and add to the docs that the window is expected.
2022-07-11 14:11:32 +00:00
[package.metadata.example.no_renderer]
name = "No Renderer"
description = "An application that runs with default plugins and displays an empty window, but without an actual renderer"
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
category = "Application"
wasm = false
Headless renderer example has been added (#13006) # Objective Fixes #11457. Fixes #22. ## Solution Based on [another headless application](https://github.com/richardanaya/headless/) --- ## Changelog - Adopted to bevy 0.14 --------- Co-authored-by: BD103 <59022059+BD103@users.noreply.github.com> Co-authored-by: François Mockers <francois.mockers@vleue.com>
2024-05-08 14:26:26 +00:00
[[example]]
name = "headless_renderer"
path = "examples/app/headless_renderer.rs"
doc-scrape-examples = true
[package.metadata.example.headless_renderer]
name = "Headless Renderer"
description = "An application that runs with no window, but renders into image file"
category = "Application"
wasm = false
Fix crash with disabled winit (#3330) # Objective This PR fixes a crash when winit is enabled when there is a camera in the world. Part of #3155 ## Solution In this PR, I removed two unwraps and added an example for regression testing.
2021-12-15 00:15:47 +00:00
[[example]]
name = "without_winit"
path = "examples/app/without_winit.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Fix crash with disabled winit (#3330) # Objective This PR fixes a crash when winit is enabled when there is a camera in the world. Part of #3155 ## Solution In this PR, I removed two unwraps and added an example for regression testing.
2021-12-15 00:15:47 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.without_winit]
name = "Without Winit"
description = "Create an application without winit (runs single time, no event loop)"
category = "Application"
wasm = false
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
# Assets
Add sprite and mesh alteration examples (#15298) # Objective Add examples for manipulating sprites and meshes by either mutating the handle or direct manipulation of the asset, as described in #15056. Closes #3130. (The previous PR suffered a Git-tastrophe, and was unceremoniously closed, sry! :sweat_smile: ) --------- Co-authored-by: Jan Hohenheim <jan@hohenheim.ch>
2024-09-22 01:18:40 +00:00
[[example]]
name = "alter_mesh"
path = "examples/asset/alter_mesh.rs"
doc-scrape-examples = true
[package.metadata.example.alter_mesh]
name = "Alter Mesh"
description = "Shows how to modify the underlying asset of a Mesh after spawning."
category = "Assets"
wasm = false
[[example]]
name = "alter_sprite"
path = "examples/asset/alter_sprite.rs"
doc-scrape-examples = true
[package.metadata.example.alter_sprite]
name = "Alter Sprite"
description = "Shows how to modify texture assets after spawning."
category = "Assets"
wasm = false
Hot asset reloading
2020-05-17 03:18:30 +00:00
[[example]]
name = "asset_loading"
path = "examples/asset/asset_loading.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Hot asset reloading
2020-05-17 03:18:30 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.asset_loading]
name = "Asset Loading"
description = "Demonstrates various methods to load assets"
category = "Assets"
Disable asset_loading and texture_atlas examples when building for wasm / WebGPU (#8683) # Objective Remove the asset_loading and texture_atlas on the WebGPU examples page as they do not function properly. Both examples use folder loading that is not supported in a browser context and currently fail with the follow error: ``` panicked at 'called `Result::unwrap()` on an `Err` value: AssetFolderNotADirectory("textures/rpg")', examples/2d/texture_atlas.rs:31:75 ``` ## Solution Disable these examples when building for WebGPU / wasm.
2023-05-25 21:57:04 +00:00
wasm = false
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
Add example for using .meta files (#12882) # Objective - Fixes #12411 - Add an example demonstrating the usage of asset meta files. ## Solution - Add a new example displaying a basic scene of three pixelated images - Apply a .meta file to one of the assets setting Nearest filtering - Use AssetServer::load_with_settings on the last one as another way to achieve the same effect - The result is one blurry image and two crisp images demonstrating a common scenario in which changing settings are useful.
2024-04-08 17:10:56 +00:00
[[example]]
name = "asset_settings"
path = "examples/asset/asset_settings.rs"
doc-scrape-examples = true
[package.metadata.example.asset_settings]
name = "Asset Settings"
description = "Demonstrates various methods of applying settings when loading an asset"
category = "Assets"
wasm = false
Added Method to Allow Pipelined Asset Loading (#10565) # Objective - Fixes #10518 ## Solution I've added a method to `LoadContext`, `load_direct_with_reader`, which mirrors the behaviour of `load_direct` with a single key difference: it is provided with the `Reader` by the caller, rather than getting it from the contained `AssetServer`. This allows for an `AssetLoader` to process its `Reader` stream, and then directly hand the results off to the `LoadContext` to handle further loading. The outer `AssetLoader` can control how the `Reader` is interpreted by providing a relevant `AssetPath`. For example, a Gzip decompression loader could process the asset `images/my_image.png.gz` by decompressing the bytes, then handing the decompressed result to the `LoadContext` with the new path `images/my_image.png.gz/my_image.png`. This intuitively reflects the nature of contained assets, whilst avoiding unintended behaviour, since the generated path cannot be a real file path (a file and folder of the same name cannot coexist in most file-systems). ```rust #[derive(Asset, TypePath)] pub struct GzAsset { pub uncompressed: ErasedLoadedAsset, } #[derive(Default)] pub struct GzAssetLoader; impl AssetLoader for GzAssetLoader { type Asset = GzAsset; type Settings = (); type Error = GzAssetLoaderError; fn load<'a>( &'a self, reader: &'a mut Reader, _settings: &'a (), load_context: &'a mut LoadContext, ) -> BoxedFuture<'a, Result<Self::Asset, Self::Error>> { Box::pin(async move { let compressed_path = load_context.path(); let file_name = compressed_path .file_name() .ok_or(GzAssetLoaderError::IndeterminateFilePath)? .to_string_lossy(); let uncompressed_file_name = file_name .strip_suffix(".gz") .ok_or(GzAssetLoaderError::IndeterminateFilePath)?; let contained_path = compressed_path.join(uncompressed_file_name); let mut bytes_compressed = Vec::new(); reader.read_to_end(&mut bytes_compressed).await?; let mut decoder = GzDecoder::new(bytes_compressed.as_slice()); let mut bytes_uncompressed = Vec::new(); decoder.read_to_end(&mut bytes_uncompressed)?; // Now that we have decompressed the asset, let's pass it back to the // context to continue loading let mut reader = VecReader::new(bytes_uncompressed); let uncompressed = load_context .load_direct_with_reader(&mut reader, contained_path) .await?; Ok(GzAsset { uncompressed }) }) } fn extensions(&self) -> &[&str] { &["gz"] } } ``` Because this example is so prudent, I've included an `asset_decompression` example which implements this exact behaviour: ```rust fn main() { App::new() .add_plugins(DefaultPlugins) .init_asset::<GzAsset>() .init_asset_loader::<GzAssetLoader>() .add_systems(Startup, setup) .add_systems(Update, decompress::<Image>) .run(); } fn setup(mut commands: Commands, asset_server: Res<AssetServer>) { commands.spawn(Camera2dBundle::default()); commands.spawn(( Compressed::<Image> { compressed: asset_server.load("data/compressed_image.png.gz"), ..default() }, Sprite::default(), TransformBundle::default(), VisibilityBundle::default(), )); } fn decompress<A: Asset>( mut commands: Commands, asset_server: Res<AssetServer>, mut compressed_assets: ResMut<Assets<GzAsset>>, query: Query<(Entity, &Compressed<A>)>, ) { for (entity, Compressed { compressed, .. }) in query.iter() { let Some(GzAsset { uncompressed }) = compressed_assets.remove(compressed) else { continue; }; let uncompressed = uncompressed.take::<A>().unwrap(); commands .entity(entity) .remove::<Compressed<A>>() .insert(asset_server.add(uncompressed)); } } ``` A key limitation to this design is how to type the internally loaded asset, since the example `GzAssetLoader` is unaware of the internal asset type `A`. As such, in this example I store the contained asset as an `ErasedLoadedAsset`, and leave it up to the consumer of the `GzAsset` to handle typing the final result, which is the purpose of the `decompress` system. This limitation can be worked around by providing type information to the `GzAssetLoader`, such as `GzAssetLoader<Image, ImageAssetLoader>`, but this would require registering the asset loader for every possible decompression target. Aside from this limitation, nested asset containerisation works as an end user would expect; if the user registers a `TarAssetLoader`, and a `GzAssetLoader`, then they can load assets with compound containerisation, such as `images.tar.gz`. --- ## Changelog - Added `LoadContext::load_direct_with_reader` - Added `asset_decompression` example ## Notes - While I believe my implementation of a Gzip asset loader is reasonable, I haven't included it as a public feature of `bevy_asset` to keep the scope of this PR as focussed as possible. - I have included `flate2` as a `dev-dependency` for the example; it is not included in the main dependency graph.
2023-11-16 17:47:31 +00:00
[[example]]
name = "asset_decompression"
path = "examples/asset/asset_decompression.rs"
doc-scrape-examples = true
[package.metadata.example.asset_decompression]
name = "Asset Decompression"
description = "Demonstrates loading a compressed asset"
category = "Assets"
wasm = false
Add AppBuilder::asset_loader_from_instance (#580) * Implement add_asset_loader_from_instance * Add example of different data loaders
2020-10-01 18:31:06 +00:00
[[example]]
Asset system rework and GLTF scene loading (#693)
2020-10-18 20:48:15 +00:00
name = "custom_asset"
path = "examples/asset/custom_asset.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add AppBuilder::asset_loader_from_instance (#580) * Implement add_asset_loader_from_instance * Add example of different data loaders
2020-10-01 18:31:06 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.custom_asset]
name = "Custom Asset"
description = "Implements a custom asset loader"
category = "Assets"
wasm = true
add ability to provide custom a `AssetIo` implementation (#1037) make it easier to override the default asset IO instance
2020-12-18 19:34:44 +00:00
[[example]]
Bevy Asset V2 (#8624) # Bevy Asset V2 Proposal ## Why Does Bevy Need A New Asset System? Asset pipelines are a central part of the gamedev process. Bevy's current asset system is missing a number of features that make it non-viable for many classes of gamedev. After plenty of discussions and [a long community feedback period](https://github.com/bevyengine/bevy/discussions/3972), we've identified a number missing features: * **Asset Preprocessing**: it should be possible to "preprocess" / "compile" / "crunch" assets at "development time" rather than when the game starts up. This enables offloading expensive work from deployed apps, faster asset loading, less runtime memory usage, etc. * **Per-Asset Loader Settings**: Individual assets cannot define their own loaders that override the defaults. Additionally, they cannot provide per-asset settings to their loaders. This is a huge limitation, as many asset types don't provide all information necessary for Bevy _inside_ the asset. For example, a raw PNG image says nothing about how it should be sampled (ex: linear vs nearest). * **Asset `.meta` files**: assets should have configuration files stored adjacent to the asset in question, which allows the user to configure asset-type-specific settings. These settings should be accessible during the pre-processing phase. Modifying a `.meta` file should trigger a re-processing / re-load of the asset. It should be possible to configure asset loaders from the meta file. * **Processed Asset Hot Reloading**: Changes to processed assets (or their dependencies) should result in re-processing them and re-loading the results in live Bevy Apps. * **Asset Dependency Tracking**: The current bevy_asset has no good way to wait for asset dependencies to load. It punts this as an exercise for consumers of the loader apis, which is unreasonable and error prone. There should be easy, ergonomic ways to wait for assets to load and block some logic on an asset's entire dependency tree loading. * **Runtime Asset Loading**: it should be (optionally) possible to load arbitrary assets dynamically at runtime. This necessitates being able to deploy and run the asset server alongside Bevy Apps on _all platforms_. For example, we should be able to invoke the shader compiler at runtime, stream scenes from sources like the internet, etc. To keep deployed binaries (and startup times) small, the runtime asset server configuration should be configurable with different settings compared to the "pre processor asset server". * **Multiple Backends**: It should be possible to load assets from arbitrary sources (filesystems, the internet, remote asset serves, etc). * **Asset Packing**: It should be possible to deploy assets in compressed "packs", which makes it easier and more efficient to distribute assets with Bevy Apps. * **Asset Handoff**: It should be possible to hold a "live" asset handle, which correlates to runtime data, without actually holding the asset in memory. Ex: it must be possible to hold a reference to a GPU mesh generated from a "mesh asset" without keeping the mesh data in CPU memory * **Per-Platform Processed Assets**: Different platforms and app distributions have different capabilities and requirements. Some platforms need lower asset resolutions or different asset formats to operate within the hardware constraints of the platform. It should be possible to define per-platform asset processing profiles. And it should be possible to deploy only the assets required for a given platform. These features have architectural implications that are significant enough to require a full rewrite. The current Bevy Asset implementation got us this far, but it can take us no farther. This PR defines a brand new asset system that implements most of these features, while laying the foundations for the remaining features to be built. ## Bevy Asset V2 Here is a quick overview of the features introduced in this PR. * **Asset Preprocessing**: Preprocess assets at development time into more efficient (and configurable) representations * **Dependency Aware**: Dependencies required to process an asset are tracked. If an asset's processed dependency changes, it will be reprocessed * **Hot Reprocessing/Reloading**: detect changes to asset source files, reprocess them if they have changed, and then hot-reload them in Bevy Apps. * **Only Process Changes**: Assets are only re-processed when their source file (or meta file) has changed. This uses hashing and timestamps to avoid processing assets that haven't changed. * **Transactional and Reliable**: Uses write-ahead logging (a technique commonly used by databases) to recover from crashes / forced-exits. Whenever possible it avoids full-reprocessing / only uncompleted transactions will be reprocessed. When the processor is running in parallel with a Bevy App, processor asset writes block Bevy App asset reads. Reading metadata + asset bytes is guaranteed to be transactional / correctly paired. * **Portable / Run anywhere / Database-free**: The processor does not rely on an in-memory database (although it uses some database techniques for reliability). This is important because pretty much all in-memory databases have unsupported platforms or build complications. * **Configure Processor Defaults Per File Type**: You can say "use this processor for all files of this type". * **Custom Processors**: The `Processor` trait is flexible and unopinionated. It can be implemented by downstream plugins. * **LoadAndSave Processors**: Most asset processing scenarios can be expressed as "run AssetLoader A, save the results using AssetSaver X, and then load the result using AssetLoader B". For example, load this png image using `PngImageLoader`, which produces an `Image` asset and then save it using `CompressedImageSaver` (which also produces an `Image` asset, but in a compressed format), which takes an `Image` asset as input. This means if you have an `AssetLoader` for an asset, you are already half way there! It also means that you can share AssetSavers across multiple loaders. Because `CompressedImageSaver` accepts Bevy's generic Image asset as input, it means you can also use it with some future `JpegImageLoader`. * **Loader and Saver Settings**: Asset Loaders and Savers can now define their own settings types, which are passed in as input when an asset is loaded / saved. Each asset can define its own settings. * **Asset `.meta` files**: configure asset loaders, their settings, enable/disable processing, and configure processor settings * **Runtime Asset Dependency Tracking** Runtime asset dependencies (ex: if an asset contains a `Handle<Image>`) are tracked by the asset server. An event is emitted when an asset and all of its dependencies have been loaded * **Unprocessed Asset Loading**: Assets do not require preprocessing. They can be loaded directly. A processed asset is just a "normal" asset with some extra metadata. Asset Loaders don't need to know or care about whether or not an asset was processed. * **Async Asset IO**: Asset readers/writers use async non-blocking interfaces. Note that because Rust doesn't yet support async traits, there is a bit of manual Boxing / Future boilerplate. This will hopefully be removed in the near future when Rust gets async traits. * **Pluggable Asset Readers and Writers**: Arbitrary asset source readers/writers are supported, both by the processor and the asset server. * **Better Asset Handles** * **Single Arc Tree**: Asset Handles now use a single arc tree that represents the lifetime of the asset. This makes their implementation simpler, more efficient, and allows us to cheaply attach metadata to handles. Ex: the AssetPath of a handle is now directly accessible on the handle itself! * **Const Typed Handles**: typed handles can be constructed in a const context. No more weird "const untyped converted to typed at runtime" patterns! * **Handles and Ids are Smaller / Faster To Hash / Compare**: Typed `Handle<T>` is now much smaller in memory and `AssetId<T>` is even smaller. * **Weak Handle Usage Reduction**: In general Handles are now considered to be "strong". Bevy features that previously used "weak `Handle<T>`" have been ported to `AssetId<T>`, which makes it statically clear that the features do not hold strong handles (while retaining strong type information). Currently Handle::Weak still exists, but it is very possible that we can remove that entirely. * **Efficient / Dense Asset Ids**: Assets now have efficient dense runtime asset ids, which means we can avoid expensive hash lookups. Assets are stored in Vecs instead of HashMaps. There are now typed and untyped ids, which means we no longer need to store dynamic type information in the ID for typed handles. "AssetPathId" (which was a nightmare from a performance and correctness standpoint) has been entirely removed in favor of dense ids (which are retrieved for a path on load) * **Direct Asset Loading, with Dependency Tracking**: Assets that are defined at runtime can still have their dependencies tracked by the Asset Server (ex: if you create a material at runtime, you can still wait for its textures to load). This is accomplished via the (currently optional) "asset dependency visitor" trait. This system can also be used to define a set of assets to load, then wait for those assets to load. * **Async folder loading**: Folder loading also uses this system and immediately returns a handle to the LoadedFolder asset, which means folder loading no longer blocks on directory traversals. * **Improved Loader Interface**: Loaders now have a specific "top level asset type", which makes returning the top-level asset simpler and statically typed. * **Basic Image Settings and Processing**: Image assets can now be processed into the gpu-friendly Basic Universal format. The ImageLoader now has a setting to define what format the image should be loaded as. Note that this is just a minimal MVP ... plenty of additional work to do here. To demo this, enable the `basis-universal` feature and turn on asset processing. * **Simpler Audio Play / AudioSink API**: Asset handle providers are cloneable, which means the Audio resource can mint its own handles. This means you can now do `let sink_handle = audio.play(music)` instead of `let sink_handle = audio_sinks.get_handle(audio.play(music))`. Note that this might still be replaced by https://github.com/bevyengine/bevy/pull/8424. **Removed Handle Casting From Engine Features**: Ex: FontAtlases no longer use casting between handle types ## Using The New Asset System ### Normal Unprocessed Asset Loading By default the `AssetPlugin` does not use processing. It behaves pretty much the same way as the old system. If you are defining a custom asset, first derive `Asset`: ```rust #[derive(Asset)] struct Thing { value: String, } ``` Initialize the asset: ```rust app.init_asset:<Thing>() ``` Implement a new `AssetLoader` for it: ```rust #[derive(Default)] struct ThingLoader; #[derive(Serialize, Deserialize, Default)] pub struct ThingSettings { some_setting: bool, } impl AssetLoader for ThingLoader { type Asset = Thing; type Settings = ThingSettings; fn load<'a>( &'a self, reader: &'a mut Reader, settings: &'a ThingSettings, load_context: &'a mut LoadContext, ) -> BoxedFuture<'a, Result<Thing, anyhow::Error>> { Box::pin(async move { let mut bytes = Vec::new(); reader.read_to_end(&mut bytes).await?; // convert bytes to value somehow Ok(Thing { value }) }) } fn extensions(&self) -> &[&str] { &["thing"] } } ``` Note that this interface will get much cleaner once Rust gets support for async traits. `Reader` is an async futures_io::AsyncRead. You can stream bytes as they come in or read them all into a `Vec<u8>`, depending on the context. You can use `let handle = load_context.load(path)` to kick off a dependency load, retrieve a handle, and register the dependency for the asset. Then just register the loader in your Bevy app: ```rust app.init_asset_loader::<ThingLoader>() ``` Now just add your `Thing` asset files into the `assets` folder and load them like this: ```rust fn system(asset_server: Res<AssetServer>) { let handle = Handle<Thing> = asset_server.load("cool.thing"); } ``` You can check load states directly via the asset server: ```rust if asset_server.load_state(&handle) == LoadState::Loaded { } ``` You can also listen for events: ```rust fn system(mut events: EventReader<AssetEvent<Thing>>, handle: Res<SomeThingHandle>) { for event in events.iter() { if event.is_loaded_with_dependencies(&handle) { } } } ``` Note the new `AssetEvent::LoadedWithDependencies`, which only fires when the asset is loaded _and_ all dependencies (and their dependencies) have loaded. Unlike the old asset system, for a given asset path all `Handle<T>` values point to the same underlying Arc. This means Handles can cheaply hold more asset information, such as the AssetPath: ```rust // prints the AssetPath of the handle info!("{:?}", handle.path()) ``` ### Processed Assets Asset processing can be enabled via the `AssetPlugin`. When developing Bevy Apps with processed assets, do this: ```rust app.add_plugins(DefaultPlugins.set(AssetPlugin::processed_dev())) ``` This runs the `AssetProcessor` in the background with hot-reloading. It reads assets from the `assets` folder, processes them, and writes them to the `.imported_assets` folder. Asset loads in the Bevy App will wait for a processed version of the asset to become available. If an asset in the `assets` folder changes, it will be reprocessed and hot-reloaded in the Bevy App. When deploying processed Bevy apps, do this: ```rust app.add_plugins(DefaultPlugins.set(AssetPlugin::processed())) ``` This does not run the `AssetProcessor` in the background. It behaves like `AssetPlugin::unprocessed()`, but reads assets from `.imported_assets`. When the `AssetProcessor` is running, it will populate sibling `.meta` files for assets in the `assets` folder. Meta files for assets that do not have a processor configured look like this: ```rust ( meta_format_version: "1.0", asset: Load( loader: "bevy_render::texture::image_loader::ImageLoader", settings: ( format: FromExtension, ), ), ) ``` This is metadata for an image asset. For example, if you have `assets/my_sprite.png`, this could be the metadata stored at `assets/my_sprite.png.meta`. Meta files are totally optional. If no metadata exists, the default settings will be used. In short, this file says "load this asset with the ImageLoader and use the file extension to determine the image type". This type of meta file is supported in all AssetPlugin modes. If in `Unprocessed` mode, the asset (with the meta settings) will be loaded directly. If in `ProcessedDev` mode, the asset file will be copied directly to the `.imported_assets` folder. The meta will also be copied directly to the `.imported_assets` folder, but with one addition: ```rust ( meta_format_version: "1.0", processed_info: Some(( hash: 12415480888597742505, full_hash: 14344495437905856884, process_dependencies: [], )), asset: Load( loader: "bevy_render::texture::image_loader::ImageLoader", settings: ( format: FromExtension, ), ), ) ``` `processed_info` contains `hash` (a direct hash of the asset and meta bytes), `full_hash` (a hash of `hash` and the hashes of all `process_dependencies`), and `process_dependencies` (the `path` and `full_hash` of every process_dependency). A "process dependency" is an asset dependency that is _directly_ used when processing the asset. Images do not have process dependencies, so this is empty. When the processor is enabled, you can use the `Process` metadata config: ```rust ( meta_format_version: "1.0", asset: Process( processor: "bevy_asset::processor::process::LoadAndSave<bevy_render::texture::image_loader::ImageLoader, bevy_render::texture::compressed_image_saver::CompressedImageSaver>", settings: ( loader_settings: ( format: FromExtension, ), saver_settings: ( generate_mipmaps: true, ), ), ), ) ``` This configures the asset to use the `LoadAndSave` processor, which runs an AssetLoader and feeds the result into an AssetSaver (which saves the given Asset and defines a loader to load it with). (for terseness LoadAndSave will likely get a shorter/friendlier type name when [Stable Type Paths](#7184) lands). `LoadAndSave` is likely to be the most common processor type, but arbitrary processors are supported. `CompressedImageSaver` saves an `Image` in the Basis Universal format and configures the ImageLoader to load it as basis universal. The `AssetProcessor` will read this meta, run it through the LoadAndSave processor, and write the basis-universal version of the image to `.imported_assets`. The final metadata will look like this: ```rust ( meta_format_version: "1.0", processed_info: Some(( hash: 905599590923828066, full_hash: 9948823010183819117, process_dependencies: [], )), asset: Load( loader: "bevy_render::texture::image_loader::ImageLoader", settings: ( format: Format(Basis), ), ), ) ``` To try basis-universal processing out in Bevy examples, (for example `sprite.rs`), change `add_plugins(DefaultPlugins)` to `add_plugins(DefaultPlugins.set(AssetPlugin::processed_dev()))` and run with the `basis-universal` feature enabled: `cargo run --features=basis-universal --example sprite`. To create a custom processor, there are two main paths: 1. Use the `LoadAndSave` processor with an existing `AssetLoader`. Implement the `AssetSaver` trait, register the processor using `asset_processor.register_processor::<LoadAndSave<ImageLoader, CompressedImageSaver>>(image_saver.into())`. 2. Implement the `Process` trait directly and register it using: `asset_processor.register_processor(thing_processor)`. You can configure default processors for file extensions like this: ```rust asset_processor.set_default_processor::<ThingProcessor>("thing") ``` There is one more metadata type to be aware of: ```rust ( meta_format_version: "1.0", asset: Ignore, ) ``` This will ignore the asset during processing / prevent it from being written to `.imported_assets`. The AssetProcessor stores a transaction log at `.imported_assets/log` and uses it to gracefully recover from unexpected stops. This means you can force-quit the processor (and Bevy Apps running the processor in parallel) at arbitrary times! `.imported_assets` is "local state". It should _not_ be checked into source control. It should also be considered "read only". In practice, you _can_ modify processed assets and processed metadata if you really need to test something. But those modifications will not be represented in the hashes of the assets, so the processed state will be "out of sync" with the source assets. The processor _will not_ fix this for you. Either revert the change after you have tested it, or delete the processed files so they can be re-populated. ## Open Questions There are a number of open questions to be discussed. We should decide if they need to be addressed in this PR and if so, how we will address them: ### Implied Dependencies vs Dependency Enumeration There are currently two ways to populate asset dependencies: * **Implied via AssetLoaders**: if an AssetLoader loads an asset (and retrieves a handle), a dependency is added to the list. * **Explicit via the optional Asset::visit_dependencies**: if `server.load_asset(my_asset)` is called, it will call `my_asset.visit_dependencies`, which will grab dependencies that have been manually defined for the asset via the Asset trait impl (which can be derived). This means that defining explicit dependencies is optional for "loaded assets". And the list of dependencies is always accurate because loaders can only produce Handles if they register dependencies. If an asset was loaded with an AssetLoader, it only uses the implied dependencies. If an asset was created at runtime and added with `asset_server.load_asset(MyAsset)`, it will use `Asset::visit_dependencies`. However this can create a behavior mismatch between loaded assets and equivalent "created at runtime" assets if `Assets::visit_dependencies` doesn't exactly match the dependencies produced by the AssetLoader. This behavior mismatch can be resolved by completely removing "implied loader dependencies" and requiring `Asset::visit_dependencies` to supply dependency data. But this creates two problems: * It makes defining loaded assets harder and more error prone: Devs must remember to manually annotate asset dependencies with `#[dependency]` when deriving `Asset`. For more complicated assets (such as scenes), the derive likely wouldn't be sufficient and a manual `visit_dependencies` impl would be required. * Removes the ability to immediately kick off dependency loads: When AssetLoaders retrieve a Handle, they also immediately kick off an asset load for the handle, which means it can start loading in parallel _before_ the asset finishes loading. For large assets, this could be significant. (although this could be mitigated for processed assets if we store dependencies in the processed meta file and load them ahead of time) ### Eager ProcessorDev Asset Loading I made a controversial call in the interest of fast startup times ("time to first pixel") for the "processor dev mode configuration". When initializing the AssetProcessor, current processed versions of unchanged assets are yielded immediately, even if their dependencies haven't been checked yet for reprocessing. This means that non-current-state-of-filesystem-but-previously-valid assets might be returned to the App first, then hot-reloaded if/when their dependencies change and the asset is reprocessed. Is this behavior desirable? There is largely one alternative: do not yield an asset from the processor to the app until all of its dependencies have been checked for changes. In some common cases (load dependency has not changed since last run) this will increase startup time. The main question is "by how much" and is that slower startup time worth it in the interest of only yielding assets that are true to the current state of the filesystem. Should this be configurable? I'm starting to think we should only yield an asset after its (historical) dependencies have been checked for changes + processed as necessary, but I'm curious what you all think. ### Paths Are Currently The Only Canonical ID / Do We Want Asset UUIDs? In this implementation AssetPaths are the only canonical asset identifier (just like the previous Bevy Asset system and Godot). Moving assets will result in re-scans (and currently reprocessing, although reprocessing can easily be avoided with some changes). Asset renames/moves will break code and assets that rely on specific paths, unless those paths are fixed up. Do we want / need "stable asset uuids"? Introducing them is very possible: 1. Generate a UUID and include it in .meta files 2. Support UUID in AssetPath 3. Generate "asset indices" which are loaded on startup and map UUIDs to paths. 4 (maybe). Consider only supporting UUIDs for processed assets so we can generate quick-to-load indices instead of scanning meta files. The main "pro" is that assets referencing UUIDs don't need to be migrated when a path changes. The main "con" is that UUIDs cannot be "lazily resolved" like paths. They need a full view of all assets to answer the question "does this UUID exist". Which means UUIDs require the AssetProcessor to fully finish startup scans before saying an asset doesnt exist. And they essentially require asset pre-processing to use in apps, because scanning all asset metadata files at runtime to resolve a UUID is not viable for medium-to-large apps. It really requires a pre-generated UUID index, which must be loaded before querying for assets. I personally think this should be investigated in a separate PR. Paths aren't going anywhere ... _everyone_ uses filesystems (and filesystem-like apis) to manage their asset source files. I consider them permanent canonical asset information. Additionally, they behave well for both processed and unprocessed asset modes. Given that Bevy is supporting both, this feels like the right canonical ID to start with. UUIDS (and maybe even other indexed-identifier types) can be added later as necessary. ### Folder / File Naming Conventions All asset processing config currently lives in the `.imported_assets` folder. The processor transaction log is in `.imported_assets/log`. Processed assets are added to `.imported_assets/Default`, which will make migrating to processed asset profiles (ex: a `.imported_assets/Mobile` profile) a non-breaking change. It also allows us to create top-level files like `.imported_assets/log` without it being interpreted as an asset. Meta files currently have a `.meta` suffix. Do we like these names and conventions? ### Should the `AssetPlugin::processed_dev` configuration enable `watch_for_changes` automatically? Currently it does (which I think makes sense), but it does make it the only configuration that enables watch_for_changes by default. ### Discuss on_loaded High Level Interface: This PR includes a very rough "proof of concept" `on_loaded` system adapter that uses the `LoadedWithDependencies` event in combination with `asset_server.load_asset` dependency tracking to support this pattern ```rust fn main() { App::new() .init_asset::<MyAssets>() .add_systems(Update, on_loaded(create_array_texture)) .run(); } #[derive(Asset, Clone)] struct MyAssets { #[dependency] picture_of_my_cat: Handle<Image>, #[dependency] picture_of_my_other_cat: Handle<Image>, } impl FromWorld for ArrayTexture { fn from_world(world: &mut World) -> Self { picture_of_my_cat: server.load("meow.png"), picture_of_my_other_cat: server.load("meeeeeeeow.png"), } } fn spawn_cat(In(my_assets): In<MyAssets>, mut commands: Commands) { commands.spawn(SpriteBundle { texture: my_assets.picture_of_my_cat.clone(), ..default() }); commands.spawn(SpriteBundle { texture: my_assets.picture_of_my_other_cat.clone(), ..default() }); } ``` The implementation is _very_ rough. And it is currently unsafe because `bevy_ecs` doesn't expose some internals to do this safely from inside `bevy_asset`. There are plenty of unanswered questions like: * "do we add a Loadable" derive? (effectively automate the FromWorld implementation above) * Should `MyAssets` even be an Asset? (largely implemented this way because it elegantly builds on `server.load_asset(MyAsset { .. })` dependency tracking). We should think hard about what our ideal API looks like (and if this is a pattern we want to support). Not necessarily something we need to solve in this PR. The current `on_loaded` impl should probably be removed from this PR before merging. ## Clarifying Questions ### What about Assets as Entities? This Bevy Asset V2 proposal implementation initially stored Assets as ECS Entities. Instead of `AssetId<T>` + the `Assets<T>` resource it used `Entity` as the asset id and Asset values were just ECS components. There are plenty of compelling reasons to do this: 1. Easier to inline assets in Bevy Scenes (as they are "just" normal entities + components) 2. More flexible queries: use the power of the ECS to filter assets (ex: `Query<Mesh, With<Tree>>`). 3. Extensible. Users can add arbitrary component data to assets. 4. Things like "component visualization tools" work out of the box to visualize asset data. However Assets as Entities has a ton of caveats right now: * We need to be able to allocate entity ids without a direct World reference (aka rework id allocator in Entities ... i worked around this in my prototypes by just pre allocating big chunks of entities) * We want asset change events in addition to ECS change tracking ... how do we populate them when mutations can come from anywhere? Do we use Changed queries? This would require iterating over the change data for all assets every frame. Is this acceptable or should we implement a new "event based" component change detection option? * Reconciling manually created assets with asset-system managed assets has some nuance (ex: are they "loaded" / do they also have that component metadata?) * "how do we handle "static" / default entity handles" (ties in to the Entity Indices discussion: https://github.com/bevyengine/bevy/discussions/8319). This is necessary for things like "built in" assets and default handles in things like SpriteBundle. * Storing asset information as a component makes it easy to "invalidate" asset state by removing the component (or forcing modifications). Ideally we have ways to lock this down (some combination of Rust type privacy and ECS validation) In practice, how we store and identify assets is a reasonably superficial change (porting off of Assets as Entities and implementing dedicated storage + ids took less than a day). So once we sort out the remaining challenges the flip should be straightforward. Additionally, I do still have "Assets as Entities" in my commit history, so we can reuse that work. I personally think "assets as entities" is a good endgame, but it also doesn't provide _significant_ value at the moment and it certainly isn't ready yet with the current state of things. ### Why not Distill? [Distill](https://github.com/amethyst/distill) is a high quality fully featured asset system built in Rust. It is very natural to ask "why not just use Distill?". It is also worth calling out that for awhile, [we planned on adopting Distill / I signed off on it](https://github.com/bevyengine/bevy/issues/708). However I think Bevy has a number of constraints that make Distill adoption suboptimal: * **Architectural Simplicity:** * Distill's processor requires an in-memory database (lmdb) and RPC networked API (using Cap'n Proto). Each of these introduces API complexity that increases maintenance burden and "code grokability". Ignoring tests, documentation, and examples, Distill has 24,237 lines of Rust code (including generated code for RPC + database interactions). If you ignore generated code, it has 11,499 lines. * Bevy builds the AssetProcessor and AssetServer using pluggable AssetReader/AssetWriter Rust traits with simple io interfaces. They do not necessitate databases or RPC interfaces (although Readers/Writers could use them if that is desired). Bevy Asset V2 (at the time of writing this PR) is 5,384 lines of Rust code (ignoring tests, documentation, and examples). Grain of salt: Distill does have more features currently (ex: Asset Packing, GUIDS, remote-out-of-process asset processor). I do plan to implement these features in Bevy Asset V2 and I personally highly doubt they will meaningfully close the 6115 lines-of-code gap. * This complexity gap (which while illustrated by lines of code, is much bigger than just that) is noteworthy to me. Bevy should be hackable and there are pillars of Distill that are very hard to understand and extend. This is a matter of opinion (and Bevy Asset V2 also has complicated areas), but I think Bevy Asset V2 is much more approachable for the average developer. * Necessary disclaimer: counting lines of code is an extremely rough complexity metric. Read the code and form your own opinions. * **Optional Asset Processing:** Not all Bevy Apps (or Bevy App developers) need / want asset preprocessing. Processing increases the complexity of the development environment by introducing things like meta files, imported asset storage, running processors in the background, waiting for processing to finish, etc. Distill _requires_ preprocessing to work. With Bevy Asset V2 processing is fully opt-in. The AssetServer isn't directly aware of asset processors at all. AssetLoaders only care about converting bytes to runtime Assets ... they don't know or care if the bytes were pre-processed or not. Processing is "elegantly" (forgive my self-congratulatory phrasing) layered on top and builds on the existing Asset system primitives. * **Direct Filesystem Access to Processed Asset State:** Distill stores processed assets in a database. This makes debugging / inspecting the processed outputs harder (either requires special tooling to query the database or they need to be "deployed" to be inspected). Bevy Asset V2, on the other hand, stores processed assets in the filesystem (by default ... this is configurable). This makes interacting with the processed state more natural. Note that both Godot and Unity's new asset system store processed assets in the filesystem. * **Portability**: Because Distill's processor uses lmdb and RPC networking, it cannot be run on certain platforms (ex: lmdb is a non-rust dependency that cannot run on the web, some platforms don't support running network servers). Bevy should be able to process assets everywhere (ex: run the Bevy Editor on the web, compile + process shaders on mobile, etc). Distill does partially mitigate this problem by supporting "streaming" assets via the RPC protocol, but this is not a full solve from my perspective. And Bevy Asset V2 can (in theory) also stream assets (without requiring RPC, although this isn't implemented yet) Note that I _do_ still think Distill would be a solid asset system for Bevy. But I think the approach in this PR is a better solve for Bevy's specific "asset system requirements". ### Doesn't async-fs just shim requests to "sync" `std::fs`? What is the point? "True async file io" has limited / spotty platform support. async-fs (and the rust async ecosystem generally ... ex Tokio) currently use async wrappers over std::fs that offload blocking requests to separate threads. This may feel unsatisfying, but it _does_ still provide value because it prevents our task pools from blocking on file system operations (which would prevent progress when there are many tasks to do, but all threads in a pool are currently blocking on file system ops). Additionally, using async APIs for our AssetReaders and AssetWriters also provides value because we can later add support for "true async file io" for platforms that support it. _And_ we can implement other "true async io" asset backends (such as networked asset io). ## Draft TODO - [x] Fill in missing filesystem event APIs: file removed event (which is expressed as dangling RenameFrom events in some cases), file/folder renamed event - [x] Assets without loaders are not moved to the processed folder. This breaks things like referenced `.bin` files for GLTFs. This should be configurable per-non-asset-type. - [x] Initial implementation of Reflect and FromReflect for Handle. The "deserialization" parity bar is low here as this only worked with static UUIDs in the old impl ... this is a non-trivial problem. Either we add a Handle::AssetPath variant that gets "upgraded" to a strong handle on scene load or we use a separate AssetRef type for Bevy scenes (which is converted to a runtime Handle on load). This deserves its own discussion in a different pr. - [x] Populate read_asset_bytes hash when run by the processor (a bit of a special case .. when run by the processor the processed meta will contain the hash so we don't need to compute it on the spot, but we don't want/need to read the meta when run by the main AssetServer) - [x] Delay hot reloading: currently filesystem events are handled immediately, which creates timing issues in some cases. For example hot reloading images can sometimes break because the image isn't finished writing. We should add a delay, likely similar to the [implementation in this PR](https://github.com/bevyengine/bevy/pull/8503). - [x] Port old platform-specific AssetIo implementations to the new AssetReader interface (currently missing Android and web) - [x] Resolve on_loaded unsafety (either by removing the API entirely or removing the unsafe) - [x] Runtime loader setting overrides - [x] Remove remaining unwraps that should be error-handled. There are number of TODOs here - [x] Pretty AssetPath Display impl - [x] Document more APIs - [x] Resolve spurious "reloading because it has changed" events (to repro run load_gltf with `processed_dev()`) - [x] load_dependency hot reloading currently only works for processed assets. If processing is disabled, load_dependency changes are not hot reloaded. - [x] Replace AssetInfo dependency load/fail counters with `loading_dependencies: HashSet<UntypedAssetId>` to prevent reloads from (potentially) breaking counters. Storing this will also enable "dependency reloaded" events (see [Next Steps](#next-steps)) - [x] Re-add filesystem watcher cargo feature gate (currently it is not optional) - [ ] Migration Guide - [ ] Changelog ## Followup TODO - [ ] Replace "eager unchanged processed asset loading" behavior with "don't returned unchanged processed asset until dependencies have been checked". - [ ] Add true `Ignore` AssetAction that does not copy the asset to the imported_assets folder. - [ ] Finish "live asset unloading" (ex: free up CPU asset memory after uploading an image to the GPU), rethink RenderAssets, and port renderer features. The `Assets` collection uses `Option<T>` for asset storage to support its removal. (1) the Option might not actually be necessary ... might be able to just remove from the collection entirely (2) need to finalize removal apis - [ ] Try replacing the "channel based" asset id recycling with something a bit more efficient (ex: we might be able to use raw atomic ints with some cleverness) - [ ] Consider adding UUIDs to processed assets (scoped just to helping identify moved assets ... not exposed to load queries ... see [Next Steps](#next-steps)) - [ ] Store "last modified" source asset and meta timestamps in processed meta files to enable skipping expensive hashing when the file wasn't changed - [ ] Fix "slow loop" handle drop fix - [ ] Migrate to TypeName - [x] Handle "loader preregistration". See #9429 ## Next Steps * **Configurable per-type defaults for AssetMeta**: It should be possible to add configuration like "all png image meta should default to using nearest sampling" (currently this hard-coded per-loader/processor Settings::default() impls). Also see the "Folder Meta" bullet point. * **Avoid Reprocessing on Asset Renames / Moves**: See the "canonical asset ids" discussion in [Open Questions](#open-questions) and the relevant bullet point in [Draft TODO](#draft-todo). Even without canonical ids, folder renames could avoid reprocessing in some cases. * **Multiple Asset Sources**: Expand AssetPath to support "asset source names" and support multiple AssetReaders in the asset server (ex: `webserver://some_path/image.png` backed by an Http webserver AssetReader). The "default" asset reader would use normal `some_path/image.png` paths. Ideally this works in combination with multiple AssetWatchers for hot-reloading * **Stable Type Names**: this pr removes the TypeUuid requirement from assets in favor of `std::any::type_name`. This makes defining assets easier (no need to generate a new uuid / use weird proc macro syntax). It also makes reading meta files easier (because things have "friendly names"). We also use type names for components in scene files. If they are good enough for components, they are good enough for assets. And consistency across Bevy pillars is desirable. However, `std::any::type_name` is not guaranteed to be stable (although in practice it is). We've developed a [stable type path](https://github.com/bevyengine/bevy/pull/7184) to resolve this, which should be adopted when it is ready. * **Command Line Interface**: It should be possible to run the asset processor in a separate process from the command line. This will also require building a network-server-backed AssetReader to communicate between the app and the processor. We've been planning to build a "bevy cli" for awhile. This seems like a good excuse to build it. * **Asset Packing**: This is largely an additive feature, so it made sense to me to punt this until we've laid the foundations in this PR. * **Per-Platform Processed Assets**: It should be possible to generate assets for multiple platforms by supporting multiple "processor profiles" per asset (ex: compress with format X on PC and Y on iOS). I think there should probably be arbitrary "profiles" (which can be separate from actual platforms), which are then assigned to a given platform when generating the final asset distribution for that platform. Ex: maybe devs want a "Mobile" profile that is shared between iOS and Android. Or a "LowEnd" profile shared between web and mobile. * **Versioning and Migrations**: Assets, Loaders, Savers, and Processors need to have versions to determine if their schema is valid. If an asset / loader version is incompatible with the current version expected at runtime, the processor should be able to migrate them. I think we should try using Bevy Reflect for this, as it would allow us to load the old version as a dynamic Reflect type without actually having the old Rust type. It would also allow us to define "patches" to migrate between versions (Bevy Reflect devs are currently working on patching). The `.meta` file already has its own format version. Migrating that to new versions should also be possible. * **Real Copy-on-write AssetPaths**: Rust's actual Cow (clone-on-write type) currently used by AssetPath can still result in String clones that aren't actually necessary (cloning an Owned Cow clones the contents). Bevy's asset system requires cloning AssetPaths in a number of places, which result in actual clones of the internal Strings. This is not efficient. AssetPath internals should be reworked to exhibit truer cow-like-behavior that reduces String clones to the absolute minimum. * **Consider processor-less processing**: In theory the AssetServer could run processors "inline" even if the background AssetProcessor is disabled. If we decide this is actually desirable, we could add this. But I don't think its a priority in the short or medium term. * **Pre-emptive dependency loading**: We could encode dependencies in processed meta files, which could then be used by the Asset Server to kick of dependency loads as early as possible (prior to starting the actual asset load). Is this desirable? How much time would this save in practice? * **Optimize Processor With UntypedAssetIds**: The processor exclusively uses AssetPath to identify assets currently. It might be possible to swap these out for UntypedAssetIds in some places, which are smaller / cheaper to hash and compare. * **One to Many Asset Processing**: An asset source file that produces many assets currently must be processed into a single "processed" asset source. If labeled assets can be written separately they can each have their own configured savers _and_ they could be loaded more granularly. Definitely worth exploring! * **Automatically Track "Runtime-only" Asset Dependencies**: Right now, tracking "created at runtime" asset dependencies requires adding them via `asset_server.load_asset(StandardMaterial::default())`. I think with some cleverness we could also do this for `materials.add(StandardMaterial::default())`, making tracking work "everywhere". There are challenges here relating to change detection / ensuring the server is made aware of dependency changes. This could be expensive in some cases. * **"Dependency Changed" events**: Some assets have runtime artifacts that need to be re-generated when one of their dependencies change (ex: regenerate a material's bind group when a Texture needs to change). We are generating the dependency graph so we can definitely produce these events. Buuuuut generating these events will have a cost / they could be high frequency for some assets, so we might want this to be opt-in for specific cases. * **Investigate Storing More Information In Handles**: Handles can now store arbitrary information, which makes it cheaper and easier to access. How much should we move into them? Canonical asset load states (via atomics)? (`handle.is_loaded()` would be very cool). Should we store the entire asset and remove the `Assets<T>` collection? (`Arc<RwLock<Option<Image>>>`?) * **Support processing and loading files without extensions**: This is a pretty arbitrary restriction and could be supported with very minimal changes. * **Folder Meta**: It would be nice if we could define per folder processor configuration defaults (likely in a `.meta` or `.folder_meta` file). Things like "default to linear filtering for all Images in this folder". * **Replace async_broadcast with event-listener?** This might be approximately drop-in for some uses and it feels more light weight * **Support Running the AssetProcessor on the Web**: Most of the hard work is done here, but there are some easy straggling TODOs (make the transaction log an interface instead of a direct file writer so we can write a web storage backend, implement an AssetReader/AssetWriter that reads/writes to something like LocalStorage). * **Consider identifying and preventing circular dependencies**: This is especially important for "processor dependencies", as processing will silently never finish in these cases. * **Built-in/Inlined Asset Hot Reloading**: This PR regresses "built-in/inlined" asset hot reloading (previously provided by the DebugAssetServer). I'm intentionally punting this because I think it can be cleanly implemented with "multiple asset sources" by registering a "debug asset source" (ex: `debug://bevy_pbr/src/render/pbr.wgsl` asset paths) in combination with an AssetWatcher for that asset source and support for "manually loading pats with asset bytes instead of AssetReaders". The old DebugAssetServer was quite nasty and I'd love to avoid that hackery going forward. * **Investigate ways to remove double-parsing meta files**: Parsing meta files currently involves parsing once with "minimal" versions of the meta file to extract the type name of the loader/processor config, then parsing again to parse the "full" meta. This is suboptimal. We should be able to define custom deserializers that (1) assume the loader/processor type name comes first (2) dynamically looks up the loader/processor registrations to deserialize settings in-line (similar to components in the bevy scene format). Another alternative: deserialize as dynamic Reflect objects and then convert. * **More runtime loading configuration**: Support using the Handle type as a hint to select an asset loader (instead of relying on AssetPath extensions) * **More high level Processor trait implementations**: For example, it might be worth adding support for arbitrary chains of "asset transforms" that modify an in-memory asset representation between loading and saving. (ex: load a Mesh, run a `subdivide_mesh` transform, followed by a `flip_normals` transform, then save the mesh to an efficient compressed format). * **Bevy Scene Handle Deserialization**: (see the relevant [Draft TODO item](#draft-todo) for context) * **Explore High Level Load Interfaces**: See [this discussion](#discuss-on_loaded-high-level-interface) for one prototype. * **Asset Streaming**: It would be great if we could stream Assets (ex: stream a long video file piece by piece) * **ID Exchanging**: In this PR Asset Handles/AssetIds are bigger than they need to be because they have a Uuid enum variant. If we implement an "id exchanging" system that trades Uuids for "efficient runtime ids", we can cut down on the size of AssetIds, making them more efficient. This has some open design questions, such as how to spawn entities with "default" handle values (as these wouldn't have access to the exchange api in the current system). * **Asset Path Fixup Tooling**: Assets that inline asset paths inside them will break when an asset moves. The asset system provides the functionality to detect when paths break. We should build a framework that enables formats to define "path migrations". This is especially important for scene files. For editor-generated files, we should also consider using UUIDs (see other bullet point) to avoid the need to migrate in these cases. --------- Co-authored-by: BeastLe9enD <beastle9end@outlook.de> Co-authored-by: Mike <mike.hsu@gmail.com> Co-authored-by: Nicola Papale <nicopap@users.noreply.github.com>
2023-09-07 02:07:27 +00:00
name = "custom_asset_reader"
path = "examples/asset/custom_asset_reader.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
add ability to provide custom a `AssetIo` implementation (#1037) make it easier to override the default asset IO instance
2020-12-18 19:34:44 +00:00
Bevy Asset V2 (#8624) # Bevy Asset V2 Proposal ## Why Does Bevy Need A New Asset System? Asset pipelines are a central part of the gamedev process. Bevy's current asset system is missing a number of features that make it non-viable for many classes of gamedev. After plenty of discussions and [a long community feedback period](https://github.com/bevyengine/bevy/discussions/3972), we've identified a number missing features: * **Asset Preprocessing**: it should be possible to "preprocess" / "compile" / "crunch" assets at "development time" rather than when the game starts up. This enables offloading expensive work from deployed apps, faster asset loading, less runtime memory usage, etc. * **Per-Asset Loader Settings**: Individual assets cannot define their own loaders that override the defaults. Additionally, they cannot provide per-asset settings to their loaders. This is a huge limitation, as many asset types don't provide all information necessary for Bevy _inside_ the asset. For example, a raw PNG image says nothing about how it should be sampled (ex: linear vs nearest). * **Asset `.meta` files**: assets should have configuration files stored adjacent to the asset in question, which allows the user to configure asset-type-specific settings. These settings should be accessible during the pre-processing phase. Modifying a `.meta` file should trigger a re-processing / re-load of the asset. It should be possible to configure asset loaders from the meta file. * **Processed Asset Hot Reloading**: Changes to processed assets (or their dependencies) should result in re-processing them and re-loading the results in live Bevy Apps. * **Asset Dependency Tracking**: The current bevy_asset has no good way to wait for asset dependencies to load. It punts this as an exercise for consumers of the loader apis, which is unreasonable and error prone. There should be easy, ergonomic ways to wait for assets to load and block some logic on an asset's entire dependency tree loading. * **Runtime Asset Loading**: it should be (optionally) possible to load arbitrary assets dynamically at runtime. This necessitates being able to deploy and run the asset server alongside Bevy Apps on _all platforms_. For example, we should be able to invoke the shader compiler at runtime, stream scenes from sources like the internet, etc. To keep deployed binaries (and startup times) small, the runtime asset server configuration should be configurable with different settings compared to the "pre processor asset server". * **Multiple Backends**: It should be possible to load assets from arbitrary sources (filesystems, the internet, remote asset serves, etc). * **Asset Packing**: It should be possible to deploy assets in compressed "packs", which makes it easier and more efficient to distribute assets with Bevy Apps. * **Asset Handoff**: It should be possible to hold a "live" asset handle, which correlates to runtime data, without actually holding the asset in memory. Ex: it must be possible to hold a reference to a GPU mesh generated from a "mesh asset" without keeping the mesh data in CPU memory * **Per-Platform Processed Assets**: Different platforms and app distributions have different capabilities and requirements. Some platforms need lower asset resolutions or different asset formats to operate within the hardware constraints of the platform. It should be possible to define per-platform asset processing profiles. And it should be possible to deploy only the assets required for a given platform. These features have architectural implications that are significant enough to require a full rewrite. The current Bevy Asset implementation got us this far, but it can take us no farther. This PR defines a brand new asset system that implements most of these features, while laying the foundations for the remaining features to be built. ## Bevy Asset V2 Here is a quick overview of the features introduced in this PR. * **Asset Preprocessing**: Preprocess assets at development time into more efficient (and configurable) representations * **Dependency Aware**: Dependencies required to process an asset are tracked. If an asset's processed dependency changes, it will be reprocessed * **Hot Reprocessing/Reloading**: detect changes to asset source files, reprocess them if they have changed, and then hot-reload them in Bevy Apps. * **Only Process Changes**: Assets are only re-processed when their source file (or meta file) has changed. This uses hashing and timestamps to avoid processing assets that haven't changed. * **Transactional and Reliable**: Uses write-ahead logging (a technique commonly used by databases) to recover from crashes / forced-exits. Whenever possible it avoids full-reprocessing / only uncompleted transactions will be reprocessed. When the processor is running in parallel with a Bevy App, processor asset writes block Bevy App asset reads. Reading metadata + asset bytes is guaranteed to be transactional / correctly paired. * **Portable / Run anywhere / Database-free**: The processor does not rely on an in-memory database (although it uses some database techniques for reliability). This is important because pretty much all in-memory databases have unsupported platforms or build complications. * **Configure Processor Defaults Per File Type**: You can say "use this processor for all files of this type". * **Custom Processors**: The `Processor` trait is flexible and unopinionated. It can be implemented by downstream plugins. * **LoadAndSave Processors**: Most asset processing scenarios can be expressed as "run AssetLoader A, save the results using AssetSaver X, and then load the result using AssetLoader B". For example, load this png image using `PngImageLoader`, which produces an `Image` asset and then save it using `CompressedImageSaver` (which also produces an `Image` asset, but in a compressed format), which takes an `Image` asset as input. This means if you have an `AssetLoader` for an asset, you are already half way there! It also means that you can share AssetSavers across multiple loaders. Because `CompressedImageSaver` accepts Bevy's generic Image asset as input, it means you can also use it with some future `JpegImageLoader`. * **Loader and Saver Settings**: Asset Loaders and Savers can now define their own settings types, which are passed in as input when an asset is loaded / saved. Each asset can define its own settings. * **Asset `.meta` files**: configure asset loaders, their settings, enable/disable processing, and configure processor settings * **Runtime Asset Dependency Tracking** Runtime asset dependencies (ex: if an asset contains a `Handle<Image>`) are tracked by the asset server. An event is emitted when an asset and all of its dependencies have been loaded * **Unprocessed Asset Loading**: Assets do not require preprocessing. They can be loaded directly. A processed asset is just a "normal" asset with some extra metadata. Asset Loaders don't need to know or care about whether or not an asset was processed. * **Async Asset IO**: Asset readers/writers use async non-blocking interfaces. Note that because Rust doesn't yet support async traits, there is a bit of manual Boxing / Future boilerplate. This will hopefully be removed in the near future when Rust gets async traits. * **Pluggable Asset Readers and Writers**: Arbitrary asset source readers/writers are supported, both by the processor and the asset server. * **Better Asset Handles** * **Single Arc Tree**: Asset Handles now use a single arc tree that represents the lifetime of the asset. This makes their implementation simpler, more efficient, and allows us to cheaply attach metadata to handles. Ex: the AssetPath of a handle is now directly accessible on the handle itself! * **Const Typed Handles**: typed handles can be constructed in a const context. No more weird "const untyped converted to typed at runtime" patterns! * **Handles and Ids are Smaller / Faster To Hash / Compare**: Typed `Handle<T>` is now much smaller in memory and `AssetId<T>` is even smaller. * **Weak Handle Usage Reduction**: In general Handles are now considered to be "strong". Bevy features that previously used "weak `Handle<T>`" have been ported to `AssetId<T>`, which makes it statically clear that the features do not hold strong handles (while retaining strong type information). Currently Handle::Weak still exists, but it is very possible that we can remove that entirely. * **Efficient / Dense Asset Ids**: Assets now have efficient dense runtime asset ids, which means we can avoid expensive hash lookups. Assets are stored in Vecs instead of HashMaps. There are now typed and untyped ids, which means we no longer need to store dynamic type information in the ID for typed handles. "AssetPathId" (which was a nightmare from a performance and correctness standpoint) has been entirely removed in favor of dense ids (which are retrieved for a path on load) * **Direct Asset Loading, with Dependency Tracking**: Assets that are defined at runtime can still have their dependencies tracked by the Asset Server (ex: if you create a material at runtime, you can still wait for its textures to load). This is accomplished via the (currently optional) "asset dependency visitor" trait. This system can also be used to define a set of assets to load, then wait for those assets to load. * **Async folder loading**: Folder loading also uses this system and immediately returns a handle to the LoadedFolder asset, which means folder loading no longer blocks on directory traversals. * **Improved Loader Interface**: Loaders now have a specific "top level asset type", which makes returning the top-level asset simpler and statically typed. * **Basic Image Settings and Processing**: Image assets can now be processed into the gpu-friendly Basic Universal format. The ImageLoader now has a setting to define what format the image should be loaded as. Note that this is just a minimal MVP ... plenty of additional work to do here. To demo this, enable the `basis-universal` feature and turn on asset processing. * **Simpler Audio Play / AudioSink API**: Asset handle providers are cloneable, which means the Audio resource can mint its own handles. This means you can now do `let sink_handle = audio.play(music)` instead of `let sink_handle = audio_sinks.get_handle(audio.play(music))`. Note that this might still be replaced by https://github.com/bevyengine/bevy/pull/8424. **Removed Handle Casting From Engine Features**: Ex: FontAtlases no longer use casting between handle types ## Using The New Asset System ### Normal Unprocessed Asset Loading By default the `AssetPlugin` does not use processing. It behaves pretty much the same way as the old system. If you are defining a custom asset, first derive `Asset`: ```rust #[derive(Asset)] struct Thing { value: String, } ``` Initialize the asset: ```rust app.init_asset:<Thing>() ``` Implement a new `AssetLoader` for it: ```rust #[derive(Default)] struct ThingLoader; #[derive(Serialize, Deserialize, Default)] pub struct ThingSettings { some_setting: bool, } impl AssetLoader for ThingLoader { type Asset = Thing; type Settings = ThingSettings; fn load<'a>( &'a self, reader: &'a mut Reader, settings: &'a ThingSettings, load_context: &'a mut LoadContext, ) -> BoxedFuture<'a, Result<Thing, anyhow::Error>> { Box::pin(async move { let mut bytes = Vec::new(); reader.read_to_end(&mut bytes).await?; // convert bytes to value somehow Ok(Thing { value }) }) } fn extensions(&self) -> &[&str] { &["thing"] } } ``` Note that this interface will get much cleaner once Rust gets support for async traits. `Reader` is an async futures_io::AsyncRead. You can stream bytes as they come in or read them all into a `Vec<u8>`, depending on the context. You can use `let handle = load_context.load(path)` to kick off a dependency load, retrieve a handle, and register the dependency for the asset. Then just register the loader in your Bevy app: ```rust app.init_asset_loader::<ThingLoader>() ``` Now just add your `Thing` asset files into the `assets` folder and load them like this: ```rust fn system(asset_server: Res<AssetServer>) { let handle = Handle<Thing> = asset_server.load("cool.thing"); } ``` You can check load states directly via the asset server: ```rust if asset_server.load_state(&handle) == LoadState::Loaded { } ``` You can also listen for events: ```rust fn system(mut events: EventReader<AssetEvent<Thing>>, handle: Res<SomeThingHandle>) { for event in events.iter() { if event.is_loaded_with_dependencies(&handle) { } } } ``` Note the new `AssetEvent::LoadedWithDependencies`, which only fires when the asset is loaded _and_ all dependencies (and their dependencies) have loaded. Unlike the old asset system, for a given asset path all `Handle<T>` values point to the same underlying Arc. This means Handles can cheaply hold more asset information, such as the AssetPath: ```rust // prints the AssetPath of the handle info!("{:?}", handle.path()) ``` ### Processed Assets Asset processing can be enabled via the `AssetPlugin`. When developing Bevy Apps with processed assets, do this: ```rust app.add_plugins(DefaultPlugins.set(AssetPlugin::processed_dev())) ``` This runs the `AssetProcessor` in the background with hot-reloading. It reads assets from the `assets` folder, processes them, and writes them to the `.imported_assets` folder. Asset loads in the Bevy App will wait for a processed version of the asset to become available. If an asset in the `assets` folder changes, it will be reprocessed and hot-reloaded in the Bevy App. When deploying processed Bevy apps, do this: ```rust app.add_plugins(DefaultPlugins.set(AssetPlugin::processed())) ``` This does not run the `AssetProcessor` in the background. It behaves like `AssetPlugin::unprocessed()`, but reads assets from `.imported_assets`. When the `AssetProcessor` is running, it will populate sibling `.meta` files for assets in the `assets` folder. Meta files for assets that do not have a processor configured look like this: ```rust ( meta_format_version: "1.0", asset: Load( loader: "bevy_render::texture::image_loader::ImageLoader", settings: ( format: FromExtension, ), ), ) ``` This is metadata for an image asset. For example, if you have `assets/my_sprite.png`, this could be the metadata stored at `assets/my_sprite.png.meta`. Meta files are totally optional. If no metadata exists, the default settings will be used. In short, this file says "load this asset with the ImageLoader and use the file extension to determine the image type". This type of meta file is supported in all AssetPlugin modes. If in `Unprocessed` mode, the asset (with the meta settings) will be loaded directly. If in `ProcessedDev` mode, the asset file will be copied directly to the `.imported_assets` folder. The meta will also be copied directly to the `.imported_assets` folder, but with one addition: ```rust ( meta_format_version: "1.0", processed_info: Some(( hash: 12415480888597742505, full_hash: 14344495437905856884, process_dependencies: [], )), asset: Load( loader: "bevy_render::texture::image_loader::ImageLoader", settings: ( format: FromExtension, ), ), ) ``` `processed_info` contains `hash` (a direct hash of the asset and meta bytes), `full_hash` (a hash of `hash` and the hashes of all `process_dependencies`), and `process_dependencies` (the `path` and `full_hash` of every process_dependency). A "process dependency" is an asset dependency that is _directly_ used when processing the asset. Images do not have process dependencies, so this is empty. When the processor is enabled, you can use the `Process` metadata config: ```rust ( meta_format_version: "1.0", asset: Process( processor: "bevy_asset::processor::process::LoadAndSave<bevy_render::texture::image_loader::ImageLoader, bevy_render::texture::compressed_image_saver::CompressedImageSaver>", settings: ( loader_settings: ( format: FromExtension, ), saver_settings: ( generate_mipmaps: true, ), ), ), ) ``` This configures the asset to use the `LoadAndSave` processor, which runs an AssetLoader and feeds the result into an AssetSaver (which saves the given Asset and defines a loader to load it with). (for terseness LoadAndSave will likely get a shorter/friendlier type name when [Stable Type Paths](#7184) lands). `LoadAndSave` is likely to be the most common processor type, but arbitrary processors are supported. `CompressedImageSaver` saves an `Image` in the Basis Universal format and configures the ImageLoader to load it as basis universal. The `AssetProcessor` will read this meta, run it through the LoadAndSave processor, and write the basis-universal version of the image to `.imported_assets`. The final metadata will look like this: ```rust ( meta_format_version: "1.0", processed_info: Some(( hash: 905599590923828066, full_hash: 9948823010183819117, process_dependencies: [], )), asset: Load( loader: "bevy_render::texture::image_loader::ImageLoader", settings: ( format: Format(Basis), ), ), ) ``` To try basis-universal processing out in Bevy examples, (for example `sprite.rs`), change `add_plugins(DefaultPlugins)` to `add_plugins(DefaultPlugins.set(AssetPlugin::processed_dev()))` and run with the `basis-universal` feature enabled: `cargo run --features=basis-universal --example sprite`. To create a custom processor, there are two main paths: 1. Use the `LoadAndSave` processor with an existing `AssetLoader`. Implement the `AssetSaver` trait, register the processor using `asset_processor.register_processor::<LoadAndSave<ImageLoader, CompressedImageSaver>>(image_saver.into())`. 2. Implement the `Process` trait directly and register it using: `asset_processor.register_processor(thing_processor)`. You can configure default processors for file extensions like this: ```rust asset_processor.set_default_processor::<ThingProcessor>("thing") ``` There is one more metadata type to be aware of: ```rust ( meta_format_version: "1.0", asset: Ignore, ) ``` This will ignore the asset during processing / prevent it from being written to `.imported_assets`. The AssetProcessor stores a transaction log at `.imported_assets/log` and uses it to gracefully recover from unexpected stops. This means you can force-quit the processor (and Bevy Apps running the processor in parallel) at arbitrary times! `.imported_assets` is "local state". It should _not_ be checked into source control. It should also be considered "read only". In practice, you _can_ modify processed assets and processed metadata if you really need to test something. But those modifications will not be represented in the hashes of the assets, so the processed state will be "out of sync" with the source assets. The processor _will not_ fix this for you. Either revert the change after you have tested it, or delete the processed files so they can be re-populated. ## Open Questions There are a number of open questions to be discussed. We should decide if they need to be addressed in this PR and if so, how we will address them: ### Implied Dependencies vs Dependency Enumeration There are currently two ways to populate asset dependencies: * **Implied via AssetLoaders**: if an AssetLoader loads an asset (and retrieves a handle), a dependency is added to the list. * **Explicit via the optional Asset::visit_dependencies**: if `server.load_asset(my_asset)` is called, it will call `my_asset.visit_dependencies`, which will grab dependencies that have been manually defined for the asset via the Asset trait impl (which can be derived). This means that defining explicit dependencies is optional for "loaded assets". And the list of dependencies is always accurate because loaders can only produce Handles if they register dependencies. If an asset was loaded with an AssetLoader, it only uses the implied dependencies. If an asset was created at runtime and added with `asset_server.load_asset(MyAsset)`, it will use `Asset::visit_dependencies`. However this can create a behavior mismatch between loaded assets and equivalent "created at runtime" assets if `Assets::visit_dependencies` doesn't exactly match the dependencies produced by the AssetLoader. This behavior mismatch can be resolved by completely removing "implied loader dependencies" and requiring `Asset::visit_dependencies` to supply dependency data. But this creates two problems: * It makes defining loaded assets harder and more error prone: Devs must remember to manually annotate asset dependencies with `#[dependency]` when deriving `Asset`. For more complicated assets (such as scenes), the derive likely wouldn't be sufficient and a manual `visit_dependencies` impl would be required. * Removes the ability to immediately kick off dependency loads: When AssetLoaders retrieve a Handle, they also immediately kick off an asset load for the handle, which means it can start loading in parallel _before_ the asset finishes loading. For large assets, this could be significant. (although this could be mitigated for processed assets if we store dependencies in the processed meta file and load them ahead of time) ### Eager ProcessorDev Asset Loading I made a controversial call in the interest of fast startup times ("time to first pixel") for the "processor dev mode configuration". When initializing the AssetProcessor, current processed versions of unchanged assets are yielded immediately, even if their dependencies haven't been checked yet for reprocessing. This means that non-current-state-of-filesystem-but-previously-valid assets might be returned to the App first, then hot-reloaded if/when their dependencies change and the asset is reprocessed. Is this behavior desirable? There is largely one alternative: do not yield an asset from the processor to the app until all of its dependencies have been checked for changes. In some common cases (load dependency has not changed since last run) this will increase startup time. The main question is "by how much" and is that slower startup time worth it in the interest of only yielding assets that are true to the current state of the filesystem. Should this be configurable? I'm starting to think we should only yield an asset after its (historical) dependencies have been checked for changes + processed as necessary, but I'm curious what you all think. ### Paths Are Currently The Only Canonical ID / Do We Want Asset UUIDs? In this implementation AssetPaths are the only canonical asset identifier (just like the previous Bevy Asset system and Godot). Moving assets will result in re-scans (and currently reprocessing, although reprocessing can easily be avoided with some changes). Asset renames/moves will break code and assets that rely on specific paths, unless those paths are fixed up. Do we want / need "stable asset uuids"? Introducing them is very possible: 1. Generate a UUID and include it in .meta files 2. Support UUID in AssetPath 3. Generate "asset indices" which are loaded on startup and map UUIDs to paths. 4 (maybe). Consider only supporting UUIDs for processed assets so we can generate quick-to-load indices instead of scanning meta files. The main "pro" is that assets referencing UUIDs don't need to be migrated when a path changes. The main "con" is that UUIDs cannot be "lazily resolved" like paths. They need a full view of all assets to answer the question "does this UUID exist". Which means UUIDs require the AssetProcessor to fully finish startup scans before saying an asset doesnt exist. And they essentially require asset pre-processing to use in apps, because scanning all asset metadata files at runtime to resolve a UUID is not viable for medium-to-large apps. It really requires a pre-generated UUID index, which must be loaded before querying for assets. I personally think this should be investigated in a separate PR. Paths aren't going anywhere ... _everyone_ uses filesystems (and filesystem-like apis) to manage their asset source files. I consider them permanent canonical asset information. Additionally, they behave well for both processed and unprocessed asset modes. Given that Bevy is supporting both, this feels like the right canonical ID to start with. UUIDS (and maybe even other indexed-identifier types) can be added later as necessary. ### Folder / File Naming Conventions All asset processing config currently lives in the `.imported_assets` folder. The processor transaction log is in `.imported_assets/log`. Processed assets are added to `.imported_assets/Default`, which will make migrating to processed asset profiles (ex: a `.imported_assets/Mobile` profile) a non-breaking change. It also allows us to create top-level files like `.imported_assets/log` without it being interpreted as an asset. Meta files currently have a `.meta` suffix. Do we like these names and conventions? ### Should the `AssetPlugin::processed_dev` configuration enable `watch_for_changes` automatically? Currently it does (which I think makes sense), but it does make it the only configuration that enables watch_for_changes by default. ### Discuss on_loaded High Level Interface: This PR includes a very rough "proof of concept" `on_loaded` system adapter that uses the `LoadedWithDependencies` event in combination with `asset_server.load_asset` dependency tracking to support this pattern ```rust fn main() { App::new() .init_asset::<MyAssets>() .add_systems(Update, on_loaded(create_array_texture)) .run(); } #[derive(Asset, Clone)] struct MyAssets { #[dependency] picture_of_my_cat: Handle<Image>, #[dependency] picture_of_my_other_cat: Handle<Image>, } impl FromWorld for ArrayTexture { fn from_world(world: &mut World) -> Self { picture_of_my_cat: server.load("meow.png"), picture_of_my_other_cat: server.load("meeeeeeeow.png"), } } fn spawn_cat(In(my_assets): In<MyAssets>, mut commands: Commands) { commands.spawn(SpriteBundle { texture: my_assets.picture_of_my_cat.clone(), ..default() }); commands.spawn(SpriteBundle { texture: my_assets.picture_of_my_other_cat.clone(), ..default() }); } ``` The implementation is _very_ rough. And it is currently unsafe because `bevy_ecs` doesn't expose some internals to do this safely from inside `bevy_asset`. There are plenty of unanswered questions like: * "do we add a Loadable" derive? (effectively automate the FromWorld implementation above) * Should `MyAssets` even be an Asset? (largely implemented this way because it elegantly builds on `server.load_asset(MyAsset { .. })` dependency tracking). We should think hard about what our ideal API looks like (and if this is a pattern we want to support). Not necessarily something we need to solve in this PR. The current `on_loaded` impl should probably be removed from this PR before merging. ## Clarifying Questions ### What about Assets as Entities? This Bevy Asset V2 proposal implementation initially stored Assets as ECS Entities. Instead of `AssetId<T>` + the `Assets<T>` resource it used `Entity` as the asset id and Asset values were just ECS components. There are plenty of compelling reasons to do this: 1. Easier to inline assets in Bevy Scenes (as they are "just" normal entities + components) 2. More flexible queries: use the power of the ECS to filter assets (ex: `Query<Mesh, With<Tree>>`). 3. Extensible. Users can add arbitrary component data to assets. 4. Things like "component visualization tools" work out of the box to visualize asset data. However Assets as Entities has a ton of caveats right now: * We need to be able to allocate entity ids without a direct World reference (aka rework id allocator in Entities ... i worked around this in my prototypes by just pre allocating big chunks of entities) * We want asset change events in addition to ECS change tracking ... how do we populate them when mutations can come from anywhere? Do we use Changed queries? This would require iterating over the change data for all assets every frame. Is this acceptable or should we implement a new "event based" component change detection option? * Reconciling manually created assets with asset-system managed assets has some nuance (ex: are they "loaded" / do they also have that component metadata?) * "how do we handle "static" / default entity handles" (ties in to the Entity Indices discussion: https://github.com/bevyengine/bevy/discussions/8319). This is necessary for things like "built in" assets and default handles in things like SpriteBundle. * Storing asset information as a component makes it easy to "invalidate" asset state by removing the component (or forcing modifications). Ideally we have ways to lock this down (some combination of Rust type privacy and ECS validation) In practice, how we store and identify assets is a reasonably superficial change (porting off of Assets as Entities and implementing dedicated storage + ids took less than a day). So once we sort out the remaining challenges the flip should be straightforward. Additionally, I do still have "Assets as Entities" in my commit history, so we can reuse that work. I personally think "assets as entities" is a good endgame, but it also doesn't provide _significant_ value at the moment and it certainly isn't ready yet with the current state of things. ### Why not Distill? [Distill](https://github.com/amethyst/distill) is a high quality fully featured asset system built in Rust. It is very natural to ask "why not just use Distill?". It is also worth calling out that for awhile, [we planned on adopting Distill / I signed off on it](https://github.com/bevyengine/bevy/issues/708). However I think Bevy has a number of constraints that make Distill adoption suboptimal: * **Architectural Simplicity:** * Distill's processor requires an in-memory database (lmdb) and RPC networked API (using Cap'n Proto). Each of these introduces API complexity that increases maintenance burden and "code grokability". Ignoring tests, documentation, and examples, Distill has 24,237 lines of Rust code (including generated code for RPC + database interactions). If you ignore generated code, it has 11,499 lines. * Bevy builds the AssetProcessor and AssetServer using pluggable AssetReader/AssetWriter Rust traits with simple io interfaces. They do not necessitate databases or RPC interfaces (although Readers/Writers could use them if that is desired). Bevy Asset V2 (at the time of writing this PR) is 5,384 lines of Rust code (ignoring tests, documentation, and examples). Grain of salt: Distill does have more features currently (ex: Asset Packing, GUIDS, remote-out-of-process asset processor). I do plan to implement these features in Bevy Asset V2 and I personally highly doubt they will meaningfully close the 6115 lines-of-code gap. * This complexity gap (which while illustrated by lines of code, is much bigger than just that) is noteworthy to me. Bevy should be hackable and there are pillars of Distill that are very hard to understand and extend. This is a matter of opinion (and Bevy Asset V2 also has complicated areas), but I think Bevy Asset V2 is much more approachable for the average developer. * Necessary disclaimer: counting lines of code is an extremely rough complexity metric. Read the code and form your own opinions. * **Optional Asset Processing:** Not all Bevy Apps (or Bevy App developers) need / want asset preprocessing. Processing increases the complexity of the development environment by introducing things like meta files, imported asset storage, running processors in the background, waiting for processing to finish, etc. Distill _requires_ preprocessing to work. With Bevy Asset V2 processing is fully opt-in. The AssetServer isn't directly aware of asset processors at all. AssetLoaders only care about converting bytes to runtime Assets ... they don't know or care if the bytes were pre-processed or not. Processing is "elegantly" (forgive my self-congratulatory phrasing) layered on top and builds on the existing Asset system primitives. * **Direct Filesystem Access to Processed Asset State:** Distill stores processed assets in a database. This makes debugging / inspecting the processed outputs harder (either requires special tooling to query the database or they need to be "deployed" to be inspected). Bevy Asset V2, on the other hand, stores processed assets in the filesystem (by default ... this is configurable). This makes interacting with the processed state more natural. Note that both Godot and Unity's new asset system store processed assets in the filesystem. * **Portability**: Because Distill's processor uses lmdb and RPC networking, it cannot be run on certain platforms (ex: lmdb is a non-rust dependency that cannot run on the web, some platforms don't support running network servers). Bevy should be able to process assets everywhere (ex: run the Bevy Editor on the web, compile + process shaders on mobile, etc). Distill does partially mitigate this problem by supporting "streaming" assets via the RPC protocol, but this is not a full solve from my perspective. And Bevy Asset V2 can (in theory) also stream assets (without requiring RPC, although this isn't implemented yet) Note that I _do_ still think Distill would be a solid asset system for Bevy. But I think the approach in this PR is a better solve for Bevy's specific "asset system requirements". ### Doesn't async-fs just shim requests to "sync" `std::fs`? What is the point? "True async file io" has limited / spotty platform support. async-fs (and the rust async ecosystem generally ... ex Tokio) currently use async wrappers over std::fs that offload blocking requests to separate threads. This may feel unsatisfying, but it _does_ still provide value because it prevents our task pools from blocking on file system operations (which would prevent progress when there are many tasks to do, but all threads in a pool are currently blocking on file system ops). Additionally, using async APIs for our AssetReaders and AssetWriters also provides value because we can later add support for "true async file io" for platforms that support it. _And_ we can implement other "true async io" asset backends (such as networked asset io). ## Draft TODO - [x] Fill in missing filesystem event APIs: file removed event (which is expressed as dangling RenameFrom events in some cases), file/folder renamed event - [x] Assets without loaders are not moved to the processed folder. This breaks things like referenced `.bin` files for GLTFs. This should be configurable per-non-asset-type. - [x] Initial implementation of Reflect and FromReflect for Handle. The "deserialization" parity bar is low here as this only worked with static UUIDs in the old impl ... this is a non-trivial problem. Either we add a Handle::AssetPath variant that gets "upgraded" to a strong handle on scene load or we use a separate AssetRef type for Bevy scenes (which is converted to a runtime Handle on load). This deserves its own discussion in a different pr. - [x] Populate read_asset_bytes hash when run by the processor (a bit of a special case .. when run by the processor the processed meta will contain the hash so we don't need to compute it on the spot, but we don't want/need to read the meta when run by the main AssetServer) - [x] Delay hot reloading: currently filesystem events are handled immediately, which creates timing issues in some cases. For example hot reloading images can sometimes break because the image isn't finished writing. We should add a delay, likely similar to the [implementation in this PR](https://github.com/bevyengine/bevy/pull/8503). - [x] Port old platform-specific AssetIo implementations to the new AssetReader interface (currently missing Android and web) - [x] Resolve on_loaded unsafety (either by removing the API entirely or removing the unsafe) - [x] Runtime loader setting overrides - [x] Remove remaining unwraps that should be error-handled. There are number of TODOs here - [x] Pretty AssetPath Display impl - [x] Document more APIs - [x] Resolve spurious "reloading because it has changed" events (to repro run load_gltf with `processed_dev()`) - [x] load_dependency hot reloading currently only works for processed assets. If processing is disabled, load_dependency changes are not hot reloaded. - [x] Replace AssetInfo dependency load/fail counters with `loading_dependencies: HashSet<UntypedAssetId>` to prevent reloads from (potentially) breaking counters. Storing this will also enable "dependency reloaded" events (see [Next Steps](#next-steps)) - [x] Re-add filesystem watcher cargo feature gate (currently it is not optional) - [ ] Migration Guide - [ ] Changelog ## Followup TODO - [ ] Replace "eager unchanged processed asset loading" behavior with "don't returned unchanged processed asset until dependencies have been checked". - [ ] Add true `Ignore` AssetAction that does not copy the asset to the imported_assets folder. - [ ] Finish "live asset unloading" (ex: free up CPU asset memory after uploading an image to the GPU), rethink RenderAssets, and port renderer features. The `Assets` collection uses `Option<T>` for asset storage to support its removal. (1) the Option might not actually be necessary ... might be able to just remove from the collection entirely (2) need to finalize removal apis - [ ] Try replacing the "channel based" asset id recycling with something a bit more efficient (ex: we might be able to use raw atomic ints with some cleverness) - [ ] Consider adding UUIDs to processed assets (scoped just to helping identify moved assets ... not exposed to load queries ... see [Next Steps](#next-steps)) - [ ] Store "last modified" source asset and meta timestamps in processed meta files to enable skipping expensive hashing when the file wasn't changed - [ ] Fix "slow loop" handle drop fix - [ ] Migrate to TypeName - [x] Handle "loader preregistration". See #9429 ## Next Steps * **Configurable per-type defaults for AssetMeta**: It should be possible to add configuration like "all png image meta should default to using nearest sampling" (currently this hard-coded per-loader/processor Settings::default() impls). Also see the "Folder Meta" bullet point. * **Avoid Reprocessing on Asset Renames / Moves**: See the "canonical asset ids" discussion in [Open Questions](#open-questions) and the relevant bullet point in [Draft TODO](#draft-todo). Even without canonical ids, folder renames could avoid reprocessing in some cases. * **Multiple Asset Sources**: Expand AssetPath to support "asset source names" and support multiple AssetReaders in the asset server (ex: `webserver://some_path/image.png` backed by an Http webserver AssetReader). The "default" asset reader would use normal `some_path/image.png` paths. Ideally this works in combination with multiple AssetWatchers for hot-reloading * **Stable Type Names**: this pr removes the TypeUuid requirement from assets in favor of `std::any::type_name`. This makes defining assets easier (no need to generate a new uuid / use weird proc macro syntax). It also makes reading meta files easier (because things have "friendly names"). We also use type names for components in scene files. If they are good enough for components, they are good enough for assets. And consistency across Bevy pillars is desirable. However, `std::any::type_name` is not guaranteed to be stable (although in practice it is). We've developed a [stable type path](https://github.com/bevyengine/bevy/pull/7184) to resolve this, which should be adopted when it is ready. * **Command Line Interface**: It should be possible to run the asset processor in a separate process from the command line. This will also require building a network-server-backed AssetReader to communicate between the app and the processor. We've been planning to build a "bevy cli" for awhile. This seems like a good excuse to build it. * **Asset Packing**: This is largely an additive feature, so it made sense to me to punt this until we've laid the foundations in this PR. * **Per-Platform Processed Assets**: It should be possible to generate assets for multiple platforms by supporting multiple "processor profiles" per asset (ex: compress with format X on PC and Y on iOS). I think there should probably be arbitrary "profiles" (which can be separate from actual platforms), which are then assigned to a given platform when generating the final asset distribution for that platform. Ex: maybe devs want a "Mobile" profile that is shared between iOS and Android. Or a "LowEnd" profile shared between web and mobile. * **Versioning and Migrations**: Assets, Loaders, Savers, and Processors need to have versions to determine if their schema is valid. If an asset / loader version is incompatible with the current version expected at runtime, the processor should be able to migrate them. I think we should try using Bevy Reflect for this, as it would allow us to load the old version as a dynamic Reflect type without actually having the old Rust type. It would also allow us to define "patches" to migrate between versions (Bevy Reflect devs are currently working on patching). The `.meta` file already has its own format version. Migrating that to new versions should also be possible. * **Real Copy-on-write AssetPaths**: Rust's actual Cow (clone-on-write type) currently used by AssetPath can still result in String clones that aren't actually necessary (cloning an Owned Cow clones the contents). Bevy's asset system requires cloning AssetPaths in a number of places, which result in actual clones of the internal Strings. This is not efficient. AssetPath internals should be reworked to exhibit truer cow-like-behavior that reduces String clones to the absolute minimum. * **Consider processor-less processing**: In theory the AssetServer could run processors "inline" even if the background AssetProcessor is disabled. If we decide this is actually desirable, we could add this. But I don't think its a priority in the short or medium term. * **Pre-emptive dependency loading**: We could encode dependencies in processed meta files, which could then be used by the Asset Server to kick of dependency loads as early as possible (prior to starting the actual asset load). Is this desirable? How much time would this save in practice? * **Optimize Processor With UntypedAssetIds**: The processor exclusively uses AssetPath to identify assets currently. It might be possible to swap these out for UntypedAssetIds in some places, which are smaller / cheaper to hash and compare. * **One to Many Asset Processing**: An asset source file that produces many assets currently must be processed into a single "processed" asset source. If labeled assets can be written separately they can each have their own configured savers _and_ they could be loaded more granularly. Definitely worth exploring! * **Automatically Track "Runtime-only" Asset Dependencies**: Right now, tracking "created at runtime" asset dependencies requires adding them via `asset_server.load_asset(StandardMaterial::default())`. I think with some cleverness we could also do this for `materials.add(StandardMaterial::default())`, making tracking work "everywhere". There are challenges here relating to change detection / ensuring the server is made aware of dependency changes. This could be expensive in some cases. * **"Dependency Changed" events**: Some assets have runtime artifacts that need to be re-generated when one of their dependencies change (ex: regenerate a material's bind group when a Texture needs to change). We are generating the dependency graph so we can definitely produce these events. Buuuuut generating these events will have a cost / they could be high frequency for some assets, so we might want this to be opt-in for specific cases. * **Investigate Storing More Information In Handles**: Handles can now store arbitrary information, which makes it cheaper and easier to access. How much should we move into them? Canonical asset load states (via atomics)? (`handle.is_loaded()` would be very cool). Should we store the entire asset and remove the `Assets<T>` collection? (`Arc<RwLock<Option<Image>>>`?) * **Support processing and loading files without extensions**: This is a pretty arbitrary restriction and could be supported with very minimal changes. * **Folder Meta**: It would be nice if we could define per folder processor configuration defaults (likely in a `.meta` or `.folder_meta` file). Things like "default to linear filtering for all Images in this folder". * **Replace async_broadcast with event-listener?** This might be approximately drop-in for some uses and it feels more light weight * **Support Running the AssetProcessor on the Web**: Most of the hard work is done here, but there are some easy straggling TODOs (make the transaction log an interface instead of a direct file writer so we can write a web storage backend, implement an AssetReader/AssetWriter that reads/writes to something like LocalStorage). * **Consider identifying and preventing circular dependencies**: This is especially important for "processor dependencies", as processing will silently never finish in these cases. * **Built-in/Inlined Asset Hot Reloading**: This PR regresses "built-in/inlined" asset hot reloading (previously provided by the DebugAssetServer). I'm intentionally punting this because I think it can be cleanly implemented with "multiple asset sources" by registering a "debug asset source" (ex: `debug://bevy_pbr/src/render/pbr.wgsl` asset paths) in combination with an AssetWatcher for that asset source and support for "manually loading pats with asset bytes instead of AssetReaders". The old DebugAssetServer was quite nasty and I'd love to avoid that hackery going forward. * **Investigate ways to remove double-parsing meta files**: Parsing meta files currently involves parsing once with "minimal" versions of the meta file to extract the type name of the loader/processor config, then parsing again to parse the "full" meta. This is suboptimal. We should be able to define custom deserializers that (1) assume the loader/processor type name comes first (2) dynamically looks up the loader/processor registrations to deserialize settings in-line (similar to components in the bevy scene format). Another alternative: deserialize as dynamic Reflect objects and then convert. * **More runtime loading configuration**: Support using the Handle type as a hint to select an asset loader (instead of relying on AssetPath extensions) * **More high level Processor trait implementations**: For example, it might be worth adding support for arbitrary chains of "asset transforms" that modify an in-memory asset representation between loading and saving. (ex: load a Mesh, run a `subdivide_mesh` transform, followed by a `flip_normals` transform, then save the mesh to an efficient compressed format). * **Bevy Scene Handle Deserialization**: (see the relevant [Draft TODO item](#draft-todo) for context) * **Explore High Level Load Interfaces**: See [this discussion](#discuss-on_loaded-high-level-interface) for one prototype. * **Asset Streaming**: It would be great if we could stream Assets (ex: stream a long video file piece by piece) * **ID Exchanging**: In this PR Asset Handles/AssetIds are bigger than they need to be because they have a Uuid enum variant. If we implement an "id exchanging" system that trades Uuids for "efficient runtime ids", we can cut down on the size of AssetIds, making them more efficient. This has some open design questions, such as how to spawn entities with "default" handle values (as these wouldn't have access to the exchange api in the current system). * **Asset Path Fixup Tooling**: Assets that inline asset paths inside them will break when an asset moves. The asset system provides the functionality to detect when paths break. We should build a framework that enables formats to define "path migrations". This is especially important for scene files. For editor-generated files, we should also consider using UUIDs (see other bullet point) to avoid the need to migrate in these cases. --------- Co-authored-by: BeastLe9enD <beastle9end@outlook.de> Co-authored-by: Mike <mike.hsu@gmail.com> Co-authored-by: Nicola Papale <nicopap@users.noreply.github.com>
2023-09-07 02:07:27 +00:00
[package.metadata.example.custom_asset_reader]
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
name = "Custom Asset IO"
Bevy Asset V2 (#8624) # Bevy Asset V2 Proposal ## Why Does Bevy Need A New Asset System? Asset pipelines are a central part of the gamedev process. Bevy's current asset system is missing a number of features that make it non-viable for many classes of gamedev. After plenty of discussions and [a long community feedback period](https://github.com/bevyengine/bevy/discussions/3972), we've identified a number missing features: * **Asset Preprocessing**: it should be possible to "preprocess" / "compile" / "crunch" assets at "development time" rather than when the game starts up. This enables offloading expensive work from deployed apps, faster asset loading, less runtime memory usage, etc. * **Per-Asset Loader Settings**: Individual assets cannot define their own loaders that override the defaults. Additionally, they cannot provide per-asset settings to their loaders. This is a huge limitation, as many asset types don't provide all information necessary for Bevy _inside_ the asset. For example, a raw PNG image says nothing about how it should be sampled (ex: linear vs nearest). * **Asset `.meta` files**: assets should have configuration files stored adjacent to the asset in question, which allows the user to configure asset-type-specific settings. These settings should be accessible during the pre-processing phase. Modifying a `.meta` file should trigger a re-processing / re-load of the asset. It should be possible to configure asset loaders from the meta file. * **Processed Asset Hot Reloading**: Changes to processed assets (or their dependencies) should result in re-processing them and re-loading the results in live Bevy Apps. * **Asset Dependency Tracking**: The current bevy_asset has no good way to wait for asset dependencies to load. It punts this as an exercise for consumers of the loader apis, which is unreasonable and error prone. There should be easy, ergonomic ways to wait for assets to load and block some logic on an asset's entire dependency tree loading. * **Runtime Asset Loading**: it should be (optionally) possible to load arbitrary assets dynamically at runtime. This necessitates being able to deploy and run the asset server alongside Bevy Apps on _all platforms_. For example, we should be able to invoke the shader compiler at runtime, stream scenes from sources like the internet, etc. To keep deployed binaries (and startup times) small, the runtime asset server configuration should be configurable with different settings compared to the "pre processor asset server". * **Multiple Backends**: It should be possible to load assets from arbitrary sources (filesystems, the internet, remote asset serves, etc). * **Asset Packing**: It should be possible to deploy assets in compressed "packs", which makes it easier and more efficient to distribute assets with Bevy Apps. * **Asset Handoff**: It should be possible to hold a "live" asset handle, which correlates to runtime data, without actually holding the asset in memory. Ex: it must be possible to hold a reference to a GPU mesh generated from a "mesh asset" without keeping the mesh data in CPU memory * **Per-Platform Processed Assets**: Different platforms and app distributions have different capabilities and requirements. Some platforms need lower asset resolutions or different asset formats to operate within the hardware constraints of the platform. It should be possible to define per-platform asset processing profiles. And it should be possible to deploy only the assets required for a given platform. These features have architectural implications that are significant enough to require a full rewrite. The current Bevy Asset implementation got us this far, but it can take us no farther. This PR defines a brand new asset system that implements most of these features, while laying the foundations for the remaining features to be built. ## Bevy Asset V2 Here is a quick overview of the features introduced in this PR. * **Asset Preprocessing**: Preprocess assets at development time into more efficient (and configurable) representations * **Dependency Aware**: Dependencies required to process an asset are tracked. If an asset's processed dependency changes, it will be reprocessed * **Hot Reprocessing/Reloading**: detect changes to asset source files, reprocess them if they have changed, and then hot-reload them in Bevy Apps. * **Only Process Changes**: Assets are only re-processed when their source file (or meta file) has changed. This uses hashing and timestamps to avoid processing assets that haven't changed. * **Transactional and Reliable**: Uses write-ahead logging (a technique commonly used by databases) to recover from crashes / forced-exits. Whenever possible it avoids full-reprocessing / only uncompleted transactions will be reprocessed. When the processor is running in parallel with a Bevy App, processor asset writes block Bevy App asset reads. Reading metadata + asset bytes is guaranteed to be transactional / correctly paired. * **Portable / Run anywhere / Database-free**: The processor does not rely on an in-memory database (although it uses some database techniques for reliability). This is important because pretty much all in-memory databases have unsupported platforms or build complications. * **Configure Processor Defaults Per File Type**: You can say "use this processor for all files of this type". * **Custom Processors**: The `Processor` trait is flexible and unopinionated. It can be implemented by downstream plugins. * **LoadAndSave Processors**: Most asset processing scenarios can be expressed as "run AssetLoader A, save the results using AssetSaver X, and then load the result using AssetLoader B". For example, load this png image using `PngImageLoader`, which produces an `Image` asset and then save it using `CompressedImageSaver` (which also produces an `Image` asset, but in a compressed format), which takes an `Image` asset as input. This means if you have an `AssetLoader` for an asset, you are already half way there! It also means that you can share AssetSavers across multiple loaders. Because `CompressedImageSaver` accepts Bevy's generic Image asset as input, it means you can also use it with some future `JpegImageLoader`. * **Loader and Saver Settings**: Asset Loaders and Savers can now define their own settings types, which are passed in as input when an asset is loaded / saved. Each asset can define its own settings. * **Asset `.meta` files**: configure asset loaders, their settings, enable/disable processing, and configure processor settings * **Runtime Asset Dependency Tracking** Runtime asset dependencies (ex: if an asset contains a `Handle<Image>`) are tracked by the asset server. An event is emitted when an asset and all of its dependencies have been loaded * **Unprocessed Asset Loading**: Assets do not require preprocessing. They can be loaded directly. A processed asset is just a "normal" asset with some extra metadata. Asset Loaders don't need to know or care about whether or not an asset was processed. * **Async Asset IO**: Asset readers/writers use async non-blocking interfaces. Note that because Rust doesn't yet support async traits, there is a bit of manual Boxing / Future boilerplate. This will hopefully be removed in the near future when Rust gets async traits. * **Pluggable Asset Readers and Writers**: Arbitrary asset source readers/writers are supported, both by the processor and the asset server. * **Better Asset Handles** * **Single Arc Tree**: Asset Handles now use a single arc tree that represents the lifetime of the asset. This makes their implementation simpler, more efficient, and allows us to cheaply attach metadata to handles. Ex: the AssetPath of a handle is now directly accessible on the handle itself! * **Const Typed Handles**: typed handles can be constructed in a const context. No more weird "const untyped converted to typed at runtime" patterns! * **Handles and Ids are Smaller / Faster To Hash / Compare**: Typed `Handle<T>` is now much smaller in memory and `AssetId<T>` is even smaller. * **Weak Handle Usage Reduction**: In general Handles are now considered to be "strong". Bevy features that previously used "weak `Handle<T>`" have been ported to `AssetId<T>`, which makes it statically clear that the features do not hold strong handles (while retaining strong type information). Currently Handle::Weak still exists, but it is very possible that we can remove that entirely. * **Efficient / Dense Asset Ids**: Assets now have efficient dense runtime asset ids, which means we can avoid expensive hash lookups. Assets are stored in Vecs instead of HashMaps. There are now typed and untyped ids, which means we no longer need to store dynamic type information in the ID for typed handles. "AssetPathId" (which was a nightmare from a performance and correctness standpoint) has been entirely removed in favor of dense ids (which are retrieved for a path on load) * **Direct Asset Loading, with Dependency Tracking**: Assets that are defined at runtime can still have their dependencies tracked by the Asset Server (ex: if you create a material at runtime, you can still wait for its textures to load). This is accomplished via the (currently optional) "asset dependency visitor" trait. This system can also be used to define a set of assets to load, then wait for those assets to load. * **Async folder loading**: Folder loading also uses this system and immediately returns a handle to the LoadedFolder asset, which means folder loading no longer blocks on directory traversals. * **Improved Loader Interface**: Loaders now have a specific "top level asset type", which makes returning the top-level asset simpler and statically typed. * **Basic Image Settings and Processing**: Image assets can now be processed into the gpu-friendly Basic Universal format. The ImageLoader now has a setting to define what format the image should be loaded as. Note that this is just a minimal MVP ... plenty of additional work to do here. To demo this, enable the `basis-universal` feature and turn on asset processing. * **Simpler Audio Play / AudioSink API**: Asset handle providers are cloneable, which means the Audio resource can mint its own handles. This means you can now do `let sink_handle = audio.play(music)` instead of `let sink_handle = audio_sinks.get_handle(audio.play(music))`. Note that this might still be replaced by https://github.com/bevyengine/bevy/pull/8424. **Removed Handle Casting From Engine Features**: Ex: FontAtlases no longer use casting between handle types ## Using The New Asset System ### Normal Unprocessed Asset Loading By default the `AssetPlugin` does not use processing. It behaves pretty much the same way as the old system. If you are defining a custom asset, first derive `Asset`: ```rust #[derive(Asset)] struct Thing { value: String, } ``` Initialize the asset: ```rust app.init_asset:<Thing>() ``` Implement a new `AssetLoader` for it: ```rust #[derive(Default)] struct ThingLoader; #[derive(Serialize, Deserialize, Default)] pub struct ThingSettings { some_setting: bool, } impl AssetLoader for ThingLoader { type Asset = Thing; type Settings = ThingSettings; fn load<'a>( &'a self, reader: &'a mut Reader, settings: &'a ThingSettings, load_context: &'a mut LoadContext, ) -> BoxedFuture<'a, Result<Thing, anyhow::Error>> { Box::pin(async move { let mut bytes = Vec::new(); reader.read_to_end(&mut bytes).await?; // convert bytes to value somehow Ok(Thing { value }) }) } fn extensions(&self) -> &[&str] { &["thing"] } } ``` Note that this interface will get much cleaner once Rust gets support for async traits. `Reader` is an async futures_io::AsyncRead. You can stream bytes as they come in or read them all into a `Vec<u8>`, depending on the context. You can use `let handle = load_context.load(path)` to kick off a dependency load, retrieve a handle, and register the dependency for the asset. Then just register the loader in your Bevy app: ```rust app.init_asset_loader::<ThingLoader>() ``` Now just add your `Thing` asset files into the `assets` folder and load them like this: ```rust fn system(asset_server: Res<AssetServer>) { let handle = Handle<Thing> = asset_server.load("cool.thing"); } ``` You can check load states directly via the asset server: ```rust if asset_server.load_state(&handle) == LoadState::Loaded { } ``` You can also listen for events: ```rust fn system(mut events: EventReader<AssetEvent<Thing>>, handle: Res<SomeThingHandle>) { for event in events.iter() { if event.is_loaded_with_dependencies(&handle) { } } } ``` Note the new `AssetEvent::LoadedWithDependencies`, which only fires when the asset is loaded _and_ all dependencies (and their dependencies) have loaded. Unlike the old asset system, for a given asset path all `Handle<T>` values point to the same underlying Arc. This means Handles can cheaply hold more asset information, such as the AssetPath: ```rust // prints the AssetPath of the handle info!("{:?}", handle.path()) ``` ### Processed Assets Asset processing can be enabled via the `AssetPlugin`. When developing Bevy Apps with processed assets, do this: ```rust app.add_plugins(DefaultPlugins.set(AssetPlugin::processed_dev())) ``` This runs the `AssetProcessor` in the background with hot-reloading. It reads assets from the `assets` folder, processes them, and writes them to the `.imported_assets` folder. Asset loads in the Bevy App will wait for a processed version of the asset to become available. If an asset in the `assets` folder changes, it will be reprocessed and hot-reloaded in the Bevy App. When deploying processed Bevy apps, do this: ```rust app.add_plugins(DefaultPlugins.set(AssetPlugin::processed())) ``` This does not run the `AssetProcessor` in the background. It behaves like `AssetPlugin::unprocessed()`, but reads assets from `.imported_assets`. When the `AssetProcessor` is running, it will populate sibling `.meta` files for assets in the `assets` folder. Meta files for assets that do not have a processor configured look like this: ```rust ( meta_format_version: "1.0", asset: Load( loader: "bevy_render::texture::image_loader::ImageLoader", settings: ( format: FromExtension, ), ), ) ``` This is metadata for an image asset. For example, if you have `assets/my_sprite.png`, this could be the metadata stored at `assets/my_sprite.png.meta`. Meta files are totally optional. If no metadata exists, the default settings will be used. In short, this file says "load this asset with the ImageLoader and use the file extension to determine the image type". This type of meta file is supported in all AssetPlugin modes. If in `Unprocessed` mode, the asset (with the meta settings) will be loaded directly. If in `ProcessedDev` mode, the asset file will be copied directly to the `.imported_assets` folder. The meta will also be copied directly to the `.imported_assets` folder, but with one addition: ```rust ( meta_format_version: "1.0", processed_info: Some(( hash: 12415480888597742505, full_hash: 14344495437905856884, process_dependencies: [], )), asset: Load( loader: "bevy_render::texture::image_loader::ImageLoader", settings: ( format: FromExtension, ), ), ) ``` `processed_info` contains `hash` (a direct hash of the asset and meta bytes), `full_hash` (a hash of `hash` and the hashes of all `process_dependencies`), and `process_dependencies` (the `path` and `full_hash` of every process_dependency). A "process dependency" is an asset dependency that is _directly_ used when processing the asset. Images do not have process dependencies, so this is empty. When the processor is enabled, you can use the `Process` metadata config: ```rust ( meta_format_version: "1.0", asset: Process( processor: "bevy_asset::processor::process::LoadAndSave<bevy_render::texture::image_loader::ImageLoader, bevy_render::texture::compressed_image_saver::CompressedImageSaver>", settings: ( loader_settings: ( format: FromExtension, ), saver_settings: ( generate_mipmaps: true, ), ), ), ) ``` This configures the asset to use the `LoadAndSave` processor, which runs an AssetLoader and feeds the result into an AssetSaver (which saves the given Asset and defines a loader to load it with). (for terseness LoadAndSave will likely get a shorter/friendlier type name when [Stable Type Paths](#7184) lands). `LoadAndSave` is likely to be the most common processor type, but arbitrary processors are supported. `CompressedImageSaver` saves an `Image` in the Basis Universal format and configures the ImageLoader to load it as basis universal. The `AssetProcessor` will read this meta, run it through the LoadAndSave processor, and write the basis-universal version of the image to `.imported_assets`. The final metadata will look like this: ```rust ( meta_format_version: "1.0", processed_info: Some(( hash: 905599590923828066, full_hash: 9948823010183819117, process_dependencies: [], )), asset: Load( loader: "bevy_render::texture::image_loader::ImageLoader", settings: ( format: Format(Basis), ), ), ) ``` To try basis-universal processing out in Bevy examples, (for example `sprite.rs`), change `add_plugins(DefaultPlugins)` to `add_plugins(DefaultPlugins.set(AssetPlugin::processed_dev()))` and run with the `basis-universal` feature enabled: `cargo run --features=basis-universal --example sprite`. To create a custom processor, there are two main paths: 1. Use the `LoadAndSave` processor with an existing `AssetLoader`. Implement the `AssetSaver` trait, register the processor using `asset_processor.register_processor::<LoadAndSave<ImageLoader, CompressedImageSaver>>(image_saver.into())`. 2. Implement the `Process` trait directly and register it using: `asset_processor.register_processor(thing_processor)`. You can configure default processors for file extensions like this: ```rust asset_processor.set_default_processor::<ThingProcessor>("thing") ``` There is one more metadata type to be aware of: ```rust ( meta_format_version: "1.0", asset: Ignore, ) ``` This will ignore the asset during processing / prevent it from being written to `.imported_assets`. The AssetProcessor stores a transaction log at `.imported_assets/log` and uses it to gracefully recover from unexpected stops. This means you can force-quit the processor (and Bevy Apps running the processor in parallel) at arbitrary times! `.imported_assets` is "local state". It should _not_ be checked into source control. It should also be considered "read only". In practice, you _can_ modify processed assets and processed metadata if you really need to test something. But those modifications will not be represented in the hashes of the assets, so the processed state will be "out of sync" with the source assets. The processor _will not_ fix this for you. Either revert the change after you have tested it, or delete the processed files so they can be re-populated. ## Open Questions There are a number of open questions to be discussed. We should decide if they need to be addressed in this PR and if so, how we will address them: ### Implied Dependencies vs Dependency Enumeration There are currently two ways to populate asset dependencies: * **Implied via AssetLoaders**: if an AssetLoader loads an asset (and retrieves a handle), a dependency is added to the list. * **Explicit via the optional Asset::visit_dependencies**: if `server.load_asset(my_asset)` is called, it will call `my_asset.visit_dependencies`, which will grab dependencies that have been manually defined for the asset via the Asset trait impl (which can be derived). This means that defining explicit dependencies is optional for "loaded assets". And the list of dependencies is always accurate because loaders can only produce Handles if they register dependencies. If an asset was loaded with an AssetLoader, it only uses the implied dependencies. If an asset was created at runtime and added with `asset_server.load_asset(MyAsset)`, it will use `Asset::visit_dependencies`. However this can create a behavior mismatch between loaded assets and equivalent "created at runtime" assets if `Assets::visit_dependencies` doesn't exactly match the dependencies produced by the AssetLoader. This behavior mismatch can be resolved by completely removing "implied loader dependencies" and requiring `Asset::visit_dependencies` to supply dependency data. But this creates two problems: * It makes defining loaded assets harder and more error prone: Devs must remember to manually annotate asset dependencies with `#[dependency]` when deriving `Asset`. For more complicated assets (such as scenes), the derive likely wouldn't be sufficient and a manual `visit_dependencies` impl would be required. * Removes the ability to immediately kick off dependency loads: When AssetLoaders retrieve a Handle, they also immediately kick off an asset load for the handle, which means it can start loading in parallel _before_ the asset finishes loading. For large assets, this could be significant. (although this could be mitigated for processed assets if we store dependencies in the processed meta file and load them ahead of time) ### Eager ProcessorDev Asset Loading I made a controversial call in the interest of fast startup times ("time to first pixel") for the "processor dev mode configuration". When initializing the AssetProcessor, current processed versions of unchanged assets are yielded immediately, even if their dependencies haven't been checked yet for reprocessing. This means that non-current-state-of-filesystem-but-previously-valid assets might be returned to the App first, then hot-reloaded if/when their dependencies change and the asset is reprocessed. Is this behavior desirable? There is largely one alternative: do not yield an asset from the processor to the app until all of its dependencies have been checked for changes. In some common cases (load dependency has not changed since last run) this will increase startup time. The main question is "by how much" and is that slower startup time worth it in the interest of only yielding assets that are true to the current state of the filesystem. Should this be configurable? I'm starting to think we should only yield an asset after its (historical) dependencies have been checked for changes + processed as necessary, but I'm curious what you all think. ### Paths Are Currently The Only Canonical ID / Do We Want Asset UUIDs? In this implementation AssetPaths are the only canonical asset identifier (just like the previous Bevy Asset system and Godot). Moving assets will result in re-scans (and currently reprocessing, although reprocessing can easily be avoided with some changes). Asset renames/moves will break code and assets that rely on specific paths, unless those paths are fixed up. Do we want / need "stable asset uuids"? Introducing them is very possible: 1. Generate a UUID and include it in .meta files 2. Support UUID in AssetPath 3. Generate "asset indices" which are loaded on startup and map UUIDs to paths. 4 (maybe). Consider only supporting UUIDs for processed assets so we can generate quick-to-load indices instead of scanning meta files. The main "pro" is that assets referencing UUIDs don't need to be migrated when a path changes. The main "con" is that UUIDs cannot be "lazily resolved" like paths. They need a full view of all assets to answer the question "does this UUID exist". Which means UUIDs require the AssetProcessor to fully finish startup scans before saying an asset doesnt exist. And they essentially require asset pre-processing to use in apps, because scanning all asset metadata files at runtime to resolve a UUID is not viable for medium-to-large apps. It really requires a pre-generated UUID index, which must be loaded before querying for assets. I personally think this should be investigated in a separate PR. Paths aren't going anywhere ... _everyone_ uses filesystems (and filesystem-like apis) to manage their asset source files. I consider them permanent canonical asset information. Additionally, they behave well for both processed and unprocessed asset modes. Given that Bevy is supporting both, this feels like the right canonical ID to start with. UUIDS (and maybe even other indexed-identifier types) can be added later as necessary. ### Folder / File Naming Conventions All asset processing config currently lives in the `.imported_assets` folder. The processor transaction log is in `.imported_assets/log`. Processed assets are added to `.imported_assets/Default`, which will make migrating to processed asset profiles (ex: a `.imported_assets/Mobile` profile) a non-breaking change. It also allows us to create top-level files like `.imported_assets/log` without it being interpreted as an asset. Meta files currently have a `.meta` suffix. Do we like these names and conventions? ### Should the `AssetPlugin::processed_dev` configuration enable `watch_for_changes` automatically? Currently it does (which I think makes sense), but it does make it the only configuration that enables watch_for_changes by default. ### Discuss on_loaded High Level Interface: This PR includes a very rough "proof of concept" `on_loaded` system adapter that uses the `LoadedWithDependencies` event in combination with `asset_server.load_asset` dependency tracking to support this pattern ```rust fn main() { App::new() .init_asset::<MyAssets>() .add_systems(Update, on_loaded(create_array_texture)) .run(); } #[derive(Asset, Clone)] struct MyAssets { #[dependency] picture_of_my_cat: Handle<Image>, #[dependency] picture_of_my_other_cat: Handle<Image>, } impl FromWorld for ArrayTexture { fn from_world(world: &mut World) -> Self { picture_of_my_cat: server.load("meow.png"), picture_of_my_other_cat: server.load("meeeeeeeow.png"), } } fn spawn_cat(In(my_assets): In<MyAssets>, mut commands: Commands) { commands.spawn(SpriteBundle { texture: my_assets.picture_of_my_cat.clone(), ..default() }); commands.spawn(SpriteBundle { texture: my_assets.picture_of_my_other_cat.clone(), ..default() }); } ``` The implementation is _very_ rough. And it is currently unsafe because `bevy_ecs` doesn't expose some internals to do this safely from inside `bevy_asset`. There are plenty of unanswered questions like: * "do we add a Loadable" derive? (effectively automate the FromWorld implementation above) * Should `MyAssets` even be an Asset? (largely implemented this way because it elegantly builds on `server.load_asset(MyAsset { .. })` dependency tracking). We should think hard about what our ideal API looks like (and if this is a pattern we want to support). Not necessarily something we need to solve in this PR. The current `on_loaded` impl should probably be removed from this PR before merging. ## Clarifying Questions ### What about Assets as Entities? This Bevy Asset V2 proposal implementation initially stored Assets as ECS Entities. Instead of `AssetId<T>` + the `Assets<T>` resource it used `Entity` as the asset id and Asset values were just ECS components. There are plenty of compelling reasons to do this: 1. Easier to inline assets in Bevy Scenes (as they are "just" normal entities + components) 2. More flexible queries: use the power of the ECS to filter assets (ex: `Query<Mesh, With<Tree>>`). 3. Extensible. Users can add arbitrary component data to assets. 4. Things like "component visualization tools" work out of the box to visualize asset data. However Assets as Entities has a ton of caveats right now: * We need to be able to allocate entity ids without a direct World reference (aka rework id allocator in Entities ... i worked around this in my prototypes by just pre allocating big chunks of entities) * We want asset change events in addition to ECS change tracking ... how do we populate them when mutations can come from anywhere? Do we use Changed queries? This would require iterating over the change data for all assets every frame. Is this acceptable or should we implement a new "event based" component change detection option? * Reconciling manually created assets with asset-system managed assets has some nuance (ex: are they "loaded" / do they also have that component metadata?) * "how do we handle "static" / default entity handles" (ties in to the Entity Indices discussion: https://github.com/bevyengine/bevy/discussions/8319). This is necessary for things like "built in" assets and default handles in things like SpriteBundle. * Storing asset information as a component makes it easy to "invalidate" asset state by removing the component (or forcing modifications). Ideally we have ways to lock this down (some combination of Rust type privacy and ECS validation) In practice, how we store and identify assets is a reasonably superficial change (porting off of Assets as Entities and implementing dedicated storage + ids took less than a day). So once we sort out the remaining challenges the flip should be straightforward. Additionally, I do still have "Assets as Entities" in my commit history, so we can reuse that work. I personally think "assets as entities" is a good endgame, but it also doesn't provide _significant_ value at the moment and it certainly isn't ready yet with the current state of things. ### Why not Distill? [Distill](https://github.com/amethyst/distill) is a high quality fully featured asset system built in Rust. It is very natural to ask "why not just use Distill?". It is also worth calling out that for awhile, [we planned on adopting Distill / I signed off on it](https://github.com/bevyengine/bevy/issues/708). However I think Bevy has a number of constraints that make Distill adoption suboptimal: * **Architectural Simplicity:** * Distill's processor requires an in-memory database (lmdb) and RPC networked API (using Cap'n Proto). Each of these introduces API complexity that increases maintenance burden and "code grokability". Ignoring tests, documentation, and examples, Distill has 24,237 lines of Rust code (including generated code for RPC + database interactions). If you ignore generated code, it has 11,499 lines. * Bevy builds the AssetProcessor and AssetServer using pluggable AssetReader/AssetWriter Rust traits with simple io interfaces. They do not necessitate databases or RPC interfaces (although Readers/Writers could use them if that is desired). Bevy Asset V2 (at the time of writing this PR) is 5,384 lines of Rust code (ignoring tests, documentation, and examples). Grain of salt: Distill does have more features currently (ex: Asset Packing, GUIDS, remote-out-of-process asset processor). I do plan to implement these features in Bevy Asset V2 and I personally highly doubt they will meaningfully close the 6115 lines-of-code gap. * This complexity gap (which while illustrated by lines of code, is much bigger than just that) is noteworthy to me. Bevy should be hackable and there are pillars of Distill that are very hard to understand and extend. This is a matter of opinion (and Bevy Asset V2 also has complicated areas), but I think Bevy Asset V2 is much more approachable for the average developer. * Necessary disclaimer: counting lines of code is an extremely rough complexity metric. Read the code and form your own opinions. * **Optional Asset Processing:** Not all Bevy Apps (or Bevy App developers) need / want asset preprocessing. Processing increases the complexity of the development environment by introducing things like meta files, imported asset storage, running processors in the background, waiting for processing to finish, etc. Distill _requires_ preprocessing to work. With Bevy Asset V2 processing is fully opt-in. The AssetServer isn't directly aware of asset processors at all. AssetLoaders only care about converting bytes to runtime Assets ... they don't know or care if the bytes were pre-processed or not. Processing is "elegantly" (forgive my self-congratulatory phrasing) layered on top and builds on the existing Asset system primitives. * **Direct Filesystem Access to Processed Asset State:** Distill stores processed assets in a database. This makes debugging / inspecting the processed outputs harder (either requires special tooling to query the database or they need to be "deployed" to be inspected). Bevy Asset V2, on the other hand, stores processed assets in the filesystem (by default ... this is configurable). This makes interacting with the processed state more natural. Note that both Godot and Unity's new asset system store processed assets in the filesystem. * **Portability**: Because Distill's processor uses lmdb and RPC networking, it cannot be run on certain platforms (ex: lmdb is a non-rust dependency that cannot run on the web, some platforms don't support running network servers). Bevy should be able to process assets everywhere (ex: run the Bevy Editor on the web, compile + process shaders on mobile, etc). Distill does partially mitigate this problem by supporting "streaming" assets via the RPC protocol, but this is not a full solve from my perspective. And Bevy Asset V2 can (in theory) also stream assets (without requiring RPC, although this isn't implemented yet) Note that I _do_ still think Distill would be a solid asset system for Bevy. But I think the approach in this PR is a better solve for Bevy's specific "asset system requirements". ### Doesn't async-fs just shim requests to "sync" `std::fs`? What is the point? "True async file io" has limited / spotty platform support. async-fs (and the rust async ecosystem generally ... ex Tokio) currently use async wrappers over std::fs that offload blocking requests to separate threads. This may feel unsatisfying, but it _does_ still provide value because it prevents our task pools from blocking on file system operations (which would prevent progress when there are many tasks to do, but all threads in a pool are currently blocking on file system ops). Additionally, using async APIs for our AssetReaders and AssetWriters also provides value because we can later add support for "true async file io" for platforms that support it. _And_ we can implement other "true async io" asset backends (such as networked asset io). ## Draft TODO - [x] Fill in missing filesystem event APIs: file removed event (which is expressed as dangling RenameFrom events in some cases), file/folder renamed event - [x] Assets without loaders are not moved to the processed folder. This breaks things like referenced `.bin` files for GLTFs. This should be configurable per-non-asset-type. - [x] Initial implementation of Reflect and FromReflect for Handle. The "deserialization" parity bar is low here as this only worked with static UUIDs in the old impl ... this is a non-trivial problem. Either we add a Handle::AssetPath variant that gets "upgraded" to a strong handle on scene load or we use a separate AssetRef type for Bevy scenes (which is converted to a runtime Handle on load). This deserves its own discussion in a different pr. - [x] Populate read_asset_bytes hash when run by the processor (a bit of a special case .. when run by the processor the processed meta will contain the hash so we don't need to compute it on the spot, but we don't want/need to read the meta when run by the main AssetServer) - [x] Delay hot reloading: currently filesystem events are handled immediately, which creates timing issues in some cases. For example hot reloading images can sometimes break because the image isn't finished writing. We should add a delay, likely similar to the [implementation in this PR](https://github.com/bevyengine/bevy/pull/8503). - [x] Port old platform-specific AssetIo implementations to the new AssetReader interface (currently missing Android and web) - [x] Resolve on_loaded unsafety (either by removing the API entirely or removing the unsafe) - [x] Runtime loader setting overrides - [x] Remove remaining unwraps that should be error-handled. There are number of TODOs here - [x] Pretty AssetPath Display impl - [x] Document more APIs - [x] Resolve spurious "reloading because it has changed" events (to repro run load_gltf with `processed_dev()`) - [x] load_dependency hot reloading currently only works for processed assets. If processing is disabled, load_dependency changes are not hot reloaded. - [x] Replace AssetInfo dependency load/fail counters with `loading_dependencies: HashSet<UntypedAssetId>` to prevent reloads from (potentially) breaking counters. Storing this will also enable "dependency reloaded" events (see [Next Steps](#next-steps)) - [x] Re-add filesystem watcher cargo feature gate (currently it is not optional) - [ ] Migration Guide - [ ] Changelog ## Followup TODO - [ ] Replace "eager unchanged processed asset loading" behavior with "don't returned unchanged processed asset until dependencies have been checked". - [ ] Add true `Ignore` AssetAction that does not copy the asset to the imported_assets folder. - [ ] Finish "live asset unloading" (ex: free up CPU asset memory after uploading an image to the GPU), rethink RenderAssets, and port renderer features. The `Assets` collection uses `Option<T>` for asset storage to support its removal. (1) the Option might not actually be necessary ... might be able to just remove from the collection entirely (2) need to finalize removal apis - [ ] Try replacing the "channel based" asset id recycling with something a bit more efficient (ex: we might be able to use raw atomic ints with some cleverness) - [ ] Consider adding UUIDs to processed assets (scoped just to helping identify moved assets ... not exposed to load queries ... see [Next Steps](#next-steps)) - [ ] Store "last modified" source asset and meta timestamps in processed meta files to enable skipping expensive hashing when the file wasn't changed - [ ] Fix "slow loop" handle drop fix - [ ] Migrate to TypeName - [x] Handle "loader preregistration". See #9429 ## Next Steps * **Configurable per-type defaults for AssetMeta**: It should be possible to add configuration like "all png image meta should default to using nearest sampling" (currently this hard-coded per-loader/processor Settings::default() impls). Also see the "Folder Meta" bullet point. * **Avoid Reprocessing on Asset Renames / Moves**: See the "canonical asset ids" discussion in [Open Questions](#open-questions) and the relevant bullet point in [Draft TODO](#draft-todo). Even without canonical ids, folder renames could avoid reprocessing in some cases. * **Multiple Asset Sources**: Expand AssetPath to support "asset source names" and support multiple AssetReaders in the asset server (ex: `webserver://some_path/image.png` backed by an Http webserver AssetReader). The "default" asset reader would use normal `some_path/image.png` paths. Ideally this works in combination with multiple AssetWatchers for hot-reloading * **Stable Type Names**: this pr removes the TypeUuid requirement from assets in favor of `std::any::type_name`. This makes defining assets easier (no need to generate a new uuid / use weird proc macro syntax). It also makes reading meta files easier (because things have "friendly names"). We also use type names for components in scene files. If they are good enough for components, they are good enough for assets. And consistency across Bevy pillars is desirable. However, `std::any::type_name` is not guaranteed to be stable (although in practice it is). We've developed a [stable type path](https://github.com/bevyengine/bevy/pull/7184) to resolve this, which should be adopted when it is ready. * **Command Line Interface**: It should be possible to run the asset processor in a separate process from the command line. This will also require building a network-server-backed AssetReader to communicate between the app and the processor. We've been planning to build a "bevy cli" for awhile. This seems like a good excuse to build it. * **Asset Packing**: This is largely an additive feature, so it made sense to me to punt this until we've laid the foundations in this PR. * **Per-Platform Processed Assets**: It should be possible to generate assets for multiple platforms by supporting multiple "processor profiles" per asset (ex: compress with format X on PC and Y on iOS). I think there should probably be arbitrary "profiles" (which can be separate from actual platforms), which are then assigned to a given platform when generating the final asset distribution for that platform. Ex: maybe devs want a "Mobile" profile that is shared between iOS and Android. Or a "LowEnd" profile shared between web and mobile. * **Versioning and Migrations**: Assets, Loaders, Savers, and Processors need to have versions to determine if their schema is valid. If an asset / loader version is incompatible with the current version expected at runtime, the processor should be able to migrate them. I think we should try using Bevy Reflect for this, as it would allow us to load the old version as a dynamic Reflect type without actually having the old Rust type. It would also allow us to define "patches" to migrate between versions (Bevy Reflect devs are currently working on patching). The `.meta` file already has its own format version. Migrating that to new versions should also be possible. * **Real Copy-on-write AssetPaths**: Rust's actual Cow (clone-on-write type) currently used by AssetPath can still result in String clones that aren't actually necessary (cloning an Owned Cow clones the contents). Bevy's asset system requires cloning AssetPaths in a number of places, which result in actual clones of the internal Strings. This is not efficient. AssetPath internals should be reworked to exhibit truer cow-like-behavior that reduces String clones to the absolute minimum. * **Consider processor-less processing**: In theory the AssetServer could run processors "inline" even if the background AssetProcessor is disabled. If we decide this is actually desirable, we could add this. But I don't think its a priority in the short or medium term. * **Pre-emptive dependency loading**: We could encode dependencies in processed meta files, which could then be used by the Asset Server to kick of dependency loads as early as possible (prior to starting the actual asset load). Is this desirable? How much time would this save in practice? * **Optimize Processor With UntypedAssetIds**: The processor exclusively uses AssetPath to identify assets currently. It might be possible to swap these out for UntypedAssetIds in some places, which are smaller / cheaper to hash and compare. * **One to Many Asset Processing**: An asset source file that produces many assets currently must be processed into a single "processed" asset source. If labeled assets can be written separately they can each have their own configured savers _and_ they could be loaded more granularly. Definitely worth exploring! * **Automatically Track "Runtime-only" Asset Dependencies**: Right now, tracking "created at runtime" asset dependencies requires adding them via `asset_server.load_asset(StandardMaterial::default())`. I think with some cleverness we could also do this for `materials.add(StandardMaterial::default())`, making tracking work "everywhere". There are challenges here relating to change detection / ensuring the server is made aware of dependency changes. This could be expensive in some cases. * **"Dependency Changed" events**: Some assets have runtime artifacts that need to be re-generated when one of their dependencies change (ex: regenerate a material's bind group when a Texture needs to change). We are generating the dependency graph so we can definitely produce these events. Buuuuut generating these events will have a cost / they could be high frequency for some assets, so we might want this to be opt-in for specific cases. * **Investigate Storing More Information In Handles**: Handles can now store arbitrary information, which makes it cheaper and easier to access. How much should we move into them? Canonical asset load states (via atomics)? (`handle.is_loaded()` would be very cool). Should we store the entire asset and remove the `Assets<T>` collection? (`Arc<RwLock<Option<Image>>>`?) * **Support processing and loading files without extensions**: This is a pretty arbitrary restriction and could be supported with very minimal changes. * **Folder Meta**: It would be nice if we could define per folder processor configuration defaults (likely in a `.meta` or `.folder_meta` file). Things like "default to linear filtering for all Images in this folder". * **Replace async_broadcast with event-listener?** This might be approximately drop-in for some uses and it feels more light weight * **Support Running the AssetProcessor on the Web**: Most of the hard work is done here, but there are some easy straggling TODOs (make the transaction log an interface instead of a direct file writer so we can write a web storage backend, implement an AssetReader/AssetWriter that reads/writes to something like LocalStorage). * **Consider identifying and preventing circular dependencies**: This is especially important for "processor dependencies", as processing will silently never finish in these cases. * **Built-in/Inlined Asset Hot Reloading**: This PR regresses "built-in/inlined" asset hot reloading (previously provided by the DebugAssetServer). I'm intentionally punting this because I think it can be cleanly implemented with "multiple asset sources" by registering a "debug asset source" (ex: `debug://bevy_pbr/src/render/pbr.wgsl` asset paths) in combination with an AssetWatcher for that asset source and support for "manually loading pats with asset bytes instead of AssetReaders". The old DebugAssetServer was quite nasty and I'd love to avoid that hackery going forward. * **Investigate ways to remove double-parsing meta files**: Parsing meta files currently involves parsing once with "minimal" versions of the meta file to extract the type name of the loader/processor config, then parsing again to parse the "full" meta. This is suboptimal. We should be able to define custom deserializers that (1) assume the loader/processor type name comes first (2) dynamically looks up the loader/processor registrations to deserialize settings in-line (similar to components in the bevy scene format). Another alternative: deserialize as dynamic Reflect objects and then convert. * **More runtime loading configuration**: Support using the Handle type as a hint to select an asset loader (instead of relying on AssetPath extensions) * **More high level Processor trait implementations**: For example, it might be worth adding support for arbitrary chains of "asset transforms" that modify an in-memory asset representation between loading and saving. (ex: load a Mesh, run a `subdivide_mesh` transform, followed by a `flip_normals` transform, then save the mesh to an efficient compressed format). * **Bevy Scene Handle Deserialization**: (see the relevant [Draft TODO item](#draft-todo) for context) * **Explore High Level Load Interfaces**: See [this discussion](#discuss-on_loaded-high-level-interface) for one prototype. * **Asset Streaming**: It would be great if we could stream Assets (ex: stream a long video file piece by piece) * **ID Exchanging**: In this PR Asset Handles/AssetIds are bigger than they need to be because they have a Uuid enum variant. If we implement an "id exchanging" system that trades Uuids for "efficient runtime ids", we can cut down on the size of AssetIds, making them more efficient. This has some open design questions, such as how to spawn entities with "default" handle values (as these wouldn't have access to the exchange api in the current system). * **Asset Path Fixup Tooling**: Assets that inline asset paths inside them will break when an asset moves. The asset system provides the functionality to detect when paths break. We should build a framework that enables formats to define "path migrations". This is especially important for scene files. For editor-generated files, we should also consider using UUIDs (see other bullet point) to avoid the need to migrate in these cases. --------- Co-authored-by: BeastLe9enD <beastle9end@outlook.de> Co-authored-by: Mike <mike.hsu@gmail.com> Co-authored-by: Nicola Papale <nicopap@users.noreply.github.com>
2023-09-07 02:07:27 +00:00
description = "Implements a custom AssetReader"
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
category = "Assets"
Remove some asset examples from web showcase (#14973) # Objective - `custom_asset_reader` and `extra_asset_source` examples are not working on web. - Fixes #14689 ## Solution - Make these examples `wasm=false` per https://github.com/bevyengine/bevy/issues/14689#issuecomment-2313064396 ## Testing
2024-08-29 16:47:58 +00:00
# Incompatible with the asset path patching of the example-showcase tool
wasm = false
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
Fix embedded asset path manipulation (#10383) # Objective Fixes #10377 ## Solution Use `Path::strip_prefix` instead of `str::split`. Avoid any explicit "/" characters in path manipulation. --- ## Changelog - Added: example of embedded asset loading - Added: support embedded assets in external crates - Fixed: resolution of embedded assets - Fixed: unexpected runtime panic during asset path resolution ## Migration Guide No API changes. --------- Co-authored-by: Shane Celis <shane.celis@gmail.com>
2024-02-02 14:49:05 +00:00
[[example]]
name = "embedded_asset"
path = "examples/asset/embedded_asset.rs"
doc-scrape-examples = true
[package.metadata.example.embedded_asset]
name = "Embedded Asset"
description = "Embed an asset in the application binary and load it"
category = "Assets"
wasm = true
Add extra_asset_source example (#11824) # Objective - Make it easier to figure out how to add asset sources ## Solution - Add an example that adds an asset source, it functions almost identical to the embedded_asset example - Move the file from the embedded_asset example into a `files/` folder
2024-03-06 16:00:03 +00:00
[[example]]
name = "extra_asset_source"
path = "examples/asset/extra_source.rs"
doc-scrape-examples = true
[package.metadata.example.extra_asset_source]
name = "Extra asset source"
description = "Load an asset from a non-standard asset source"
category = "Assets"
Remove some asset examples from web showcase (#14973) # Objective - `custom_asset_reader` and `extra_asset_source` examples are not working on web. - Fixes #14689 ## Solution - Make these examples `wasm=false` per https://github.com/bevyengine/bevy/issues/14689#issuecomment-2313064396 ## Testing
2024-08-29 16:47:58 +00:00
# Uses non-standard asset path
wasm = false
Add extra_asset_source example (#11824) # Objective - Make it easier to figure out how to add asset sources ## Solution - Add an example that adds an asset source, it functions almost identical to the embedded_asset example - Move the file from the embedded_asset example into a `files/` folder
2024-03-06 16:00:03 +00:00
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
[[example]]
name = "hot_asset_reloading"
path = "examples/asset/hot_asset_reloading.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Multiple Asset Sources (#9885) This adds support for **Multiple Asset Sources**. You can now register a named `AssetSource`, which you can load assets from like you normally would: ```rust let shader: Handle<Shader> = asset_server.load("custom_source://path/to/shader.wgsl"); ``` Notice that `AssetPath` now supports `some_source://` syntax. This can now be accessed through the `asset_path.source()` accessor. Asset source names _are not required_. If one is not specified, the default asset source will be used: ```rust let shader: Handle<Shader> = asset_server.load("path/to/shader.wgsl"); ``` The behavior of the default asset source has not changed. Ex: the `assets` folder is still the default. As referenced in #9714 ## Why? **Multiple Asset Sources** enables a number of often-asked-for scenarios: * **Loading some assets from other locations on disk**: you could create a `config` asset source that reads from the OS-default config folder (not implemented in this PR) * **Loading some assets from a remote server**: you could register a new `remote` asset source that reads some assets from a remote http server (not implemented in this PR) * **Improved "Binary Embedded" Assets**: we can use this system for "embedded-in-binary assets", which allows us to replace the old `load_internal_asset!` approach, which couldn't support asset processing, didn't support hot-reloading _well_, and didn't make embedded assets accessible to the `AssetServer` (implemented in this pr) ## Adding New Asset Sources An `AssetSource` is "just" a collection of `AssetReader`, `AssetWriter`, and `AssetWatcher` entries. You can configure new asset sources like this: ```rust app.register_asset_source( "other", AssetSource::build() .with_reader(|| Box::new(FileAssetReader::new("other"))) ) ) ``` Note that `AssetSource` construction _must_ be repeatable, which is why a closure is accepted. `AssetSourceBuilder` supports `with_reader`, `with_writer`, `with_watcher`, `with_processed_reader`, `with_processed_writer`, and `with_processed_watcher`. Note that the "asset source" system replaces the old "asset providers" system. ## Processing Multiple Sources The `AssetProcessor` now supports multiple asset sources! Processed assets can refer to assets in other sources and everything "just works". Each `AssetSource` defines an unprocessed and processed `AssetReader` / `AssetWriter`. Currently this is all or nothing for a given `AssetSource`. A given source is either processed or it is not. Later we might want to add support for "lazy asset processing", where an `AssetSource` (such as a remote server) can be configured to only process assets that are directly referenced by local assets (in order to save local disk space and avoid doing extra work). ## A new `AssetSource`: `embedded` One of the big features motivating **Multiple Asset Sources** was improving our "embedded-in-binary" asset loading. To prove out the **Multiple Asset Sources** implementation, I chose to build a new `embedded` `AssetSource`, which replaces the old `load_interal_asset!` system. The old `load_internal_asset!` approach had a number of issues: * The `AssetServer` was not aware of (or capable of loading) internal assets. * Because internal assets weren't visible to the `AssetServer`, they could not be processed (or used by assets that are processed). This would prevent things "preprocessing shaders that depend on built in Bevy shaders", which is something we desperately need to start doing. * Each "internal asset" needed a UUID to be defined in-code to reference it. This was very manual and toilsome. The new `embedded` `AssetSource` enables the following pattern: ```rust // Called in `crates/bevy_pbr/src/render/mesh.rs` embedded_asset!(app, "mesh.wgsl"); // later in the app let shader: Handle<Shader> = asset_server.load("embedded://bevy_pbr/render/mesh.wgsl"); ``` Notice that this always treats the crate name as the "root path", and it trims out the `src` path for brevity. This is generally predictable, but if you need to debug you can use the new `embedded_path!` macro to get a `PathBuf` that matches the one used by `embedded_asset`. You can also reference embedded assets in arbitrary assets, such as WGSL shaders: ```rust #import "embedded://bevy_pbr/render/mesh.wgsl" ``` This also makes `embedded` assets go through the "normal" asset lifecycle. They are only loaded when they are actually used! We are also discussing implicitly converting asset paths to/from shader modules, so in the future (not in this PR) you might be able to load it like this: ```rust #import bevy_pbr::render::mesh::Vertex ``` Compare that to the old system! ```rust pub const MESH_SHADER_HANDLE: Handle<Shader> = Handle::weak_from_u128(3252377289100772450); load_internal_asset!(app, MESH_SHADER_HANDLE, "mesh.wgsl", Shader::from_wgsl); // The mesh asset is the _only_ accessible via MESH_SHADER_HANDLE and _cannot_ be loaded via the AssetServer. ``` ## Hot Reloading `embedded` You can enable `embedded` hot reloading by enabling the `embedded_watcher` cargo feature: ``` cargo run --features=embedded_watcher ``` ## Improved Hot Reloading Workflow First: the `filesystem_watcher` cargo feature has been renamed to `file_watcher` for brevity (and to match the `FileAssetReader` naming convention). More importantly, hot asset reloading is no longer configured in-code by default. If you enable any asset watcher feature (such as `file_watcher` or `rust_source_watcher`), asset watching will be automatically enabled. This removes the need to _also_ enable hot reloading in your app code. That means you can replace this: ```rust app.add_plugins(DefaultPlugins.set(AssetPlugin::default().watch_for_changes())) ``` with this: ```rust app.add_plugins(DefaultPlugins) ``` If you want to hot reload assets in your app during development, just run your app like this: ``` cargo run --features=file_watcher ``` This means you can use the same code for development and deployment! To deploy an app, just don't include the watcher feature ``` cargo build --release ``` My intent is to move to this approach for pretty much all dev workflows. In a future PR I would like to replace `AssetMode::ProcessedDev` with a `runtime-processor` cargo feature. We could then group all common "dev" cargo features under a single `dev` feature: ```sh # this would enable file_watcher, embedded_watcher, runtime-processor, and more cargo run --features=dev ``` ## AssetMode `AssetPlugin::Unprocessed`, `AssetPlugin::Processed`, and `AssetPlugin::ProcessedDev` have been replaced with an `AssetMode` field on `AssetPlugin`. ```rust // before app.add_plugins(DefaultPlugins.set(AssetPlugin::Processed { /* fields here */ }) // after app.add_plugins(DefaultPlugins.set(AssetPlugin { mode: AssetMode::Processed, ..default() }) ``` This aligns `AssetPlugin` with our other struct-like plugins. The old "source" and "destination" `AssetProvider` fields in the enum variants have been replaced by the "asset source" system. You no longer need to configure the AssetPlugin to "point" to custom asset providers. ## AssetServerMode To improve the implementation of **Multiple Asset Sources**, `AssetServer` was made aware of whether or not it is using "processed" or "unprocessed" assets. You can check that like this: ```rust if asset_server.mode() == AssetServerMode::Processed { /* do something */ } ``` Note that this refactor should also prepare the way for building "one to many processed output files", as it makes the server aware of whether it is loading from processed or unprocessed sources. Meaning we can store and read processed and unprocessed assets differently! ## AssetPath can now refer to folders The "file only" restriction has been removed from `AssetPath`. The `AssetServer::load_folder` API now accepts an `AssetPath` instead of a `Path`, meaning you can load folders from other asset sources! ## Improved AssetPath Parsing AssetPath parsing was reworked to support sources, improve error messages, and to enable parsing with a single pass over the string. `AssetPath::new` was replaced by `AssetPath::parse` and `AssetPath::try_parse`. ## AssetWatcher broken out from AssetReader `AssetReader` is no longer responsible for constructing `AssetWatcher`. This has been moved to `AssetSourceBuilder`. ## Duplicate Event Debouncing Asset V2 already debounced duplicate filesystem events, but this was _input_ events. Multiple input event types can produce the same _output_ `AssetSourceEvent`. Now that we have `embedded_watcher`, which does expensive file io on events, it made sense to debounce output events too, so I added that! This will also benefit the AssetProcessor by preventing integrity checks for duplicate events (and helps keep the noise down in trace logs). ## Next Steps * **Port Built-in Shaders**: Currently the primary (and essentially only) user of `load_interal_asset` in Bevy's source code is "built-in shaders". I chose not to do that in this PR for a few reasons: 1. We need to add the ability to pass shader defs in to shaders via meta files. Some shaders (such as MESH_VIEW_TYPES) need to pass shader def values in that are defined in code. 2. We need to revisit the current shader module naming system. I think we _probably_ want to imply modules from source structure (at least by default). Ideally in a way that can losslessly convert asset paths to/from shader modules (to enable the asset system to resolve modules using the asset server). 3. I want to keep this change set minimal / get this merged first. * **Deprecate `load_internal_asset`**: we can't do that until we do (1) and (2) * **Relative Asset Paths**: This PR significantly increases the need for relative asset paths (which was already pretty high). Currently when loading dependencies, it is assumed to be an absolute path, which means if in an `AssetLoader` you call `context.load("some/path/image.png")` it will assume that is the "default" asset source, _even if the current asset is in a different asset source_. This will cause breakage for AssetLoaders that are not designed to add the current source to whatever paths are being used. AssetLoaders should generally not need to be aware of the name of their current asset source, or need to think about the "current asset source" generally. We should build apis that support relative asset paths and then encourage using relative paths as much as possible (both via api design and docs). Relative paths are also important because they will allow developers to move folders around (even across providers) without reprocessing, provided there is no path breakage.
2023-10-13 23:17:32 +00:00
required-features = ["file_watcher"]
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.hot_asset_reloading]
name = "Hot Reloading of Assets"
description = "Demonstrates automatic reloading of assets when modified on disk"
category = "Assets"
support required features in wasm examples showcase (#10577) # Objective - Examples with required features fail to build - If you're fixing a specific issue, say "Fixes #X". ## Solution - Pass them along when building examples for wasm showcase - Also mark example `hot_asset_reloading` as not wasm compatible as it isn't even with the right features enabled
2023-11-16 01:50:25 +00:00
wasm = false
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
Bevy Asset V2 (#8624) # Bevy Asset V2 Proposal ## Why Does Bevy Need A New Asset System? Asset pipelines are a central part of the gamedev process. Bevy's current asset system is missing a number of features that make it non-viable for many classes of gamedev. After plenty of discussions and [a long community feedback period](https://github.com/bevyengine/bevy/discussions/3972), we've identified a number missing features: * **Asset Preprocessing**: it should be possible to "preprocess" / "compile" / "crunch" assets at "development time" rather than when the game starts up. This enables offloading expensive work from deployed apps, faster asset loading, less runtime memory usage, etc. * **Per-Asset Loader Settings**: Individual assets cannot define their own loaders that override the defaults. Additionally, they cannot provide per-asset settings to their loaders. This is a huge limitation, as many asset types don't provide all information necessary for Bevy _inside_ the asset. For example, a raw PNG image says nothing about how it should be sampled (ex: linear vs nearest). * **Asset `.meta` files**: assets should have configuration files stored adjacent to the asset in question, which allows the user to configure asset-type-specific settings. These settings should be accessible during the pre-processing phase. Modifying a `.meta` file should trigger a re-processing / re-load of the asset. It should be possible to configure asset loaders from the meta file. * **Processed Asset Hot Reloading**: Changes to processed assets (or their dependencies) should result in re-processing them and re-loading the results in live Bevy Apps. * **Asset Dependency Tracking**: The current bevy_asset has no good way to wait for asset dependencies to load. It punts this as an exercise for consumers of the loader apis, which is unreasonable and error prone. There should be easy, ergonomic ways to wait for assets to load and block some logic on an asset's entire dependency tree loading. * **Runtime Asset Loading**: it should be (optionally) possible to load arbitrary assets dynamically at runtime. This necessitates being able to deploy and run the asset server alongside Bevy Apps on _all platforms_. For example, we should be able to invoke the shader compiler at runtime, stream scenes from sources like the internet, etc. To keep deployed binaries (and startup times) small, the runtime asset server configuration should be configurable with different settings compared to the "pre processor asset server". * **Multiple Backends**: It should be possible to load assets from arbitrary sources (filesystems, the internet, remote asset serves, etc). * **Asset Packing**: It should be possible to deploy assets in compressed "packs", which makes it easier and more efficient to distribute assets with Bevy Apps. * **Asset Handoff**: It should be possible to hold a "live" asset handle, which correlates to runtime data, without actually holding the asset in memory. Ex: it must be possible to hold a reference to a GPU mesh generated from a "mesh asset" without keeping the mesh data in CPU memory * **Per-Platform Processed Assets**: Different platforms and app distributions have different capabilities and requirements. Some platforms need lower asset resolutions or different asset formats to operate within the hardware constraints of the platform. It should be possible to define per-platform asset processing profiles. And it should be possible to deploy only the assets required for a given platform. These features have architectural implications that are significant enough to require a full rewrite. The current Bevy Asset implementation got us this far, but it can take us no farther. This PR defines a brand new asset system that implements most of these features, while laying the foundations for the remaining features to be built. ## Bevy Asset V2 Here is a quick overview of the features introduced in this PR. * **Asset Preprocessing**: Preprocess assets at development time into more efficient (and configurable) representations * **Dependency Aware**: Dependencies required to process an asset are tracked. If an asset's processed dependency changes, it will be reprocessed * **Hot Reprocessing/Reloading**: detect changes to asset source files, reprocess them if they have changed, and then hot-reload them in Bevy Apps. * **Only Process Changes**: Assets are only re-processed when their source file (or meta file) has changed. This uses hashing and timestamps to avoid processing assets that haven't changed. * **Transactional and Reliable**: Uses write-ahead logging (a technique commonly used by databases) to recover from crashes / forced-exits. Whenever possible it avoids full-reprocessing / only uncompleted transactions will be reprocessed. When the processor is running in parallel with a Bevy App, processor asset writes block Bevy App asset reads. Reading metadata + asset bytes is guaranteed to be transactional / correctly paired. * **Portable / Run anywhere / Database-free**: The processor does not rely on an in-memory database (although it uses some database techniques for reliability). This is important because pretty much all in-memory databases have unsupported platforms or build complications. * **Configure Processor Defaults Per File Type**: You can say "use this processor for all files of this type". * **Custom Processors**: The `Processor` trait is flexible and unopinionated. It can be implemented by downstream plugins. * **LoadAndSave Processors**: Most asset processing scenarios can be expressed as "run AssetLoader A, save the results using AssetSaver X, and then load the result using AssetLoader B". For example, load this png image using `PngImageLoader`, which produces an `Image` asset and then save it using `CompressedImageSaver` (which also produces an `Image` asset, but in a compressed format), which takes an `Image` asset as input. This means if you have an `AssetLoader` for an asset, you are already half way there! It also means that you can share AssetSavers across multiple loaders. Because `CompressedImageSaver` accepts Bevy's generic Image asset as input, it means you can also use it with some future `JpegImageLoader`. * **Loader and Saver Settings**: Asset Loaders and Savers can now define their own settings types, which are passed in as input when an asset is loaded / saved. Each asset can define its own settings. * **Asset `.meta` files**: configure asset loaders, their settings, enable/disable processing, and configure processor settings * **Runtime Asset Dependency Tracking** Runtime asset dependencies (ex: if an asset contains a `Handle<Image>`) are tracked by the asset server. An event is emitted when an asset and all of its dependencies have been loaded * **Unprocessed Asset Loading**: Assets do not require preprocessing. They can be loaded directly. A processed asset is just a "normal" asset with some extra metadata. Asset Loaders don't need to know or care about whether or not an asset was processed. * **Async Asset IO**: Asset readers/writers use async non-blocking interfaces. Note that because Rust doesn't yet support async traits, there is a bit of manual Boxing / Future boilerplate. This will hopefully be removed in the near future when Rust gets async traits. * **Pluggable Asset Readers and Writers**: Arbitrary asset source readers/writers are supported, both by the processor and the asset server. * **Better Asset Handles** * **Single Arc Tree**: Asset Handles now use a single arc tree that represents the lifetime of the asset. This makes their implementation simpler, more efficient, and allows us to cheaply attach metadata to handles. Ex: the AssetPath of a handle is now directly accessible on the handle itself! * **Const Typed Handles**: typed handles can be constructed in a const context. No more weird "const untyped converted to typed at runtime" patterns! * **Handles and Ids are Smaller / Faster To Hash / Compare**: Typed `Handle<T>` is now much smaller in memory and `AssetId<T>` is even smaller. * **Weak Handle Usage Reduction**: In general Handles are now considered to be "strong". Bevy features that previously used "weak `Handle<T>`" have been ported to `AssetId<T>`, which makes it statically clear that the features do not hold strong handles (while retaining strong type information). Currently Handle::Weak still exists, but it is very possible that we can remove that entirely. * **Efficient / Dense Asset Ids**: Assets now have efficient dense runtime asset ids, which means we can avoid expensive hash lookups. Assets are stored in Vecs instead of HashMaps. There are now typed and untyped ids, which means we no longer need to store dynamic type information in the ID for typed handles. "AssetPathId" (which was a nightmare from a performance and correctness standpoint) has been entirely removed in favor of dense ids (which are retrieved for a path on load) * **Direct Asset Loading, with Dependency Tracking**: Assets that are defined at runtime can still have their dependencies tracked by the Asset Server (ex: if you create a material at runtime, you can still wait for its textures to load). This is accomplished via the (currently optional) "asset dependency visitor" trait. This system can also be used to define a set of assets to load, then wait for those assets to load. * **Async folder loading**: Folder loading also uses this system and immediately returns a handle to the LoadedFolder asset, which means folder loading no longer blocks on directory traversals. * **Improved Loader Interface**: Loaders now have a specific "top level asset type", which makes returning the top-level asset simpler and statically typed. * **Basic Image Settings and Processing**: Image assets can now be processed into the gpu-friendly Basic Universal format. The ImageLoader now has a setting to define what format the image should be loaded as. Note that this is just a minimal MVP ... plenty of additional work to do here. To demo this, enable the `basis-universal` feature and turn on asset processing. * **Simpler Audio Play / AudioSink API**: Asset handle providers are cloneable, which means the Audio resource can mint its own handles. This means you can now do `let sink_handle = audio.play(music)` instead of `let sink_handle = audio_sinks.get_handle(audio.play(music))`. Note that this might still be replaced by https://github.com/bevyengine/bevy/pull/8424. **Removed Handle Casting From Engine Features**: Ex: FontAtlases no longer use casting between handle types ## Using The New Asset System ### Normal Unprocessed Asset Loading By default the `AssetPlugin` does not use processing. It behaves pretty much the same way as the old system. If you are defining a custom asset, first derive `Asset`: ```rust #[derive(Asset)] struct Thing { value: String, } ``` Initialize the asset: ```rust app.init_asset:<Thing>() ``` Implement a new `AssetLoader` for it: ```rust #[derive(Default)] struct ThingLoader; #[derive(Serialize, Deserialize, Default)] pub struct ThingSettings { some_setting: bool, } impl AssetLoader for ThingLoader { type Asset = Thing; type Settings = ThingSettings; fn load<'a>( &'a self, reader: &'a mut Reader, settings: &'a ThingSettings, load_context: &'a mut LoadContext, ) -> BoxedFuture<'a, Result<Thing, anyhow::Error>> { Box::pin(async move { let mut bytes = Vec::new(); reader.read_to_end(&mut bytes).await?; // convert bytes to value somehow Ok(Thing { value }) }) } fn extensions(&self) -> &[&str] { &["thing"] } } ``` Note that this interface will get much cleaner once Rust gets support for async traits. `Reader` is an async futures_io::AsyncRead. You can stream bytes as they come in or read them all into a `Vec<u8>`, depending on the context. You can use `let handle = load_context.load(path)` to kick off a dependency load, retrieve a handle, and register the dependency for the asset. Then just register the loader in your Bevy app: ```rust app.init_asset_loader::<ThingLoader>() ``` Now just add your `Thing` asset files into the `assets` folder and load them like this: ```rust fn system(asset_server: Res<AssetServer>) { let handle = Handle<Thing> = asset_server.load("cool.thing"); } ``` You can check load states directly via the asset server: ```rust if asset_server.load_state(&handle) == LoadState::Loaded { } ``` You can also listen for events: ```rust fn system(mut events: EventReader<AssetEvent<Thing>>, handle: Res<SomeThingHandle>) { for event in events.iter() { if event.is_loaded_with_dependencies(&handle) { } } } ``` Note the new `AssetEvent::LoadedWithDependencies`, which only fires when the asset is loaded _and_ all dependencies (and their dependencies) have loaded. Unlike the old asset system, for a given asset path all `Handle<T>` values point to the same underlying Arc. This means Handles can cheaply hold more asset information, such as the AssetPath: ```rust // prints the AssetPath of the handle info!("{:?}", handle.path()) ``` ### Processed Assets Asset processing can be enabled via the `AssetPlugin`. When developing Bevy Apps with processed assets, do this: ```rust app.add_plugins(DefaultPlugins.set(AssetPlugin::processed_dev())) ``` This runs the `AssetProcessor` in the background with hot-reloading. It reads assets from the `assets` folder, processes them, and writes them to the `.imported_assets` folder. Asset loads in the Bevy App will wait for a processed version of the asset to become available. If an asset in the `assets` folder changes, it will be reprocessed and hot-reloaded in the Bevy App. When deploying processed Bevy apps, do this: ```rust app.add_plugins(DefaultPlugins.set(AssetPlugin::processed())) ``` This does not run the `AssetProcessor` in the background. It behaves like `AssetPlugin::unprocessed()`, but reads assets from `.imported_assets`. When the `AssetProcessor` is running, it will populate sibling `.meta` files for assets in the `assets` folder. Meta files for assets that do not have a processor configured look like this: ```rust ( meta_format_version: "1.0", asset: Load( loader: "bevy_render::texture::image_loader::ImageLoader", settings: ( format: FromExtension, ), ), ) ``` This is metadata for an image asset. For example, if you have `assets/my_sprite.png`, this could be the metadata stored at `assets/my_sprite.png.meta`. Meta files are totally optional. If no metadata exists, the default settings will be used. In short, this file says "load this asset with the ImageLoader and use the file extension to determine the image type". This type of meta file is supported in all AssetPlugin modes. If in `Unprocessed` mode, the asset (with the meta settings) will be loaded directly. If in `ProcessedDev` mode, the asset file will be copied directly to the `.imported_assets` folder. The meta will also be copied directly to the `.imported_assets` folder, but with one addition: ```rust ( meta_format_version: "1.0", processed_info: Some(( hash: 12415480888597742505, full_hash: 14344495437905856884, process_dependencies: [], )), asset: Load( loader: "bevy_render::texture::image_loader::ImageLoader", settings: ( format: FromExtension, ), ), ) ``` `processed_info` contains `hash` (a direct hash of the asset and meta bytes), `full_hash` (a hash of `hash` and the hashes of all `process_dependencies`), and `process_dependencies` (the `path` and `full_hash` of every process_dependency). A "process dependency" is an asset dependency that is _directly_ used when processing the asset. Images do not have process dependencies, so this is empty. When the processor is enabled, you can use the `Process` metadata config: ```rust ( meta_format_version: "1.0", asset: Process( processor: "bevy_asset::processor::process::LoadAndSave<bevy_render::texture::image_loader::ImageLoader, bevy_render::texture::compressed_image_saver::CompressedImageSaver>", settings: ( loader_settings: ( format: FromExtension, ), saver_settings: ( generate_mipmaps: true, ), ), ), ) ``` This configures the asset to use the `LoadAndSave` processor, which runs an AssetLoader and feeds the result into an AssetSaver (which saves the given Asset and defines a loader to load it with). (for terseness LoadAndSave will likely get a shorter/friendlier type name when [Stable Type Paths](#7184) lands). `LoadAndSave` is likely to be the most common processor type, but arbitrary processors are supported. `CompressedImageSaver` saves an `Image` in the Basis Universal format and configures the ImageLoader to load it as basis universal. The `AssetProcessor` will read this meta, run it through the LoadAndSave processor, and write the basis-universal version of the image to `.imported_assets`. The final metadata will look like this: ```rust ( meta_format_version: "1.0", processed_info: Some(( hash: 905599590923828066, full_hash: 9948823010183819117, process_dependencies: [], )), asset: Load( loader: "bevy_render::texture::image_loader::ImageLoader", settings: ( format: Format(Basis), ), ), ) ``` To try basis-universal processing out in Bevy examples, (for example `sprite.rs`), change `add_plugins(DefaultPlugins)` to `add_plugins(DefaultPlugins.set(AssetPlugin::processed_dev()))` and run with the `basis-universal` feature enabled: `cargo run --features=basis-universal --example sprite`. To create a custom processor, there are two main paths: 1. Use the `LoadAndSave` processor with an existing `AssetLoader`. Implement the `AssetSaver` trait, register the processor using `asset_processor.register_processor::<LoadAndSave<ImageLoader, CompressedImageSaver>>(image_saver.into())`. 2. Implement the `Process` trait directly and register it using: `asset_processor.register_processor(thing_processor)`. You can configure default processors for file extensions like this: ```rust asset_processor.set_default_processor::<ThingProcessor>("thing") ``` There is one more metadata type to be aware of: ```rust ( meta_format_version: "1.0", asset: Ignore, ) ``` This will ignore the asset during processing / prevent it from being written to `.imported_assets`. The AssetProcessor stores a transaction log at `.imported_assets/log` and uses it to gracefully recover from unexpected stops. This means you can force-quit the processor (and Bevy Apps running the processor in parallel) at arbitrary times! `.imported_assets` is "local state". It should _not_ be checked into source control. It should also be considered "read only". In practice, you _can_ modify processed assets and processed metadata if you really need to test something. But those modifications will not be represented in the hashes of the assets, so the processed state will be "out of sync" with the source assets. The processor _will not_ fix this for you. Either revert the change after you have tested it, or delete the processed files so they can be re-populated. ## Open Questions There are a number of open questions to be discussed. We should decide if they need to be addressed in this PR and if so, how we will address them: ### Implied Dependencies vs Dependency Enumeration There are currently two ways to populate asset dependencies: * **Implied via AssetLoaders**: if an AssetLoader loads an asset (and retrieves a handle), a dependency is added to the list. * **Explicit via the optional Asset::visit_dependencies**: if `server.load_asset(my_asset)` is called, it will call `my_asset.visit_dependencies`, which will grab dependencies that have been manually defined for the asset via the Asset trait impl (which can be derived). This means that defining explicit dependencies is optional for "loaded assets". And the list of dependencies is always accurate because loaders can only produce Handles if they register dependencies. If an asset was loaded with an AssetLoader, it only uses the implied dependencies. If an asset was created at runtime and added with `asset_server.load_asset(MyAsset)`, it will use `Asset::visit_dependencies`. However this can create a behavior mismatch between loaded assets and equivalent "created at runtime" assets if `Assets::visit_dependencies` doesn't exactly match the dependencies produced by the AssetLoader. This behavior mismatch can be resolved by completely removing "implied loader dependencies" and requiring `Asset::visit_dependencies` to supply dependency data. But this creates two problems: * It makes defining loaded assets harder and more error prone: Devs must remember to manually annotate asset dependencies with `#[dependency]` when deriving `Asset`. For more complicated assets (such as scenes), the derive likely wouldn't be sufficient and a manual `visit_dependencies` impl would be required. * Removes the ability to immediately kick off dependency loads: When AssetLoaders retrieve a Handle, they also immediately kick off an asset load for the handle, which means it can start loading in parallel _before_ the asset finishes loading. For large assets, this could be significant. (although this could be mitigated for processed assets if we store dependencies in the processed meta file and load them ahead of time) ### Eager ProcessorDev Asset Loading I made a controversial call in the interest of fast startup times ("time to first pixel") for the "processor dev mode configuration". When initializing the AssetProcessor, current processed versions of unchanged assets are yielded immediately, even if their dependencies haven't been checked yet for reprocessing. This means that non-current-state-of-filesystem-but-previously-valid assets might be returned to the App first, then hot-reloaded if/when their dependencies change and the asset is reprocessed. Is this behavior desirable? There is largely one alternative: do not yield an asset from the processor to the app until all of its dependencies have been checked for changes. In some common cases (load dependency has not changed since last run) this will increase startup time. The main question is "by how much" and is that slower startup time worth it in the interest of only yielding assets that are true to the current state of the filesystem. Should this be configurable? I'm starting to think we should only yield an asset after its (historical) dependencies have been checked for changes + processed as necessary, but I'm curious what you all think. ### Paths Are Currently The Only Canonical ID / Do We Want Asset UUIDs? In this implementation AssetPaths are the only canonical asset identifier (just like the previous Bevy Asset system and Godot). Moving assets will result in re-scans (and currently reprocessing, although reprocessing can easily be avoided with some changes). Asset renames/moves will break code and assets that rely on specific paths, unless those paths are fixed up. Do we want / need "stable asset uuids"? Introducing them is very possible: 1. Generate a UUID and include it in .meta files 2. Support UUID in AssetPath 3. Generate "asset indices" which are loaded on startup and map UUIDs to paths. 4 (maybe). Consider only supporting UUIDs for processed assets so we can generate quick-to-load indices instead of scanning meta files. The main "pro" is that assets referencing UUIDs don't need to be migrated when a path changes. The main "con" is that UUIDs cannot be "lazily resolved" like paths. They need a full view of all assets to answer the question "does this UUID exist". Which means UUIDs require the AssetProcessor to fully finish startup scans before saying an asset doesnt exist. And they essentially require asset pre-processing to use in apps, because scanning all asset metadata files at runtime to resolve a UUID is not viable for medium-to-large apps. It really requires a pre-generated UUID index, which must be loaded before querying for assets. I personally think this should be investigated in a separate PR. Paths aren't going anywhere ... _everyone_ uses filesystems (and filesystem-like apis) to manage their asset source files. I consider them permanent canonical asset information. Additionally, they behave well for both processed and unprocessed asset modes. Given that Bevy is supporting both, this feels like the right canonical ID to start with. UUIDS (and maybe even other indexed-identifier types) can be added later as necessary. ### Folder / File Naming Conventions All asset processing config currently lives in the `.imported_assets` folder. The processor transaction log is in `.imported_assets/log`. Processed assets are added to `.imported_assets/Default`, which will make migrating to processed asset profiles (ex: a `.imported_assets/Mobile` profile) a non-breaking change. It also allows us to create top-level files like `.imported_assets/log` without it being interpreted as an asset. Meta files currently have a `.meta` suffix. Do we like these names and conventions? ### Should the `AssetPlugin::processed_dev` configuration enable `watch_for_changes` automatically? Currently it does (which I think makes sense), but it does make it the only configuration that enables watch_for_changes by default. ### Discuss on_loaded High Level Interface: This PR includes a very rough "proof of concept" `on_loaded` system adapter that uses the `LoadedWithDependencies` event in combination with `asset_server.load_asset` dependency tracking to support this pattern ```rust fn main() { App::new() .init_asset::<MyAssets>() .add_systems(Update, on_loaded(create_array_texture)) .run(); } #[derive(Asset, Clone)] struct MyAssets { #[dependency] picture_of_my_cat: Handle<Image>, #[dependency] picture_of_my_other_cat: Handle<Image>, } impl FromWorld for ArrayTexture { fn from_world(world: &mut World) -> Self { picture_of_my_cat: server.load("meow.png"), picture_of_my_other_cat: server.load("meeeeeeeow.png"), } } fn spawn_cat(In(my_assets): In<MyAssets>, mut commands: Commands) { commands.spawn(SpriteBundle { texture: my_assets.picture_of_my_cat.clone(), ..default() }); commands.spawn(SpriteBundle { texture: my_assets.picture_of_my_other_cat.clone(), ..default() }); } ``` The implementation is _very_ rough. And it is currently unsafe because `bevy_ecs` doesn't expose some internals to do this safely from inside `bevy_asset`. There are plenty of unanswered questions like: * "do we add a Loadable" derive? (effectively automate the FromWorld implementation above) * Should `MyAssets` even be an Asset? (largely implemented this way because it elegantly builds on `server.load_asset(MyAsset { .. })` dependency tracking). We should think hard about what our ideal API looks like (and if this is a pattern we want to support). Not necessarily something we need to solve in this PR. The current `on_loaded` impl should probably be removed from this PR before merging. ## Clarifying Questions ### What about Assets as Entities? This Bevy Asset V2 proposal implementation initially stored Assets as ECS Entities. Instead of `AssetId<T>` + the `Assets<T>` resource it used `Entity` as the asset id and Asset values were just ECS components. There are plenty of compelling reasons to do this: 1. Easier to inline assets in Bevy Scenes (as they are "just" normal entities + components) 2. More flexible queries: use the power of the ECS to filter assets (ex: `Query<Mesh, With<Tree>>`). 3. Extensible. Users can add arbitrary component data to assets. 4. Things like "component visualization tools" work out of the box to visualize asset data. However Assets as Entities has a ton of caveats right now: * We need to be able to allocate entity ids without a direct World reference (aka rework id allocator in Entities ... i worked around this in my prototypes by just pre allocating big chunks of entities) * We want asset change events in addition to ECS change tracking ... how do we populate them when mutations can come from anywhere? Do we use Changed queries? This would require iterating over the change data for all assets every frame. Is this acceptable or should we implement a new "event based" component change detection option? * Reconciling manually created assets with asset-system managed assets has some nuance (ex: are they "loaded" / do they also have that component metadata?) * "how do we handle "static" / default entity handles" (ties in to the Entity Indices discussion: https://github.com/bevyengine/bevy/discussions/8319). This is necessary for things like "built in" assets and default handles in things like SpriteBundle. * Storing asset information as a component makes it easy to "invalidate" asset state by removing the component (or forcing modifications). Ideally we have ways to lock this down (some combination of Rust type privacy and ECS validation) In practice, how we store and identify assets is a reasonably superficial change (porting off of Assets as Entities and implementing dedicated storage + ids took less than a day). So once we sort out the remaining challenges the flip should be straightforward. Additionally, I do still have "Assets as Entities" in my commit history, so we can reuse that work. I personally think "assets as entities" is a good endgame, but it also doesn't provide _significant_ value at the moment and it certainly isn't ready yet with the current state of things. ### Why not Distill? [Distill](https://github.com/amethyst/distill) is a high quality fully featured asset system built in Rust. It is very natural to ask "why not just use Distill?". It is also worth calling out that for awhile, [we planned on adopting Distill / I signed off on it](https://github.com/bevyengine/bevy/issues/708). However I think Bevy has a number of constraints that make Distill adoption suboptimal: * **Architectural Simplicity:** * Distill's processor requires an in-memory database (lmdb) and RPC networked API (using Cap'n Proto). Each of these introduces API complexity that increases maintenance burden and "code grokability". Ignoring tests, documentation, and examples, Distill has 24,237 lines of Rust code (including generated code for RPC + database interactions). If you ignore generated code, it has 11,499 lines. * Bevy builds the AssetProcessor and AssetServer using pluggable AssetReader/AssetWriter Rust traits with simple io interfaces. They do not necessitate databases or RPC interfaces (although Readers/Writers could use them if that is desired). Bevy Asset V2 (at the time of writing this PR) is 5,384 lines of Rust code (ignoring tests, documentation, and examples). Grain of salt: Distill does have more features currently (ex: Asset Packing, GUIDS, remote-out-of-process asset processor). I do plan to implement these features in Bevy Asset V2 and I personally highly doubt they will meaningfully close the 6115 lines-of-code gap. * This complexity gap (which while illustrated by lines of code, is much bigger than just that) is noteworthy to me. Bevy should be hackable and there are pillars of Distill that are very hard to understand and extend. This is a matter of opinion (and Bevy Asset V2 also has complicated areas), but I think Bevy Asset V2 is much more approachable for the average developer. * Necessary disclaimer: counting lines of code is an extremely rough complexity metric. Read the code and form your own opinions. * **Optional Asset Processing:** Not all Bevy Apps (or Bevy App developers) need / want asset preprocessing. Processing increases the complexity of the development environment by introducing things like meta files, imported asset storage, running processors in the background, waiting for processing to finish, etc. Distill _requires_ preprocessing to work. With Bevy Asset V2 processing is fully opt-in. The AssetServer isn't directly aware of asset processors at all. AssetLoaders only care about converting bytes to runtime Assets ... they don't know or care if the bytes were pre-processed or not. Processing is "elegantly" (forgive my self-congratulatory phrasing) layered on top and builds on the existing Asset system primitives. * **Direct Filesystem Access to Processed Asset State:** Distill stores processed assets in a database. This makes debugging / inspecting the processed outputs harder (either requires special tooling to query the database or they need to be "deployed" to be inspected). Bevy Asset V2, on the other hand, stores processed assets in the filesystem (by default ... this is configurable). This makes interacting with the processed state more natural. Note that both Godot and Unity's new asset system store processed assets in the filesystem. * **Portability**: Because Distill's processor uses lmdb and RPC networking, it cannot be run on certain platforms (ex: lmdb is a non-rust dependency that cannot run on the web, some platforms don't support running network servers). Bevy should be able to process assets everywhere (ex: run the Bevy Editor on the web, compile + process shaders on mobile, etc). Distill does partially mitigate this problem by supporting "streaming" assets via the RPC protocol, but this is not a full solve from my perspective. And Bevy Asset V2 can (in theory) also stream assets (without requiring RPC, although this isn't implemented yet) Note that I _do_ still think Distill would be a solid asset system for Bevy. But I think the approach in this PR is a better solve for Bevy's specific "asset system requirements". ### Doesn't async-fs just shim requests to "sync" `std::fs`? What is the point? "True async file io" has limited / spotty platform support. async-fs (and the rust async ecosystem generally ... ex Tokio) currently use async wrappers over std::fs that offload blocking requests to separate threads. This may feel unsatisfying, but it _does_ still provide value because it prevents our task pools from blocking on file system operations (which would prevent progress when there are many tasks to do, but all threads in a pool are currently blocking on file system ops). Additionally, using async APIs for our AssetReaders and AssetWriters also provides value because we can later add support for "true async file io" for platforms that support it. _And_ we can implement other "true async io" asset backends (such as networked asset io). ## Draft TODO - [x] Fill in missing filesystem event APIs: file removed event (which is expressed as dangling RenameFrom events in some cases), file/folder renamed event - [x] Assets without loaders are not moved to the processed folder. This breaks things like referenced `.bin` files for GLTFs. This should be configurable per-non-asset-type. - [x] Initial implementation of Reflect and FromReflect for Handle. The "deserialization" parity bar is low here as this only worked with static UUIDs in the old impl ... this is a non-trivial problem. Either we add a Handle::AssetPath variant that gets "upgraded" to a strong handle on scene load or we use a separate AssetRef type for Bevy scenes (which is converted to a runtime Handle on load). This deserves its own discussion in a different pr. - [x] Populate read_asset_bytes hash when run by the processor (a bit of a special case .. when run by the processor the processed meta will contain the hash so we don't need to compute it on the spot, but we don't want/need to read the meta when run by the main AssetServer) - [x] Delay hot reloading: currently filesystem events are handled immediately, which creates timing issues in some cases. For example hot reloading images can sometimes break because the image isn't finished writing. We should add a delay, likely similar to the [implementation in this PR](https://github.com/bevyengine/bevy/pull/8503). - [x] Port old platform-specific AssetIo implementations to the new AssetReader interface (currently missing Android and web) - [x] Resolve on_loaded unsafety (either by removing the API entirely or removing the unsafe) - [x] Runtime loader setting overrides - [x] Remove remaining unwraps that should be error-handled. There are number of TODOs here - [x] Pretty AssetPath Display impl - [x] Document more APIs - [x] Resolve spurious "reloading because it has changed" events (to repro run load_gltf with `processed_dev()`) - [x] load_dependency hot reloading currently only works for processed assets. If processing is disabled, load_dependency changes are not hot reloaded. - [x] Replace AssetInfo dependency load/fail counters with `loading_dependencies: HashSet<UntypedAssetId>` to prevent reloads from (potentially) breaking counters. Storing this will also enable "dependency reloaded" events (see [Next Steps](#next-steps)) - [x] Re-add filesystem watcher cargo feature gate (currently it is not optional) - [ ] Migration Guide - [ ] Changelog ## Followup TODO - [ ] Replace "eager unchanged processed asset loading" behavior with "don't returned unchanged processed asset until dependencies have been checked". - [ ] Add true `Ignore` AssetAction that does not copy the asset to the imported_assets folder. - [ ] Finish "live asset unloading" (ex: free up CPU asset memory after uploading an image to the GPU), rethink RenderAssets, and port renderer features. The `Assets` collection uses `Option<T>` for asset storage to support its removal. (1) the Option might not actually be necessary ... might be able to just remove from the collection entirely (2) need to finalize removal apis - [ ] Try replacing the "channel based" asset id recycling with something a bit more efficient (ex: we might be able to use raw atomic ints with some cleverness) - [ ] Consider adding UUIDs to processed assets (scoped just to helping identify moved assets ... not exposed to load queries ... see [Next Steps](#next-steps)) - [ ] Store "last modified" source asset and meta timestamps in processed meta files to enable skipping expensive hashing when the file wasn't changed - [ ] Fix "slow loop" handle drop fix - [ ] Migrate to TypeName - [x] Handle "loader preregistration". See #9429 ## Next Steps * **Configurable per-type defaults for AssetMeta**: It should be possible to add configuration like "all png image meta should default to using nearest sampling" (currently this hard-coded per-loader/processor Settings::default() impls). Also see the "Folder Meta" bullet point. * **Avoid Reprocessing on Asset Renames / Moves**: See the "canonical asset ids" discussion in [Open Questions](#open-questions) and the relevant bullet point in [Draft TODO](#draft-todo). Even without canonical ids, folder renames could avoid reprocessing in some cases. * **Multiple Asset Sources**: Expand AssetPath to support "asset source names" and support multiple AssetReaders in the asset server (ex: `webserver://some_path/image.png` backed by an Http webserver AssetReader). The "default" asset reader would use normal `some_path/image.png` paths. Ideally this works in combination with multiple AssetWatchers for hot-reloading * **Stable Type Names**: this pr removes the TypeUuid requirement from assets in favor of `std::any::type_name`. This makes defining assets easier (no need to generate a new uuid / use weird proc macro syntax). It also makes reading meta files easier (because things have "friendly names"). We also use type names for components in scene files. If they are good enough for components, they are good enough for assets. And consistency across Bevy pillars is desirable. However, `std::any::type_name` is not guaranteed to be stable (although in practice it is). We've developed a [stable type path](https://github.com/bevyengine/bevy/pull/7184) to resolve this, which should be adopted when it is ready. * **Command Line Interface**: It should be possible to run the asset processor in a separate process from the command line. This will also require building a network-server-backed AssetReader to communicate between the app and the processor. We've been planning to build a "bevy cli" for awhile. This seems like a good excuse to build it. * **Asset Packing**: This is largely an additive feature, so it made sense to me to punt this until we've laid the foundations in this PR. * **Per-Platform Processed Assets**: It should be possible to generate assets for multiple platforms by supporting multiple "processor profiles" per asset (ex: compress with format X on PC and Y on iOS). I think there should probably be arbitrary "profiles" (which can be separate from actual platforms), which are then assigned to a given platform when generating the final asset distribution for that platform. Ex: maybe devs want a "Mobile" profile that is shared between iOS and Android. Or a "LowEnd" profile shared between web and mobile. * **Versioning and Migrations**: Assets, Loaders, Savers, and Processors need to have versions to determine if their schema is valid. If an asset / loader version is incompatible with the current version expected at runtime, the processor should be able to migrate them. I think we should try using Bevy Reflect for this, as it would allow us to load the old version as a dynamic Reflect type without actually having the old Rust type. It would also allow us to define "patches" to migrate between versions (Bevy Reflect devs are currently working on patching). The `.meta` file already has its own format version. Migrating that to new versions should also be possible. * **Real Copy-on-write AssetPaths**: Rust's actual Cow (clone-on-write type) currently used by AssetPath can still result in String clones that aren't actually necessary (cloning an Owned Cow clones the contents). Bevy's asset system requires cloning AssetPaths in a number of places, which result in actual clones of the internal Strings. This is not efficient. AssetPath internals should be reworked to exhibit truer cow-like-behavior that reduces String clones to the absolute minimum. * **Consider processor-less processing**: In theory the AssetServer could run processors "inline" even if the background AssetProcessor is disabled. If we decide this is actually desirable, we could add this. But I don't think its a priority in the short or medium term. * **Pre-emptive dependency loading**: We could encode dependencies in processed meta files, which could then be used by the Asset Server to kick of dependency loads as early as possible (prior to starting the actual asset load). Is this desirable? How much time would this save in practice? * **Optimize Processor With UntypedAssetIds**: The processor exclusively uses AssetPath to identify assets currently. It might be possible to swap these out for UntypedAssetIds in some places, which are smaller / cheaper to hash and compare. * **One to Many Asset Processing**: An asset source file that produces many assets currently must be processed into a single "processed" asset source. If labeled assets can be written separately they can each have their own configured savers _and_ they could be loaded more granularly. Definitely worth exploring! * **Automatically Track "Runtime-only" Asset Dependencies**: Right now, tracking "created at runtime" asset dependencies requires adding them via `asset_server.load_asset(StandardMaterial::default())`. I think with some cleverness we could also do this for `materials.add(StandardMaterial::default())`, making tracking work "everywhere". There are challenges here relating to change detection / ensuring the server is made aware of dependency changes. This could be expensive in some cases. * **"Dependency Changed" events**: Some assets have runtime artifacts that need to be re-generated when one of their dependencies change (ex: regenerate a material's bind group when a Texture needs to change). We are generating the dependency graph so we can definitely produce these events. Buuuuut generating these events will have a cost / they could be high frequency for some assets, so we might want this to be opt-in for specific cases. * **Investigate Storing More Information In Handles**: Handles can now store arbitrary information, which makes it cheaper and easier to access. How much should we move into them? Canonical asset load states (via atomics)? (`handle.is_loaded()` would be very cool). Should we store the entire asset and remove the `Assets<T>` collection? (`Arc<RwLock<Option<Image>>>`?) * **Support processing and loading files without extensions**: This is a pretty arbitrary restriction and could be supported with very minimal changes. * **Folder Meta**: It would be nice if we could define per folder processor configuration defaults (likely in a `.meta` or `.folder_meta` file). Things like "default to linear filtering for all Images in this folder". * **Replace async_broadcast with event-listener?** This might be approximately drop-in for some uses and it feels more light weight * **Support Running the AssetProcessor on the Web**: Most of the hard work is done here, but there are some easy straggling TODOs (make the transaction log an interface instead of a direct file writer so we can write a web storage backend, implement an AssetReader/AssetWriter that reads/writes to something like LocalStorage). * **Consider identifying and preventing circular dependencies**: This is especially important for "processor dependencies", as processing will silently never finish in these cases. * **Built-in/Inlined Asset Hot Reloading**: This PR regresses "built-in/inlined" asset hot reloading (previously provided by the DebugAssetServer). I'm intentionally punting this because I think it can be cleanly implemented with "multiple asset sources" by registering a "debug asset source" (ex: `debug://bevy_pbr/src/render/pbr.wgsl` asset paths) in combination with an AssetWatcher for that asset source and support for "manually loading pats with asset bytes instead of AssetReaders". The old DebugAssetServer was quite nasty and I'd love to avoid that hackery going forward. * **Investigate ways to remove double-parsing meta files**: Parsing meta files currently involves parsing once with "minimal" versions of the meta file to extract the type name of the loader/processor config, then parsing again to parse the "full" meta. This is suboptimal. We should be able to define custom deserializers that (1) assume the loader/processor type name comes first (2) dynamically looks up the loader/processor registrations to deserialize settings in-line (similar to components in the bevy scene format). Another alternative: deserialize as dynamic Reflect objects and then convert. * **More runtime loading configuration**: Support using the Handle type as a hint to select an asset loader (instead of relying on AssetPath extensions) * **More high level Processor trait implementations**: For example, it might be worth adding support for arbitrary chains of "asset transforms" that modify an in-memory asset representation between loading and saving. (ex: load a Mesh, run a `subdivide_mesh` transform, followed by a `flip_normals` transform, then save the mesh to an efficient compressed format). * **Bevy Scene Handle Deserialization**: (see the relevant [Draft TODO item](#draft-todo) for context) * **Explore High Level Load Interfaces**: See [this discussion](#discuss-on_loaded-high-level-interface) for one prototype. * **Asset Streaming**: It would be great if we could stream Assets (ex: stream a long video file piece by piece) * **ID Exchanging**: In this PR Asset Handles/AssetIds are bigger than they need to be because they have a Uuid enum variant. If we implement an "id exchanging" system that trades Uuids for "efficient runtime ids", we can cut down on the size of AssetIds, making them more efficient. This has some open design questions, such as how to spawn entities with "default" handle values (as these wouldn't have access to the exchange api in the current system). * **Asset Path Fixup Tooling**: Assets that inline asset paths inside them will break when an asset moves. The asset system provides the functionality to detect when paths break. We should build a framework that enables formats to define "path migrations". This is especially important for scene files. For editor-generated files, we should also consider using UUIDs (see other bullet point) to avoid the need to migrate in these cases. --------- Co-authored-by: BeastLe9enD <beastle9end@outlook.de> Co-authored-by: Mike <mike.hsu@gmail.com> Co-authored-by: Nicola Papale <nicopap@users.noreply.github.com>
2023-09-07 02:07:27 +00:00
[[example]]
name = "asset_processing"
Reduce noise in asset processing example (#10262) # Objective - Reduce noise to allow users to see previous asset changes and other logs like from asset reloading - The example file is named differently than the example ## Solution - Only print the asset content if there are asset events - Rename the example file to `asset_processing`
2023-10-25 19:37:03 +00:00
path = "examples/asset/processing/asset_processing.rs"
Bevy Asset V2 (#8624) # Bevy Asset V2 Proposal ## Why Does Bevy Need A New Asset System? Asset pipelines are a central part of the gamedev process. Bevy's current asset system is missing a number of features that make it non-viable for many classes of gamedev. After plenty of discussions and [a long community feedback period](https://github.com/bevyengine/bevy/discussions/3972), we've identified a number missing features: * **Asset Preprocessing**: it should be possible to "preprocess" / "compile" / "crunch" assets at "development time" rather than when the game starts up. This enables offloading expensive work from deployed apps, faster asset loading, less runtime memory usage, etc. * **Per-Asset Loader Settings**: Individual assets cannot define their own loaders that override the defaults. Additionally, they cannot provide per-asset settings to their loaders. This is a huge limitation, as many asset types don't provide all information necessary for Bevy _inside_ the asset. For example, a raw PNG image says nothing about how it should be sampled (ex: linear vs nearest). * **Asset `.meta` files**: assets should have configuration files stored adjacent to the asset in question, which allows the user to configure asset-type-specific settings. These settings should be accessible during the pre-processing phase. Modifying a `.meta` file should trigger a re-processing / re-load of the asset. It should be possible to configure asset loaders from the meta file. * **Processed Asset Hot Reloading**: Changes to processed assets (or their dependencies) should result in re-processing them and re-loading the results in live Bevy Apps. * **Asset Dependency Tracking**: The current bevy_asset has no good way to wait for asset dependencies to load. It punts this as an exercise for consumers of the loader apis, which is unreasonable and error prone. There should be easy, ergonomic ways to wait for assets to load and block some logic on an asset's entire dependency tree loading. * **Runtime Asset Loading**: it should be (optionally) possible to load arbitrary assets dynamically at runtime. This necessitates being able to deploy and run the asset server alongside Bevy Apps on _all platforms_. For example, we should be able to invoke the shader compiler at runtime, stream scenes from sources like the internet, etc. To keep deployed binaries (and startup times) small, the runtime asset server configuration should be configurable with different settings compared to the "pre processor asset server". * **Multiple Backends**: It should be possible to load assets from arbitrary sources (filesystems, the internet, remote asset serves, etc). * **Asset Packing**: It should be possible to deploy assets in compressed "packs", which makes it easier and more efficient to distribute assets with Bevy Apps. * **Asset Handoff**: It should be possible to hold a "live" asset handle, which correlates to runtime data, without actually holding the asset in memory. Ex: it must be possible to hold a reference to a GPU mesh generated from a "mesh asset" without keeping the mesh data in CPU memory * **Per-Platform Processed Assets**: Different platforms and app distributions have different capabilities and requirements. Some platforms need lower asset resolutions or different asset formats to operate within the hardware constraints of the platform. It should be possible to define per-platform asset processing profiles. And it should be possible to deploy only the assets required for a given platform. These features have architectural implications that are significant enough to require a full rewrite. The current Bevy Asset implementation got us this far, but it can take us no farther. This PR defines a brand new asset system that implements most of these features, while laying the foundations for the remaining features to be built. ## Bevy Asset V2 Here is a quick overview of the features introduced in this PR. * **Asset Preprocessing**: Preprocess assets at development time into more efficient (and configurable) representations * **Dependency Aware**: Dependencies required to process an asset are tracked. If an asset's processed dependency changes, it will be reprocessed * **Hot Reprocessing/Reloading**: detect changes to asset source files, reprocess them if they have changed, and then hot-reload them in Bevy Apps. * **Only Process Changes**: Assets are only re-processed when their source file (or meta file) has changed. This uses hashing and timestamps to avoid processing assets that haven't changed. * **Transactional and Reliable**: Uses write-ahead logging (a technique commonly used by databases) to recover from crashes / forced-exits. Whenever possible it avoids full-reprocessing / only uncompleted transactions will be reprocessed. When the processor is running in parallel with a Bevy App, processor asset writes block Bevy App asset reads. Reading metadata + asset bytes is guaranteed to be transactional / correctly paired. * **Portable / Run anywhere / Database-free**: The processor does not rely on an in-memory database (although it uses some database techniques for reliability). This is important because pretty much all in-memory databases have unsupported platforms or build complications. * **Configure Processor Defaults Per File Type**: You can say "use this processor for all files of this type". * **Custom Processors**: The `Processor` trait is flexible and unopinionated. It can be implemented by downstream plugins. * **LoadAndSave Processors**: Most asset processing scenarios can be expressed as "run AssetLoader A, save the results using AssetSaver X, and then load the result using AssetLoader B". For example, load this png image using `PngImageLoader`, which produces an `Image` asset and then save it using `CompressedImageSaver` (which also produces an `Image` asset, but in a compressed format), which takes an `Image` asset as input. This means if you have an `AssetLoader` for an asset, you are already half way there! It also means that you can share AssetSavers across multiple loaders. Because `CompressedImageSaver` accepts Bevy's generic Image asset as input, it means you can also use it with some future `JpegImageLoader`. * **Loader and Saver Settings**: Asset Loaders and Savers can now define their own settings types, which are passed in as input when an asset is loaded / saved. Each asset can define its own settings. * **Asset `.meta` files**: configure asset loaders, their settings, enable/disable processing, and configure processor settings * **Runtime Asset Dependency Tracking** Runtime asset dependencies (ex: if an asset contains a `Handle<Image>`) are tracked by the asset server. An event is emitted when an asset and all of its dependencies have been loaded * **Unprocessed Asset Loading**: Assets do not require preprocessing. They can be loaded directly. A processed asset is just a "normal" asset with some extra metadata. Asset Loaders don't need to know or care about whether or not an asset was processed. * **Async Asset IO**: Asset readers/writers use async non-blocking interfaces. Note that because Rust doesn't yet support async traits, there is a bit of manual Boxing / Future boilerplate. This will hopefully be removed in the near future when Rust gets async traits. * **Pluggable Asset Readers and Writers**: Arbitrary asset source readers/writers are supported, both by the processor and the asset server. * **Better Asset Handles** * **Single Arc Tree**: Asset Handles now use a single arc tree that represents the lifetime of the asset. This makes their implementation simpler, more efficient, and allows us to cheaply attach metadata to handles. Ex: the AssetPath of a handle is now directly accessible on the handle itself! * **Const Typed Handles**: typed handles can be constructed in a const context. No more weird "const untyped converted to typed at runtime" patterns! * **Handles and Ids are Smaller / Faster To Hash / Compare**: Typed `Handle<T>` is now much smaller in memory and `AssetId<T>` is even smaller. * **Weak Handle Usage Reduction**: In general Handles are now considered to be "strong". Bevy features that previously used "weak `Handle<T>`" have been ported to `AssetId<T>`, which makes it statically clear that the features do not hold strong handles (while retaining strong type information). Currently Handle::Weak still exists, but it is very possible that we can remove that entirely. * **Efficient / Dense Asset Ids**: Assets now have efficient dense runtime asset ids, which means we can avoid expensive hash lookups. Assets are stored in Vecs instead of HashMaps. There are now typed and untyped ids, which means we no longer need to store dynamic type information in the ID for typed handles. "AssetPathId" (which was a nightmare from a performance and correctness standpoint) has been entirely removed in favor of dense ids (which are retrieved for a path on load) * **Direct Asset Loading, with Dependency Tracking**: Assets that are defined at runtime can still have their dependencies tracked by the Asset Server (ex: if you create a material at runtime, you can still wait for its textures to load). This is accomplished via the (currently optional) "asset dependency visitor" trait. This system can also be used to define a set of assets to load, then wait for those assets to load. * **Async folder loading**: Folder loading also uses this system and immediately returns a handle to the LoadedFolder asset, which means folder loading no longer blocks on directory traversals. * **Improved Loader Interface**: Loaders now have a specific "top level asset type", which makes returning the top-level asset simpler and statically typed. * **Basic Image Settings and Processing**: Image assets can now be processed into the gpu-friendly Basic Universal format. The ImageLoader now has a setting to define what format the image should be loaded as. Note that this is just a minimal MVP ... plenty of additional work to do here. To demo this, enable the `basis-universal` feature and turn on asset processing. * **Simpler Audio Play / AudioSink API**: Asset handle providers are cloneable, which means the Audio resource can mint its own handles. This means you can now do `let sink_handle = audio.play(music)` instead of `let sink_handle = audio_sinks.get_handle(audio.play(music))`. Note that this might still be replaced by https://github.com/bevyengine/bevy/pull/8424. **Removed Handle Casting From Engine Features**: Ex: FontAtlases no longer use casting between handle types ## Using The New Asset System ### Normal Unprocessed Asset Loading By default the `AssetPlugin` does not use processing. It behaves pretty much the same way as the old system. If you are defining a custom asset, first derive `Asset`: ```rust #[derive(Asset)] struct Thing { value: String, } ``` Initialize the asset: ```rust app.init_asset:<Thing>() ``` Implement a new `AssetLoader` for it: ```rust #[derive(Default)] struct ThingLoader; #[derive(Serialize, Deserialize, Default)] pub struct ThingSettings { some_setting: bool, } impl AssetLoader for ThingLoader { type Asset = Thing; type Settings = ThingSettings; fn load<'a>( &'a self, reader: &'a mut Reader, settings: &'a ThingSettings, load_context: &'a mut LoadContext, ) -> BoxedFuture<'a, Result<Thing, anyhow::Error>> { Box::pin(async move { let mut bytes = Vec::new(); reader.read_to_end(&mut bytes).await?; // convert bytes to value somehow Ok(Thing { value }) }) } fn extensions(&self) -> &[&str] { &["thing"] } } ``` Note that this interface will get much cleaner once Rust gets support for async traits. `Reader` is an async futures_io::AsyncRead. You can stream bytes as they come in or read them all into a `Vec<u8>`, depending on the context. You can use `let handle = load_context.load(path)` to kick off a dependency load, retrieve a handle, and register the dependency for the asset. Then just register the loader in your Bevy app: ```rust app.init_asset_loader::<ThingLoader>() ``` Now just add your `Thing` asset files into the `assets` folder and load them like this: ```rust fn system(asset_server: Res<AssetServer>) { let handle = Handle<Thing> = asset_server.load("cool.thing"); } ``` You can check load states directly via the asset server: ```rust if asset_server.load_state(&handle) == LoadState::Loaded { } ``` You can also listen for events: ```rust fn system(mut events: EventReader<AssetEvent<Thing>>, handle: Res<SomeThingHandle>) { for event in events.iter() { if event.is_loaded_with_dependencies(&handle) { } } } ``` Note the new `AssetEvent::LoadedWithDependencies`, which only fires when the asset is loaded _and_ all dependencies (and their dependencies) have loaded. Unlike the old asset system, for a given asset path all `Handle<T>` values point to the same underlying Arc. This means Handles can cheaply hold more asset information, such as the AssetPath: ```rust // prints the AssetPath of the handle info!("{:?}", handle.path()) ``` ### Processed Assets Asset processing can be enabled via the `AssetPlugin`. When developing Bevy Apps with processed assets, do this: ```rust app.add_plugins(DefaultPlugins.set(AssetPlugin::processed_dev())) ``` This runs the `AssetProcessor` in the background with hot-reloading. It reads assets from the `assets` folder, processes them, and writes them to the `.imported_assets` folder. Asset loads in the Bevy App will wait for a processed version of the asset to become available. If an asset in the `assets` folder changes, it will be reprocessed and hot-reloaded in the Bevy App. When deploying processed Bevy apps, do this: ```rust app.add_plugins(DefaultPlugins.set(AssetPlugin::processed())) ``` This does not run the `AssetProcessor` in the background. It behaves like `AssetPlugin::unprocessed()`, but reads assets from `.imported_assets`. When the `AssetProcessor` is running, it will populate sibling `.meta` files for assets in the `assets` folder. Meta files for assets that do not have a processor configured look like this: ```rust ( meta_format_version: "1.0", asset: Load( loader: "bevy_render::texture::image_loader::ImageLoader", settings: ( format: FromExtension, ), ), ) ``` This is metadata for an image asset. For example, if you have `assets/my_sprite.png`, this could be the metadata stored at `assets/my_sprite.png.meta`. Meta files are totally optional. If no metadata exists, the default settings will be used. In short, this file says "load this asset with the ImageLoader and use the file extension to determine the image type". This type of meta file is supported in all AssetPlugin modes. If in `Unprocessed` mode, the asset (with the meta settings) will be loaded directly. If in `ProcessedDev` mode, the asset file will be copied directly to the `.imported_assets` folder. The meta will also be copied directly to the `.imported_assets` folder, but with one addition: ```rust ( meta_format_version: "1.0", processed_info: Some(( hash: 12415480888597742505, full_hash: 14344495437905856884, process_dependencies: [], )), asset: Load( loader: "bevy_render::texture::image_loader::ImageLoader", settings: ( format: FromExtension, ), ), ) ``` `processed_info` contains `hash` (a direct hash of the asset and meta bytes), `full_hash` (a hash of `hash` and the hashes of all `process_dependencies`), and `process_dependencies` (the `path` and `full_hash` of every process_dependency). A "process dependency" is an asset dependency that is _directly_ used when processing the asset. Images do not have process dependencies, so this is empty. When the processor is enabled, you can use the `Process` metadata config: ```rust ( meta_format_version: "1.0", asset: Process( processor: "bevy_asset::processor::process::LoadAndSave<bevy_render::texture::image_loader::ImageLoader, bevy_render::texture::compressed_image_saver::CompressedImageSaver>", settings: ( loader_settings: ( format: FromExtension, ), saver_settings: ( generate_mipmaps: true, ), ), ), ) ``` This configures the asset to use the `LoadAndSave` processor, which runs an AssetLoader and feeds the result into an AssetSaver (which saves the given Asset and defines a loader to load it with). (for terseness LoadAndSave will likely get a shorter/friendlier type name when [Stable Type Paths](#7184) lands). `LoadAndSave` is likely to be the most common processor type, but arbitrary processors are supported. `CompressedImageSaver` saves an `Image` in the Basis Universal format and configures the ImageLoader to load it as basis universal. The `AssetProcessor` will read this meta, run it through the LoadAndSave processor, and write the basis-universal version of the image to `.imported_assets`. The final metadata will look like this: ```rust ( meta_format_version: "1.0", processed_info: Some(( hash: 905599590923828066, full_hash: 9948823010183819117, process_dependencies: [], )), asset: Load( loader: "bevy_render::texture::image_loader::ImageLoader", settings: ( format: Format(Basis), ), ), ) ``` To try basis-universal processing out in Bevy examples, (for example `sprite.rs`), change `add_plugins(DefaultPlugins)` to `add_plugins(DefaultPlugins.set(AssetPlugin::processed_dev()))` and run with the `basis-universal` feature enabled: `cargo run --features=basis-universal --example sprite`. To create a custom processor, there are two main paths: 1. Use the `LoadAndSave` processor with an existing `AssetLoader`. Implement the `AssetSaver` trait, register the processor using `asset_processor.register_processor::<LoadAndSave<ImageLoader, CompressedImageSaver>>(image_saver.into())`. 2. Implement the `Process` trait directly and register it using: `asset_processor.register_processor(thing_processor)`. You can configure default processors for file extensions like this: ```rust asset_processor.set_default_processor::<ThingProcessor>("thing") ``` There is one more metadata type to be aware of: ```rust ( meta_format_version: "1.0", asset: Ignore, ) ``` This will ignore the asset during processing / prevent it from being written to `.imported_assets`. The AssetProcessor stores a transaction log at `.imported_assets/log` and uses it to gracefully recover from unexpected stops. This means you can force-quit the processor (and Bevy Apps running the processor in parallel) at arbitrary times! `.imported_assets` is "local state". It should _not_ be checked into source control. It should also be considered "read only". In practice, you _can_ modify processed assets and processed metadata if you really need to test something. But those modifications will not be represented in the hashes of the assets, so the processed state will be "out of sync" with the source assets. The processor _will not_ fix this for you. Either revert the change after you have tested it, or delete the processed files so they can be re-populated. ## Open Questions There are a number of open questions to be discussed. We should decide if they need to be addressed in this PR and if so, how we will address them: ### Implied Dependencies vs Dependency Enumeration There are currently two ways to populate asset dependencies: * **Implied via AssetLoaders**: if an AssetLoader loads an asset (and retrieves a handle), a dependency is added to the list. * **Explicit via the optional Asset::visit_dependencies**: if `server.load_asset(my_asset)` is called, it will call `my_asset.visit_dependencies`, which will grab dependencies that have been manually defined for the asset via the Asset trait impl (which can be derived). This means that defining explicit dependencies is optional for "loaded assets". And the list of dependencies is always accurate because loaders can only produce Handles if they register dependencies. If an asset was loaded with an AssetLoader, it only uses the implied dependencies. If an asset was created at runtime and added with `asset_server.load_asset(MyAsset)`, it will use `Asset::visit_dependencies`. However this can create a behavior mismatch between loaded assets and equivalent "created at runtime" assets if `Assets::visit_dependencies` doesn't exactly match the dependencies produced by the AssetLoader. This behavior mismatch can be resolved by completely removing "implied loader dependencies" and requiring `Asset::visit_dependencies` to supply dependency data. But this creates two problems: * It makes defining loaded assets harder and more error prone: Devs must remember to manually annotate asset dependencies with `#[dependency]` when deriving `Asset`. For more complicated assets (such as scenes), the derive likely wouldn't be sufficient and a manual `visit_dependencies` impl would be required. * Removes the ability to immediately kick off dependency loads: When AssetLoaders retrieve a Handle, they also immediately kick off an asset load for the handle, which means it can start loading in parallel _before_ the asset finishes loading. For large assets, this could be significant. (although this could be mitigated for processed assets if we store dependencies in the processed meta file and load them ahead of time) ### Eager ProcessorDev Asset Loading I made a controversial call in the interest of fast startup times ("time to first pixel") for the "processor dev mode configuration". When initializing the AssetProcessor, current processed versions of unchanged assets are yielded immediately, even if their dependencies haven't been checked yet for reprocessing. This means that non-current-state-of-filesystem-but-previously-valid assets might be returned to the App first, then hot-reloaded if/when their dependencies change and the asset is reprocessed. Is this behavior desirable? There is largely one alternative: do not yield an asset from the processor to the app until all of its dependencies have been checked for changes. In some common cases (load dependency has not changed since last run) this will increase startup time. The main question is "by how much" and is that slower startup time worth it in the interest of only yielding assets that are true to the current state of the filesystem. Should this be configurable? I'm starting to think we should only yield an asset after its (historical) dependencies have been checked for changes + processed as necessary, but I'm curious what you all think. ### Paths Are Currently The Only Canonical ID / Do We Want Asset UUIDs? In this implementation AssetPaths are the only canonical asset identifier (just like the previous Bevy Asset system and Godot). Moving assets will result in re-scans (and currently reprocessing, although reprocessing can easily be avoided with some changes). Asset renames/moves will break code and assets that rely on specific paths, unless those paths are fixed up. Do we want / need "stable asset uuids"? Introducing them is very possible: 1. Generate a UUID and include it in .meta files 2. Support UUID in AssetPath 3. Generate "asset indices" which are loaded on startup and map UUIDs to paths. 4 (maybe). Consider only supporting UUIDs for processed assets so we can generate quick-to-load indices instead of scanning meta files. The main "pro" is that assets referencing UUIDs don't need to be migrated when a path changes. The main "con" is that UUIDs cannot be "lazily resolved" like paths. They need a full view of all assets to answer the question "does this UUID exist". Which means UUIDs require the AssetProcessor to fully finish startup scans before saying an asset doesnt exist. And they essentially require asset pre-processing to use in apps, because scanning all asset metadata files at runtime to resolve a UUID is not viable for medium-to-large apps. It really requires a pre-generated UUID index, which must be loaded before querying for assets. I personally think this should be investigated in a separate PR. Paths aren't going anywhere ... _everyone_ uses filesystems (and filesystem-like apis) to manage their asset source files. I consider them permanent canonical asset information. Additionally, they behave well for both processed and unprocessed asset modes. Given that Bevy is supporting both, this feels like the right canonical ID to start with. UUIDS (and maybe even other indexed-identifier types) can be added later as necessary. ### Folder / File Naming Conventions All asset processing config currently lives in the `.imported_assets` folder. The processor transaction log is in `.imported_assets/log`. Processed assets are added to `.imported_assets/Default`, which will make migrating to processed asset profiles (ex: a `.imported_assets/Mobile` profile) a non-breaking change. It also allows us to create top-level files like `.imported_assets/log` without it being interpreted as an asset. Meta files currently have a `.meta` suffix. Do we like these names and conventions? ### Should the `AssetPlugin::processed_dev` configuration enable `watch_for_changes` automatically? Currently it does (which I think makes sense), but it does make it the only configuration that enables watch_for_changes by default. ### Discuss on_loaded High Level Interface: This PR includes a very rough "proof of concept" `on_loaded` system adapter that uses the `LoadedWithDependencies` event in combination with `asset_server.load_asset` dependency tracking to support this pattern ```rust fn main() { App::new() .init_asset::<MyAssets>() .add_systems(Update, on_loaded(create_array_texture)) .run(); } #[derive(Asset, Clone)] struct MyAssets { #[dependency] picture_of_my_cat: Handle<Image>, #[dependency] picture_of_my_other_cat: Handle<Image>, } impl FromWorld for ArrayTexture { fn from_world(world: &mut World) -> Self { picture_of_my_cat: server.load("meow.png"), picture_of_my_other_cat: server.load("meeeeeeeow.png"), } } fn spawn_cat(In(my_assets): In<MyAssets>, mut commands: Commands) { commands.spawn(SpriteBundle { texture: my_assets.picture_of_my_cat.clone(), ..default() }); commands.spawn(SpriteBundle { texture: my_assets.picture_of_my_other_cat.clone(), ..default() }); } ``` The implementation is _very_ rough. And it is currently unsafe because `bevy_ecs` doesn't expose some internals to do this safely from inside `bevy_asset`. There are plenty of unanswered questions like: * "do we add a Loadable" derive? (effectively automate the FromWorld implementation above) * Should `MyAssets` even be an Asset? (largely implemented this way because it elegantly builds on `server.load_asset(MyAsset { .. })` dependency tracking). We should think hard about what our ideal API looks like (and if this is a pattern we want to support). Not necessarily something we need to solve in this PR. The current `on_loaded` impl should probably be removed from this PR before merging. ## Clarifying Questions ### What about Assets as Entities? This Bevy Asset V2 proposal implementation initially stored Assets as ECS Entities. Instead of `AssetId<T>` + the `Assets<T>` resource it used `Entity` as the asset id and Asset values were just ECS components. There are plenty of compelling reasons to do this: 1. Easier to inline assets in Bevy Scenes (as they are "just" normal entities + components) 2. More flexible queries: use the power of the ECS to filter assets (ex: `Query<Mesh, With<Tree>>`). 3. Extensible. Users can add arbitrary component data to assets. 4. Things like "component visualization tools" work out of the box to visualize asset data. However Assets as Entities has a ton of caveats right now: * We need to be able to allocate entity ids without a direct World reference (aka rework id allocator in Entities ... i worked around this in my prototypes by just pre allocating big chunks of entities) * We want asset change events in addition to ECS change tracking ... how do we populate them when mutations can come from anywhere? Do we use Changed queries? This would require iterating over the change data for all assets every frame. Is this acceptable or should we implement a new "event based" component change detection option? * Reconciling manually created assets with asset-system managed assets has some nuance (ex: are they "loaded" / do they also have that component metadata?) * "how do we handle "static" / default entity handles" (ties in to the Entity Indices discussion: https://github.com/bevyengine/bevy/discussions/8319). This is necessary for things like "built in" assets and default handles in things like SpriteBundle. * Storing asset information as a component makes it easy to "invalidate" asset state by removing the component (or forcing modifications). Ideally we have ways to lock this down (some combination of Rust type privacy and ECS validation) In practice, how we store and identify assets is a reasonably superficial change (porting off of Assets as Entities and implementing dedicated storage + ids took less than a day). So once we sort out the remaining challenges the flip should be straightforward. Additionally, I do still have "Assets as Entities" in my commit history, so we can reuse that work. I personally think "assets as entities" is a good endgame, but it also doesn't provide _significant_ value at the moment and it certainly isn't ready yet with the current state of things. ### Why not Distill? [Distill](https://github.com/amethyst/distill) is a high quality fully featured asset system built in Rust. It is very natural to ask "why not just use Distill?". It is also worth calling out that for awhile, [we planned on adopting Distill / I signed off on it](https://github.com/bevyengine/bevy/issues/708). However I think Bevy has a number of constraints that make Distill adoption suboptimal: * **Architectural Simplicity:** * Distill's processor requires an in-memory database (lmdb) and RPC networked API (using Cap'n Proto). Each of these introduces API complexity that increases maintenance burden and "code grokability". Ignoring tests, documentation, and examples, Distill has 24,237 lines of Rust code (including generated code for RPC + database interactions). If you ignore generated code, it has 11,499 lines. * Bevy builds the AssetProcessor and AssetServer using pluggable AssetReader/AssetWriter Rust traits with simple io interfaces. They do not necessitate databases or RPC interfaces (although Readers/Writers could use them if that is desired). Bevy Asset V2 (at the time of writing this PR) is 5,384 lines of Rust code (ignoring tests, documentation, and examples). Grain of salt: Distill does have more features currently (ex: Asset Packing, GUIDS, remote-out-of-process asset processor). I do plan to implement these features in Bevy Asset V2 and I personally highly doubt they will meaningfully close the 6115 lines-of-code gap. * This complexity gap (which while illustrated by lines of code, is much bigger than just that) is noteworthy to me. Bevy should be hackable and there are pillars of Distill that are very hard to understand and extend. This is a matter of opinion (and Bevy Asset V2 also has complicated areas), but I think Bevy Asset V2 is much more approachable for the average developer. * Necessary disclaimer: counting lines of code is an extremely rough complexity metric. Read the code and form your own opinions. * **Optional Asset Processing:** Not all Bevy Apps (or Bevy App developers) need / want asset preprocessing. Processing increases the complexity of the development environment by introducing things like meta files, imported asset storage, running processors in the background, waiting for processing to finish, etc. Distill _requires_ preprocessing to work. With Bevy Asset V2 processing is fully opt-in. The AssetServer isn't directly aware of asset processors at all. AssetLoaders only care about converting bytes to runtime Assets ... they don't know or care if the bytes were pre-processed or not. Processing is "elegantly" (forgive my self-congratulatory phrasing) layered on top and builds on the existing Asset system primitives. * **Direct Filesystem Access to Processed Asset State:** Distill stores processed assets in a database. This makes debugging / inspecting the processed outputs harder (either requires special tooling to query the database or they need to be "deployed" to be inspected). Bevy Asset V2, on the other hand, stores processed assets in the filesystem (by default ... this is configurable). This makes interacting with the processed state more natural. Note that both Godot and Unity's new asset system store processed assets in the filesystem. * **Portability**: Because Distill's processor uses lmdb and RPC networking, it cannot be run on certain platforms (ex: lmdb is a non-rust dependency that cannot run on the web, some platforms don't support running network servers). Bevy should be able to process assets everywhere (ex: run the Bevy Editor on the web, compile + process shaders on mobile, etc). Distill does partially mitigate this problem by supporting "streaming" assets via the RPC protocol, but this is not a full solve from my perspective. And Bevy Asset V2 can (in theory) also stream assets (without requiring RPC, although this isn't implemented yet) Note that I _do_ still think Distill would be a solid asset system for Bevy. But I think the approach in this PR is a better solve for Bevy's specific "asset system requirements". ### Doesn't async-fs just shim requests to "sync" `std::fs`? What is the point? "True async file io" has limited / spotty platform support. async-fs (and the rust async ecosystem generally ... ex Tokio) currently use async wrappers over std::fs that offload blocking requests to separate threads. This may feel unsatisfying, but it _does_ still provide value because it prevents our task pools from blocking on file system operations (which would prevent progress when there are many tasks to do, but all threads in a pool are currently blocking on file system ops). Additionally, using async APIs for our AssetReaders and AssetWriters also provides value because we can later add support for "true async file io" for platforms that support it. _And_ we can implement other "true async io" asset backends (such as networked asset io). ## Draft TODO - [x] Fill in missing filesystem event APIs: file removed event (which is expressed as dangling RenameFrom events in some cases), file/folder renamed event - [x] Assets without loaders are not moved to the processed folder. This breaks things like referenced `.bin` files for GLTFs. This should be configurable per-non-asset-type. - [x] Initial implementation of Reflect and FromReflect for Handle. The "deserialization" parity bar is low here as this only worked with static UUIDs in the old impl ... this is a non-trivial problem. Either we add a Handle::AssetPath variant that gets "upgraded" to a strong handle on scene load or we use a separate AssetRef type for Bevy scenes (which is converted to a runtime Handle on load). This deserves its own discussion in a different pr. - [x] Populate read_asset_bytes hash when run by the processor (a bit of a special case .. when run by the processor the processed meta will contain the hash so we don't need to compute it on the spot, but we don't want/need to read the meta when run by the main AssetServer) - [x] Delay hot reloading: currently filesystem events are handled immediately, which creates timing issues in some cases. For example hot reloading images can sometimes break because the image isn't finished writing. We should add a delay, likely similar to the [implementation in this PR](https://github.com/bevyengine/bevy/pull/8503). - [x] Port old platform-specific AssetIo implementations to the new AssetReader interface (currently missing Android and web) - [x] Resolve on_loaded unsafety (either by removing the API entirely or removing the unsafe) - [x] Runtime loader setting overrides - [x] Remove remaining unwraps that should be error-handled. There are number of TODOs here - [x] Pretty AssetPath Display impl - [x] Document more APIs - [x] Resolve spurious "reloading because it has changed" events (to repro run load_gltf with `processed_dev()`) - [x] load_dependency hot reloading currently only works for processed assets. If processing is disabled, load_dependency changes are not hot reloaded. - [x] Replace AssetInfo dependency load/fail counters with `loading_dependencies: HashSet<UntypedAssetId>` to prevent reloads from (potentially) breaking counters. Storing this will also enable "dependency reloaded" events (see [Next Steps](#next-steps)) - [x] Re-add filesystem watcher cargo feature gate (currently it is not optional) - [ ] Migration Guide - [ ] Changelog ## Followup TODO - [ ] Replace "eager unchanged processed asset loading" behavior with "don't returned unchanged processed asset until dependencies have been checked". - [ ] Add true `Ignore` AssetAction that does not copy the asset to the imported_assets folder. - [ ] Finish "live asset unloading" (ex: free up CPU asset memory after uploading an image to the GPU), rethink RenderAssets, and port renderer features. The `Assets` collection uses `Option<T>` for asset storage to support its removal. (1) the Option might not actually be necessary ... might be able to just remove from the collection entirely (2) need to finalize removal apis - [ ] Try replacing the "channel based" asset id recycling with something a bit more efficient (ex: we might be able to use raw atomic ints with some cleverness) - [ ] Consider adding UUIDs to processed assets (scoped just to helping identify moved assets ... not exposed to load queries ... see [Next Steps](#next-steps)) - [ ] Store "last modified" source asset and meta timestamps in processed meta files to enable skipping expensive hashing when the file wasn't changed - [ ] Fix "slow loop" handle drop fix - [ ] Migrate to TypeName - [x] Handle "loader preregistration". See #9429 ## Next Steps * **Configurable per-type defaults for AssetMeta**: It should be possible to add configuration like "all png image meta should default to using nearest sampling" (currently this hard-coded per-loader/processor Settings::default() impls). Also see the "Folder Meta" bullet point. * **Avoid Reprocessing on Asset Renames / Moves**: See the "canonical asset ids" discussion in [Open Questions](#open-questions) and the relevant bullet point in [Draft TODO](#draft-todo). Even without canonical ids, folder renames could avoid reprocessing in some cases. * **Multiple Asset Sources**: Expand AssetPath to support "asset source names" and support multiple AssetReaders in the asset server (ex: `webserver://some_path/image.png` backed by an Http webserver AssetReader). The "default" asset reader would use normal `some_path/image.png` paths. Ideally this works in combination with multiple AssetWatchers for hot-reloading * **Stable Type Names**: this pr removes the TypeUuid requirement from assets in favor of `std::any::type_name`. This makes defining assets easier (no need to generate a new uuid / use weird proc macro syntax). It also makes reading meta files easier (because things have "friendly names"). We also use type names for components in scene files. If they are good enough for components, they are good enough for assets. And consistency across Bevy pillars is desirable. However, `std::any::type_name` is not guaranteed to be stable (although in practice it is). We've developed a [stable type path](https://github.com/bevyengine/bevy/pull/7184) to resolve this, which should be adopted when it is ready. * **Command Line Interface**: It should be possible to run the asset processor in a separate process from the command line. This will also require building a network-server-backed AssetReader to communicate between the app and the processor. We've been planning to build a "bevy cli" for awhile. This seems like a good excuse to build it. * **Asset Packing**: This is largely an additive feature, so it made sense to me to punt this until we've laid the foundations in this PR. * **Per-Platform Processed Assets**: It should be possible to generate assets for multiple platforms by supporting multiple "processor profiles" per asset (ex: compress with format X on PC and Y on iOS). I think there should probably be arbitrary "profiles" (which can be separate from actual platforms), which are then assigned to a given platform when generating the final asset distribution for that platform. Ex: maybe devs want a "Mobile" profile that is shared between iOS and Android. Or a "LowEnd" profile shared between web and mobile. * **Versioning and Migrations**: Assets, Loaders, Savers, and Processors need to have versions to determine if their schema is valid. If an asset / loader version is incompatible with the current version expected at runtime, the processor should be able to migrate them. I think we should try using Bevy Reflect for this, as it would allow us to load the old version as a dynamic Reflect type without actually having the old Rust type. It would also allow us to define "patches" to migrate between versions (Bevy Reflect devs are currently working on patching). The `.meta` file already has its own format version. Migrating that to new versions should also be possible. * **Real Copy-on-write AssetPaths**: Rust's actual Cow (clone-on-write type) currently used by AssetPath can still result in String clones that aren't actually necessary (cloning an Owned Cow clones the contents). Bevy's asset system requires cloning AssetPaths in a number of places, which result in actual clones of the internal Strings. This is not efficient. AssetPath internals should be reworked to exhibit truer cow-like-behavior that reduces String clones to the absolute minimum. * **Consider processor-less processing**: In theory the AssetServer could run processors "inline" even if the background AssetProcessor is disabled. If we decide this is actually desirable, we could add this. But I don't think its a priority in the short or medium term. * **Pre-emptive dependency loading**: We could encode dependencies in processed meta files, which could then be used by the Asset Server to kick of dependency loads as early as possible (prior to starting the actual asset load). Is this desirable? How much time would this save in practice? * **Optimize Processor With UntypedAssetIds**: The processor exclusively uses AssetPath to identify assets currently. It might be possible to swap these out for UntypedAssetIds in some places, which are smaller / cheaper to hash and compare. * **One to Many Asset Processing**: An asset source file that produces many assets currently must be processed into a single "processed" asset source. If labeled assets can be written separately they can each have their own configured savers _and_ they could be loaded more granularly. Definitely worth exploring! * **Automatically Track "Runtime-only" Asset Dependencies**: Right now, tracking "created at runtime" asset dependencies requires adding them via `asset_server.load_asset(StandardMaterial::default())`. I think with some cleverness we could also do this for `materials.add(StandardMaterial::default())`, making tracking work "everywhere". There are challenges here relating to change detection / ensuring the server is made aware of dependency changes. This could be expensive in some cases. * **"Dependency Changed" events**: Some assets have runtime artifacts that need to be re-generated when one of their dependencies change (ex: regenerate a material's bind group when a Texture needs to change). We are generating the dependency graph so we can definitely produce these events. Buuuuut generating these events will have a cost / they could be high frequency for some assets, so we might want this to be opt-in for specific cases. * **Investigate Storing More Information In Handles**: Handles can now store arbitrary information, which makes it cheaper and easier to access. How much should we move into them? Canonical asset load states (via atomics)? (`handle.is_loaded()` would be very cool). Should we store the entire asset and remove the `Assets<T>` collection? (`Arc<RwLock<Option<Image>>>`?) * **Support processing and loading files without extensions**: This is a pretty arbitrary restriction and could be supported with very minimal changes. * **Folder Meta**: It would be nice if we could define per folder processor configuration defaults (likely in a `.meta` or `.folder_meta` file). Things like "default to linear filtering for all Images in this folder". * **Replace async_broadcast with event-listener?** This might be approximately drop-in for some uses and it feels more light weight * **Support Running the AssetProcessor on the Web**: Most of the hard work is done here, but there are some easy straggling TODOs (make the transaction log an interface instead of a direct file writer so we can write a web storage backend, implement an AssetReader/AssetWriter that reads/writes to something like LocalStorage). * **Consider identifying and preventing circular dependencies**: This is especially important for "processor dependencies", as processing will silently never finish in these cases. * **Built-in/Inlined Asset Hot Reloading**: This PR regresses "built-in/inlined" asset hot reloading (previously provided by the DebugAssetServer). I'm intentionally punting this because I think it can be cleanly implemented with "multiple asset sources" by registering a "debug asset source" (ex: `debug://bevy_pbr/src/render/pbr.wgsl` asset paths) in combination with an AssetWatcher for that asset source and support for "manually loading pats with asset bytes instead of AssetReaders". The old DebugAssetServer was quite nasty and I'd love to avoid that hackery going forward. * **Investigate ways to remove double-parsing meta files**: Parsing meta files currently involves parsing once with "minimal" versions of the meta file to extract the type name of the loader/processor config, then parsing again to parse the "full" meta. This is suboptimal. We should be able to define custom deserializers that (1) assume the loader/processor type name comes first (2) dynamically looks up the loader/processor registrations to deserialize settings in-line (similar to components in the bevy scene format). Another alternative: deserialize as dynamic Reflect objects and then convert. * **More runtime loading configuration**: Support using the Handle type as a hint to select an asset loader (instead of relying on AssetPath extensions) * **More high level Processor trait implementations**: For example, it might be worth adding support for arbitrary chains of "asset transforms" that modify an in-memory asset representation between loading and saving. (ex: load a Mesh, run a `subdivide_mesh` transform, followed by a `flip_normals` transform, then save the mesh to an efficient compressed format). * **Bevy Scene Handle Deserialization**: (see the relevant [Draft TODO item](#draft-todo) for context) * **Explore High Level Load Interfaces**: See [this discussion](#discuss-on_loaded-high-level-interface) for one prototype. * **Asset Streaming**: It would be great if we could stream Assets (ex: stream a long video file piece by piece) * **ID Exchanging**: In this PR Asset Handles/AssetIds are bigger than they need to be because they have a Uuid enum variant. If we implement an "id exchanging" system that trades Uuids for "efficient runtime ids", we can cut down on the size of AssetIds, making them more efficient. This has some open design questions, such as how to spawn entities with "default" handle values (as these wouldn't have access to the exchange api in the current system). * **Asset Path Fixup Tooling**: Assets that inline asset paths inside them will break when an asset moves. The asset system provides the functionality to detect when paths break. We should build a framework that enables formats to define "path migrations". This is especially important for scene files. For editor-generated files, we should also consider using UUIDs (see other bullet point) to avoid the need to migrate in these cases. --------- Co-authored-by: BeastLe9enD <beastle9end@outlook.de> Co-authored-by: Mike <mike.hsu@gmail.com> Co-authored-by: Nicola Papale <nicopap@users.noreply.github.com>
2023-09-07 02:07:27 +00:00
doc-scrape-examples = true
Add `asset_processor` feature and remove AssetMode::ProcessedDev (#10194) # Objective Users shouldn't need to change their source code between "development workflows" and "releasing". Currently, Bevy Asset V2 has two "processed" asset modes `Processed` (assumes assets are already processed) and `ProcessedDev` (starts an asset processor and processes assets). This means that the mode must be changed _in code_ when switching from "app dev" to "release". Very suboptimal. We have already removed "runtime opt-in" for hot-reloading. Enabling the `file_watcher` feature _automatically_ enables file watching in code. This means deploying a game (without hot reloading enabled) just means calling `cargo build --release` instead of `cargo run --features bevy/file_watcher`. We should adopt this pattern for asset processing. ## Solution This adds the `asset_processor` feature, which will start the `AssetProcessor` when an `AssetPlugin` runs in `AssetMode::Processed`. The "asset processing workflow" is now: 1. Enable `AssetMode::Processed` on `AssetPlugin` 2. When developing, run with the `asset_processor` and `file_watcher` features 3. When releasing, build without these features. The `AssetMode::ProcessedDev` mode has been removed.
2023-10-20 20:50:26 +00:00
required-features = ["file_watcher", "asset_processor"]
Bevy Asset V2 (#8624) # Bevy Asset V2 Proposal ## Why Does Bevy Need A New Asset System? Asset pipelines are a central part of the gamedev process. Bevy's current asset system is missing a number of features that make it non-viable for many classes of gamedev. After plenty of discussions and [a long community feedback period](https://github.com/bevyengine/bevy/discussions/3972), we've identified a number missing features: * **Asset Preprocessing**: it should be possible to "preprocess" / "compile" / "crunch" assets at "development time" rather than when the game starts up. This enables offloading expensive work from deployed apps, faster asset loading, less runtime memory usage, etc. * **Per-Asset Loader Settings**: Individual assets cannot define their own loaders that override the defaults. Additionally, they cannot provide per-asset settings to their loaders. This is a huge limitation, as many asset types don't provide all information necessary for Bevy _inside_ the asset. For example, a raw PNG image says nothing about how it should be sampled (ex: linear vs nearest). * **Asset `.meta` files**: assets should have configuration files stored adjacent to the asset in question, which allows the user to configure asset-type-specific settings. These settings should be accessible during the pre-processing phase. Modifying a `.meta` file should trigger a re-processing / re-load of the asset. It should be possible to configure asset loaders from the meta file. * **Processed Asset Hot Reloading**: Changes to processed assets (or their dependencies) should result in re-processing them and re-loading the results in live Bevy Apps. * **Asset Dependency Tracking**: The current bevy_asset has no good way to wait for asset dependencies to load. It punts this as an exercise for consumers of the loader apis, which is unreasonable and error prone. There should be easy, ergonomic ways to wait for assets to load and block some logic on an asset's entire dependency tree loading. * **Runtime Asset Loading**: it should be (optionally) possible to load arbitrary assets dynamically at runtime. This necessitates being able to deploy and run the asset server alongside Bevy Apps on _all platforms_. For example, we should be able to invoke the shader compiler at runtime, stream scenes from sources like the internet, etc. To keep deployed binaries (and startup times) small, the runtime asset server configuration should be configurable with different settings compared to the "pre processor asset server". * **Multiple Backends**: It should be possible to load assets from arbitrary sources (filesystems, the internet, remote asset serves, etc). * **Asset Packing**: It should be possible to deploy assets in compressed "packs", which makes it easier and more efficient to distribute assets with Bevy Apps. * **Asset Handoff**: It should be possible to hold a "live" asset handle, which correlates to runtime data, without actually holding the asset in memory. Ex: it must be possible to hold a reference to a GPU mesh generated from a "mesh asset" without keeping the mesh data in CPU memory * **Per-Platform Processed Assets**: Different platforms and app distributions have different capabilities and requirements. Some platforms need lower asset resolutions or different asset formats to operate within the hardware constraints of the platform. It should be possible to define per-platform asset processing profiles. And it should be possible to deploy only the assets required for a given platform. These features have architectural implications that are significant enough to require a full rewrite. The current Bevy Asset implementation got us this far, but it can take us no farther. This PR defines a brand new asset system that implements most of these features, while laying the foundations for the remaining features to be built. ## Bevy Asset V2 Here is a quick overview of the features introduced in this PR. * **Asset Preprocessing**: Preprocess assets at development time into more efficient (and configurable) representations * **Dependency Aware**: Dependencies required to process an asset are tracked. If an asset's processed dependency changes, it will be reprocessed * **Hot Reprocessing/Reloading**: detect changes to asset source files, reprocess them if they have changed, and then hot-reload them in Bevy Apps. * **Only Process Changes**: Assets are only re-processed when their source file (or meta file) has changed. This uses hashing and timestamps to avoid processing assets that haven't changed. * **Transactional and Reliable**: Uses write-ahead logging (a technique commonly used by databases) to recover from crashes / forced-exits. Whenever possible it avoids full-reprocessing / only uncompleted transactions will be reprocessed. When the processor is running in parallel with a Bevy App, processor asset writes block Bevy App asset reads. Reading metadata + asset bytes is guaranteed to be transactional / correctly paired. * **Portable / Run anywhere / Database-free**: The processor does not rely on an in-memory database (although it uses some database techniques for reliability). This is important because pretty much all in-memory databases have unsupported platforms or build complications. * **Configure Processor Defaults Per File Type**: You can say "use this processor for all files of this type". * **Custom Processors**: The `Processor` trait is flexible and unopinionated. It can be implemented by downstream plugins. * **LoadAndSave Processors**: Most asset processing scenarios can be expressed as "run AssetLoader A, save the results using AssetSaver X, and then load the result using AssetLoader B". For example, load this png image using `PngImageLoader`, which produces an `Image` asset and then save it using `CompressedImageSaver` (which also produces an `Image` asset, but in a compressed format), which takes an `Image` asset as input. This means if you have an `AssetLoader` for an asset, you are already half way there! It also means that you can share AssetSavers across multiple loaders. Because `CompressedImageSaver` accepts Bevy's generic Image asset as input, it means you can also use it with some future `JpegImageLoader`. * **Loader and Saver Settings**: Asset Loaders and Savers can now define their own settings types, which are passed in as input when an asset is loaded / saved. Each asset can define its own settings. * **Asset `.meta` files**: configure asset loaders, their settings, enable/disable processing, and configure processor settings * **Runtime Asset Dependency Tracking** Runtime asset dependencies (ex: if an asset contains a `Handle<Image>`) are tracked by the asset server. An event is emitted when an asset and all of its dependencies have been loaded * **Unprocessed Asset Loading**: Assets do not require preprocessing. They can be loaded directly. A processed asset is just a "normal" asset with some extra metadata. Asset Loaders don't need to know or care about whether or not an asset was processed. * **Async Asset IO**: Asset readers/writers use async non-blocking interfaces. Note that because Rust doesn't yet support async traits, there is a bit of manual Boxing / Future boilerplate. This will hopefully be removed in the near future when Rust gets async traits. * **Pluggable Asset Readers and Writers**: Arbitrary asset source readers/writers are supported, both by the processor and the asset server. * **Better Asset Handles** * **Single Arc Tree**: Asset Handles now use a single arc tree that represents the lifetime of the asset. This makes their implementation simpler, more efficient, and allows us to cheaply attach metadata to handles. Ex: the AssetPath of a handle is now directly accessible on the handle itself! * **Const Typed Handles**: typed handles can be constructed in a const context. No more weird "const untyped converted to typed at runtime" patterns! * **Handles and Ids are Smaller / Faster To Hash / Compare**: Typed `Handle<T>` is now much smaller in memory and `AssetId<T>` is even smaller. * **Weak Handle Usage Reduction**: In general Handles are now considered to be "strong". Bevy features that previously used "weak `Handle<T>`" have been ported to `AssetId<T>`, which makes it statically clear that the features do not hold strong handles (while retaining strong type information). Currently Handle::Weak still exists, but it is very possible that we can remove that entirely. * **Efficient / Dense Asset Ids**: Assets now have efficient dense runtime asset ids, which means we can avoid expensive hash lookups. Assets are stored in Vecs instead of HashMaps. There are now typed and untyped ids, which means we no longer need to store dynamic type information in the ID for typed handles. "AssetPathId" (which was a nightmare from a performance and correctness standpoint) has been entirely removed in favor of dense ids (which are retrieved for a path on load) * **Direct Asset Loading, with Dependency Tracking**: Assets that are defined at runtime can still have their dependencies tracked by the Asset Server (ex: if you create a material at runtime, you can still wait for its textures to load). This is accomplished via the (currently optional) "asset dependency visitor" trait. This system can also be used to define a set of assets to load, then wait for those assets to load. * **Async folder loading**: Folder loading also uses this system and immediately returns a handle to the LoadedFolder asset, which means folder loading no longer blocks on directory traversals. * **Improved Loader Interface**: Loaders now have a specific "top level asset type", which makes returning the top-level asset simpler and statically typed. * **Basic Image Settings and Processing**: Image assets can now be processed into the gpu-friendly Basic Universal format. The ImageLoader now has a setting to define what format the image should be loaded as. Note that this is just a minimal MVP ... plenty of additional work to do here. To demo this, enable the `basis-universal` feature and turn on asset processing. * **Simpler Audio Play / AudioSink API**: Asset handle providers are cloneable, which means the Audio resource can mint its own handles. This means you can now do `let sink_handle = audio.play(music)` instead of `let sink_handle = audio_sinks.get_handle(audio.play(music))`. Note that this might still be replaced by https://github.com/bevyengine/bevy/pull/8424. **Removed Handle Casting From Engine Features**: Ex: FontAtlases no longer use casting between handle types ## Using The New Asset System ### Normal Unprocessed Asset Loading By default the `AssetPlugin` does not use processing. It behaves pretty much the same way as the old system. If you are defining a custom asset, first derive `Asset`: ```rust #[derive(Asset)] struct Thing { value: String, } ``` Initialize the asset: ```rust app.init_asset:<Thing>() ``` Implement a new `AssetLoader` for it: ```rust #[derive(Default)] struct ThingLoader; #[derive(Serialize, Deserialize, Default)] pub struct ThingSettings { some_setting: bool, } impl AssetLoader for ThingLoader { type Asset = Thing; type Settings = ThingSettings; fn load<'a>( &'a self, reader: &'a mut Reader, settings: &'a ThingSettings, load_context: &'a mut LoadContext, ) -> BoxedFuture<'a, Result<Thing, anyhow::Error>> { Box::pin(async move { let mut bytes = Vec::new(); reader.read_to_end(&mut bytes).await?; // convert bytes to value somehow Ok(Thing { value }) }) } fn extensions(&self) -> &[&str] { &["thing"] } } ``` Note that this interface will get much cleaner once Rust gets support for async traits. `Reader` is an async futures_io::AsyncRead. You can stream bytes as they come in or read them all into a `Vec<u8>`, depending on the context. You can use `let handle = load_context.load(path)` to kick off a dependency load, retrieve a handle, and register the dependency for the asset. Then just register the loader in your Bevy app: ```rust app.init_asset_loader::<ThingLoader>() ``` Now just add your `Thing` asset files into the `assets` folder and load them like this: ```rust fn system(asset_server: Res<AssetServer>) { let handle = Handle<Thing> = asset_server.load("cool.thing"); } ``` You can check load states directly via the asset server: ```rust if asset_server.load_state(&handle) == LoadState::Loaded { } ``` You can also listen for events: ```rust fn system(mut events: EventReader<AssetEvent<Thing>>, handle: Res<SomeThingHandle>) { for event in events.iter() { if event.is_loaded_with_dependencies(&handle) { } } } ``` Note the new `AssetEvent::LoadedWithDependencies`, which only fires when the asset is loaded _and_ all dependencies (and their dependencies) have loaded. Unlike the old asset system, for a given asset path all `Handle<T>` values point to the same underlying Arc. This means Handles can cheaply hold more asset information, such as the AssetPath: ```rust // prints the AssetPath of the handle info!("{:?}", handle.path()) ``` ### Processed Assets Asset processing can be enabled via the `AssetPlugin`. When developing Bevy Apps with processed assets, do this: ```rust app.add_plugins(DefaultPlugins.set(AssetPlugin::processed_dev())) ``` This runs the `AssetProcessor` in the background with hot-reloading. It reads assets from the `assets` folder, processes them, and writes them to the `.imported_assets` folder. Asset loads in the Bevy App will wait for a processed version of the asset to become available. If an asset in the `assets` folder changes, it will be reprocessed and hot-reloaded in the Bevy App. When deploying processed Bevy apps, do this: ```rust app.add_plugins(DefaultPlugins.set(AssetPlugin::processed())) ``` This does not run the `AssetProcessor` in the background. It behaves like `AssetPlugin::unprocessed()`, but reads assets from `.imported_assets`. When the `AssetProcessor` is running, it will populate sibling `.meta` files for assets in the `assets` folder. Meta files for assets that do not have a processor configured look like this: ```rust ( meta_format_version: "1.0", asset: Load( loader: "bevy_render::texture::image_loader::ImageLoader", settings: ( format: FromExtension, ), ), ) ``` This is metadata for an image asset. For example, if you have `assets/my_sprite.png`, this could be the metadata stored at `assets/my_sprite.png.meta`. Meta files are totally optional. If no metadata exists, the default settings will be used. In short, this file says "load this asset with the ImageLoader and use the file extension to determine the image type". This type of meta file is supported in all AssetPlugin modes. If in `Unprocessed` mode, the asset (with the meta settings) will be loaded directly. If in `ProcessedDev` mode, the asset file will be copied directly to the `.imported_assets` folder. The meta will also be copied directly to the `.imported_assets` folder, but with one addition: ```rust ( meta_format_version: "1.0", processed_info: Some(( hash: 12415480888597742505, full_hash: 14344495437905856884, process_dependencies: [], )), asset: Load( loader: "bevy_render::texture::image_loader::ImageLoader", settings: ( format: FromExtension, ), ), ) ``` `processed_info` contains `hash` (a direct hash of the asset and meta bytes), `full_hash` (a hash of `hash` and the hashes of all `process_dependencies`), and `process_dependencies` (the `path` and `full_hash` of every process_dependency). A "process dependency" is an asset dependency that is _directly_ used when processing the asset. Images do not have process dependencies, so this is empty. When the processor is enabled, you can use the `Process` metadata config: ```rust ( meta_format_version: "1.0", asset: Process( processor: "bevy_asset::processor::process::LoadAndSave<bevy_render::texture::image_loader::ImageLoader, bevy_render::texture::compressed_image_saver::CompressedImageSaver>", settings: ( loader_settings: ( format: FromExtension, ), saver_settings: ( generate_mipmaps: true, ), ), ), ) ``` This configures the asset to use the `LoadAndSave` processor, which runs an AssetLoader and feeds the result into an AssetSaver (which saves the given Asset and defines a loader to load it with). (for terseness LoadAndSave will likely get a shorter/friendlier type name when [Stable Type Paths](#7184) lands). `LoadAndSave` is likely to be the most common processor type, but arbitrary processors are supported. `CompressedImageSaver` saves an `Image` in the Basis Universal format and configures the ImageLoader to load it as basis universal. The `AssetProcessor` will read this meta, run it through the LoadAndSave processor, and write the basis-universal version of the image to `.imported_assets`. The final metadata will look like this: ```rust ( meta_format_version: "1.0", processed_info: Some(( hash: 905599590923828066, full_hash: 9948823010183819117, process_dependencies: [], )), asset: Load( loader: "bevy_render::texture::image_loader::ImageLoader", settings: ( format: Format(Basis), ), ), ) ``` To try basis-universal processing out in Bevy examples, (for example `sprite.rs`), change `add_plugins(DefaultPlugins)` to `add_plugins(DefaultPlugins.set(AssetPlugin::processed_dev()))` and run with the `basis-universal` feature enabled: `cargo run --features=basis-universal --example sprite`. To create a custom processor, there are two main paths: 1. Use the `LoadAndSave` processor with an existing `AssetLoader`. Implement the `AssetSaver` trait, register the processor using `asset_processor.register_processor::<LoadAndSave<ImageLoader, CompressedImageSaver>>(image_saver.into())`. 2. Implement the `Process` trait directly and register it using: `asset_processor.register_processor(thing_processor)`. You can configure default processors for file extensions like this: ```rust asset_processor.set_default_processor::<ThingProcessor>("thing") ``` There is one more metadata type to be aware of: ```rust ( meta_format_version: "1.0", asset: Ignore, ) ``` This will ignore the asset during processing / prevent it from being written to `.imported_assets`. The AssetProcessor stores a transaction log at `.imported_assets/log` and uses it to gracefully recover from unexpected stops. This means you can force-quit the processor (and Bevy Apps running the processor in parallel) at arbitrary times! `.imported_assets` is "local state". It should _not_ be checked into source control. It should also be considered "read only". In practice, you _can_ modify processed assets and processed metadata if you really need to test something. But those modifications will not be represented in the hashes of the assets, so the processed state will be "out of sync" with the source assets. The processor _will not_ fix this for you. Either revert the change after you have tested it, or delete the processed files so they can be re-populated. ## Open Questions There are a number of open questions to be discussed. We should decide if they need to be addressed in this PR and if so, how we will address them: ### Implied Dependencies vs Dependency Enumeration There are currently two ways to populate asset dependencies: * **Implied via AssetLoaders**: if an AssetLoader loads an asset (and retrieves a handle), a dependency is added to the list. * **Explicit via the optional Asset::visit_dependencies**: if `server.load_asset(my_asset)` is called, it will call `my_asset.visit_dependencies`, which will grab dependencies that have been manually defined for the asset via the Asset trait impl (which can be derived). This means that defining explicit dependencies is optional for "loaded assets". And the list of dependencies is always accurate because loaders can only produce Handles if they register dependencies. If an asset was loaded with an AssetLoader, it only uses the implied dependencies. If an asset was created at runtime and added with `asset_server.load_asset(MyAsset)`, it will use `Asset::visit_dependencies`. However this can create a behavior mismatch between loaded assets and equivalent "created at runtime" assets if `Assets::visit_dependencies` doesn't exactly match the dependencies produced by the AssetLoader. This behavior mismatch can be resolved by completely removing "implied loader dependencies" and requiring `Asset::visit_dependencies` to supply dependency data. But this creates two problems: * It makes defining loaded assets harder and more error prone: Devs must remember to manually annotate asset dependencies with `#[dependency]` when deriving `Asset`. For more complicated assets (such as scenes), the derive likely wouldn't be sufficient and a manual `visit_dependencies` impl would be required. * Removes the ability to immediately kick off dependency loads: When AssetLoaders retrieve a Handle, they also immediately kick off an asset load for the handle, which means it can start loading in parallel _before_ the asset finishes loading. For large assets, this could be significant. (although this could be mitigated for processed assets if we store dependencies in the processed meta file and load them ahead of time) ### Eager ProcessorDev Asset Loading I made a controversial call in the interest of fast startup times ("time to first pixel") for the "processor dev mode configuration". When initializing the AssetProcessor, current processed versions of unchanged assets are yielded immediately, even if their dependencies haven't been checked yet for reprocessing. This means that non-current-state-of-filesystem-but-previously-valid assets might be returned to the App first, then hot-reloaded if/when their dependencies change and the asset is reprocessed. Is this behavior desirable? There is largely one alternative: do not yield an asset from the processor to the app until all of its dependencies have been checked for changes. In some common cases (load dependency has not changed since last run) this will increase startup time. The main question is "by how much" and is that slower startup time worth it in the interest of only yielding assets that are true to the current state of the filesystem. Should this be configurable? I'm starting to think we should only yield an asset after its (historical) dependencies have been checked for changes + processed as necessary, but I'm curious what you all think. ### Paths Are Currently The Only Canonical ID / Do We Want Asset UUIDs? In this implementation AssetPaths are the only canonical asset identifier (just like the previous Bevy Asset system and Godot). Moving assets will result in re-scans (and currently reprocessing, although reprocessing can easily be avoided with some changes). Asset renames/moves will break code and assets that rely on specific paths, unless those paths are fixed up. Do we want / need "stable asset uuids"? Introducing them is very possible: 1. Generate a UUID and include it in .meta files 2. Support UUID in AssetPath 3. Generate "asset indices" which are loaded on startup and map UUIDs to paths. 4 (maybe). Consider only supporting UUIDs for processed assets so we can generate quick-to-load indices instead of scanning meta files. The main "pro" is that assets referencing UUIDs don't need to be migrated when a path changes. The main "con" is that UUIDs cannot be "lazily resolved" like paths. They need a full view of all assets to answer the question "does this UUID exist". Which means UUIDs require the AssetProcessor to fully finish startup scans before saying an asset doesnt exist. And they essentially require asset pre-processing to use in apps, because scanning all asset metadata files at runtime to resolve a UUID is not viable for medium-to-large apps. It really requires a pre-generated UUID index, which must be loaded before querying for assets. I personally think this should be investigated in a separate PR. Paths aren't going anywhere ... _everyone_ uses filesystems (and filesystem-like apis) to manage their asset source files. I consider them permanent canonical asset information. Additionally, they behave well for both processed and unprocessed asset modes. Given that Bevy is supporting both, this feels like the right canonical ID to start with. UUIDS (and maybe even other indexed-identifier types) can be added later as necessary. ### Folder / File Naming Conventions All asset processing config currently lives in the `.imported_assets` folder. The processor transaction log is in `.imported_assets/log`. Processed assets are added to `.imported_assets/Default`, which will make migrating to processed asset profiles (ex: a `.imported_assets/Mobile` profile) a non-breaking change. It also allows us to create top-level files like `.imported_assets/log` without it being interpreted as an asset. Meta files currently have a `.meta` suffix. Do we like these names and conventions? ### Should the `AssetPlugin::processed_dev` configuration enable `watch_for_changes` automatically? Currently it does (which I think makes sense), but it does make it the only configuration that enables watch_for_changes by default. ### Discuss on_loaded High Level Interface: This PR includes a very rough "proof of concept" `on_loaded` system adapter that uses the `LoadedWithDependencies` event in combination with `asset_server.load_asset` dependency tracking to support this pattern ```rust fn main() { App::new() .init_asset::<MyAssets>() .add_systems(Update, on_loaded(create_array_texture)) .run(); } #[derive(Asset, Clone)] struct MyAssets { #[dependency] picture_of_my_cat: Handle<Image>, #[dependency] picture_of_my_other_cat: Handle<Image>, } impl FromWorld for ArrayTexture { fn from_world(world: &mut World) -> Self { picture_of_my_cat: server.load("meow.png"), picture_of_my_other_cat: server.load("meeeeeeeow.png"), } } fn spawn_cat(In(my_assets): In<MyAssets>, mut commands: Commands) { commands.spawn(SpriteBundle { texture: my_assets.picture_of_my_cat.clone(), ..default() }); commands.spawn(SpriteBundle { texture: my_assets.picture_of_my_other_cat.clone(), ..default() }); } ``` The implementation is _very_ rough. And it is currently unsafe because `bevy_ecs` doesn't expose some internals to do this safely from inside `bevy_asset`. There are plenty of unanswered questions like: * "do we add a Loadable" derive? (effectively automate the FromWorld implementation above) * Should `MyAssets` even be an Asset? (largely implemented this way because it elegantly builds on `server.load_asset(MyAsset { .. })` dependency tracking). We should think hard about what our ideal API looks like (and if this is a pattern we want to support). Not necessarily something we need to solve in this PR. The current `on_loaded` impl should probably be removed from this PR before merging. ## Clarifying Questions ### What about Assets as Entities? This Bevy Asset V2 proposal implementation initially stored Assets as ECS Entities. Instead of `AssetId<T>` + the `Assets<T>` resource it used `Entity` as the asset id and Asset values were just ECS components. There are plenty of compelling reasons to do this: 1. Easier to inline assets in Bevy Scenes (as they are "just" normal entities + components) 2. More flexible queries: use the power of the ECS to filter assets (ex: `Query<Mesh, With<Tree>>`). 3. Extensible. Users can add arbitrary component data to assets. 4. Things like "component visualization tools" work out of the box to visualize asset data. However Assets as Entities has a ton of caveats right now: * We need to be able to allocate entity ids without a direct World reference (aka rework id allocator in Entities ... i worked around this in my prototypes by just pre allocating big chunks of entities) * We want asset change events in addition to ECS change tracking ... how do we populate them when mutations can come from anywhere? Do we use Changed queries? This would require iterating over the change data for all assets every frame. Is this acceptable or should we implement a new "event based" component change detection option? * Reconciling manually created assets with asset-system managed assets has some nuance (ex: are they "loaded" / do they also have that component metadata?) * "how do we handle "static" / default entity handles" (ties in to the Entity Indices discussion: https://github.com/bevyengine/bevy/discussions/8319). This is necessary for things like "built in" assets and default handles in things like SpriteBundle. * Storing asset information as a component makes it easy to "invalidate" asset state by removing the component (or forcing modifications). Ideally we have ways to lock this down (some combination of Rust type privacy and ECS validation) In practice, how we store and identify assets is a reasonably superficial change (porting off of Assets as Entities and implementing dedicated storage + ids took less than a day). So once we sort out the remaining challenges the flip should be straightforward. Additionally, I do still have "Assets as Entities" in my commit history, so we can reuse that work. I personally think "assets as entities" is a good endgame, but it also doesn't provide _significant_ value at the moment and it certainly isn't ready yet with the current state of things. ### Why not Distill? [Distill](https://github.com/amethyst/distill) is a high quality fully featured asset system built in Rust. It is very natural to ask "why not just use Distill?". It is also worth calling out that for awhile, [we planned on adopting Distill / I signed off on it](https://github.com/bevyengine/bevy/issues/708). However I think Bevy has a number of constraints that make Distill adoption suboptimal: * **Architectural Simplicity:** * Distill's processor requires an in-memory database (lmdb) and RPC networked API (using Cap'n Proto). Each of these introduces API complexity that increases maintenance burden and "code grokability". Ignoring tests, documentation, and examples, Distill has 24,237 lines of Rust code (including generated code for RPC + database interactions). If you ignore generated code, it has 11,499 lines. * Bevy builds the AssetProcessor and AssetServer using pluggable AssetReader/AssetWriter Rust traits with simple io interfaces. They do not necessitate databases or RPC interfaces (although Readers/Writers could use them if that is desired). Bevy Asset V2 (at the time of writing this PR) is 5,384 lines of Rust code (ignoring tests, documentation, and examples). Grain of salt: Distill does have more features currently (ex: Asset Packing, GUIDS, remote-out-of-process asset processor). I do plan to implement these features in Bevy Asset V2 and I personally highly doubt they will meaningfully close the 6115 lines-of-code gap. * This complexity gap (which while illustrated by lines of code, is much bigger than just that) is noteworthy to me. Bevy should be hackable and there are pillars of Distill that are very hard to understand and extend. This is a matter of opinion (and Bevy Asset V2 also has complicated areas), but I think Bevy Asset V2 is much more approachable for the average developer. * Necessary disclaimer: counting lines of code is an extremely rough complexity metric. Read the code and form your own opinions. * **Optional Asset Processing:** Not all Bevy Apps (or Bevy App developers) need / want asset preprocessing. Processing increases the complexity of the development environment by introducing things like meta files, imported asset storage, running processors in the background, waiting for processing to finish, etc. Distill _requires_ preprocessing to work. With Bevy Asset V2 processing is fully opt-in. The AssetServer isn't directly aware of asset processors at all. AssetLoaders only care about converting bytes to runtime Assets ... they don't know or care if the bytes were pre-processed or not. Processing is "elegantly" (forgive my self-congratulatory phrasing) layered on top and builds on the existing Asset system primitives. * **Direct Filesystem Access to Processed Asset State:** Distill stores processed assets in a database. This makes debugging / inspecting the processed outputs harder (either requires special tooling to query the database or they need to be "deployed" to be inspected). Bevy Asset V2, on the other hand, stores processed assets in the filesystem (by default ... this is configurable). This makes interacting with the processed state more natural. Note that both Godot and Unity's new asset system store processed assets in the filesystem. * **Portability**: Because Distill's processor uses lmdb and RPC networking, it cannot be run on certain platforms (ex: lmdb is a non-rust dependency that cannot run on the web, some platforms don't support running network servers). Bevy should be able to process assets everywhere (ex: run the Bevy Editor on the web, compile + process shaders on mobile, etc). Distill does partially mitigate this problem by supporting "streaming" assets via the RPC protocol, but this is not a full solve from my perspective. And Bevy Asset V2 can (in theory) also stream assets (without requiring RPC, although this isn't implemented yet) Note that I _do_ still think Distill would be a solid asset system for Bevy. But I think the approach in this PR is a better solve for Bevy's specific "asset system requirements". ### Doesn't async-fs just shim requests to "sync" `std::fs`? What is the point? "True async file io" has limited / spotty platform support. async-fs (and the rust async ecosystem generally ... ex Tokio) currently use async wrappers over std::fs that offload blocking requests to separate threads. This may feel unsatisfying, but it _does_ still provide value because it prevents our task pools from blocking on file system operations (which would prevent progress when there are many tasks to do, but all threads in a pool are currently blocking on file system ops). Additionally, using async APIs for our AssetReaders and AssetWriters also provides value because we can later add support for "true async file io" for platforms that support it. _And_ we can implement other "true async io" asset backends (such as networked asset io). ## Draft TODO - [x] Fill in missing filesystem event APIs: file removed event (which is expressed as dangling RenameFrom events in some cases), file/folder renamed event - [x] Assets without loaders are not moved to the processed folder. This breaks things like referenced `.bin` files for GLTFs. This should be configurable per-non-asset-type. - [x] Initial implementation of Reflect and FromReflect for Handle. The "deserialization" parity bar is low here as this only worked with static UUIDs in the old impl ... this is a non-trivial problem. Either we add a Handle::AssetPath variant that gets "upgraded" to a strong handle on scene load or we use a separate AssetRef type for Bevy scenes (which is converted to a runtime Handle on load). This deserves its own discussion in a different pr. - [x] Populate read_asset_bytes hash when run by the processor (a bit of a special case .. when run by the processor the processed meta will contain the hash so we don't need to compute it on the spot, but we don't want/need to read the meta when run by the main AssetServer) - [x] Delay hot reloading: currently filesystem events are handled immediately, which creates timing issues in some cases. For example hot reloading images can sometimes break because the image isn't finished writing. We should add a delay, likely similar to the [implementation in this PR](https://github.com/bevyengine/bevy/pull/8503). - [x] Port old platform-specific AssetIo implementations to the new AssetReader interface (currently missing Android and web) - [x] Resolve on_loaded unsafety (either by removing the API entirely or removing the unsafe) - [x] Runtime loader setting overrides - [x] Remove remaining unwraps that should be error-handled. There are number of TODOs here - [x] Pretty AssetPath Display impl - [x] Document more APIs - [x] Resolve spurious "reloading because it has changed" events (to repro run load_gltf with `processed_dev()`) - [x] load_dependency hot reloading currently only works for processed assets. If processing is disabled, load_dependency changes are not hot reloaded. - [x] Replace AssetInfo dependency load/fail counters with `loading_dependencies: HashSet<UntypedAssetId>` to prevent reloads from (potentially) breaking counters. Storing this will also enable "dependency reloaded" events (see [Next Steps](#next-steps)) - [x] Re-add filesystem watcher cargo feature gate (currently it is not optional) - [ ] Migration Guide - [ ] Changelog ## Followup TODO - [ ] Replace "eager unchanged processed asset loading" behavior with "don't returned unchanged processed asset until dependencies have been checked". - [ ] Add true `Ignore` AssetAction that does not copy the asset to the imported_assets folder. - [ ] Finish "live asset unloading" (ex: free up CPU asset memory after uploading an image to the GPU), rethink RenderAssets, and port renderer features. The `Assets` collection uses `Option<T>` for asset storage to support its removal. (1) the Option might not actually be necessary ... might be able to just remove from the collection entirely (2) need to finalize removal apis - [ ] Try replacing the "channel based" asset id recycling with something a bit more efficient (ex: we might be able to use raw atomic ints with some cleverness) - [ ] Consider adding UUIDs to processed assets (scoped just to helping identify moved assets ... not exposed to load queries ... see [Next Steps](#next-steps)) - [ ] Store "last modified" source asset and meta timestamps in processed meta files to enable skipping expensive hashing when the file wasn't changed - [ ] Fix "slow loop" handle drop fix - [ ] Migrate to TypeName - [x] Handle "loader preregistration". See #9429 ## Next Steps * **Configurable per-type defaults for AssetMeta**: It should be possible to add configuration like "all png image meta should default to using nearest sampling" (currently this hard-coded per-loader/processor Settings::default() impls). Also see the "Folder Meta" bullet point. * **Avoid Reprocessing on Asset Renames / Moves**: See the "canonical asset ids" discussion in [Open Questions](#open-questions) and the relevant bullet point in [Draft TODO](#draft-todo). Even without canonical ids, folder renames could avoid reprocessing in some cases. * **Multiple Asset Sources**: Expand AssetPath to support "asset source names" and support multiple AssetReaders in the asset server (ex: `webserver://some_path/image.png` backed by an Http webserver AssetReader). The "default" asset reader would use normal `some_path/image.png` paths. Ideally this works in combination with multiple AssetWatchers for hot-reloading * **Stable Type Names**: this pr removes the TypeUuid requirement from assets in favor of `std::any::type_name`. This makes defining assets easier (no need to generate a new uuid / use weird proc macro syntax). It also makes reading meta files easier (because things have "friendly names"). We also use type names for components in scene files. If they are good enough for components, they are good enough for assets. And consistency across Bevy pillars is desirable. However, `std::any::type_name` is not guaranteed to be stable (although in practice it is). We've developed a [stable type path](https://github.com/bevyengine/bevy/pull/7184) to resolve this, which should be adopted when it is ready. * **Command Line Interface**: It should be possible to run the asset processor in a separate process from the command line. This will also require building a network-server-backed AssetReader to communicate between the app and the processor. We've been planning to build a "bevy cli" for awhile. This seems like a good excuse to build it. * **Asset Packing**: This is largely an additive feature, so it made sense to me to punt this until we've laid the foundations in this PR. * **Per-Platform Processed Assets**: It should be possible to generate assets for multiple platforms by supporting multiple "processor profiles" per asset (ex: compress with format X on PC and Y on iOS). I think there should probably be arbitrary "profiles" (which can be separate from actual platforms), which are then assigned to a given platform when generating the final asset distribution for that platform. Ex: maybe devs want a "Mobile" profile that is shared between iOS and Android. Or a "LowEnd" profile shared between web and mobile. * **Versioning and Migrations**: Assets, Loaders, Savers, and Processors need to have versions to determine if their schema is valid. If an asset / loader version is incompatible with the current version expected at runtime, the processor should be able to migrate them. I think we should try using Bevy Reflect for this, as it would allow us to load the old version as a dynamic Reflect type without actually having the old Rust type. It would also allow us to define "patches" to migrate between versions (Bevy Reflect devs are currently working on patching). The `.meta` file already has its own format version. Migrating that to new versions should also be possible. * **Real Copy-on-write AssetPaths**: Rust's actual Cow (clone-on-write type) currently used by AssetPath can still result in String clones that aren't actually necessary (cloning an Owned Cow clones the contents). Bevy's asset system requires cloning AssetPaths in a number of places, which result in actual clones of the internal Strings. This is not efficient. AssetPath internals should be reworked to exhibit truer cow-like-behavior that reduces String clones to the absolute minimum. * **Consider processor-less processing**: In theory the AssetServer could run processors "inline" even if the background AssetProcessor is disabled. If we decide this is actually desirable, we could add this. But I don't think its a priority in the short or medium term. * **Pre-emptive dependency loading**: We could encode dependencies in processed meta files, which could then be used by the Asset Server to kick of dependency loads as early as possible (prior to starting the actual asset load). Is this desirable? How much time would this save in practice? * **Optimize Processor With UntypedAssetIds**: The processor exclusively uses AssetPath to identify assets currently. It might be possible to swap these out for UntypedAssetIds in some places, which are smaller / cheaper to hash and compare. * **One to Many Asset Processing**: An asset source file that produces many assets currently must be processed into a single "processed" asset source. If labeled assets can be written separately they can each have their own configured savers _and_ they could be loaded more granularly. Definitely worth exploring! * **Automatically Track "Runtime-only" Asset Dependencies**: Right now, tracking "created at runtime" asset dependencies requires adding them via `asset_server.load_asset(StandardMaterial::default())`. I think with some cleverness we could also do this for `materials.add(StandardMaterial::default())`, making tracking work "everywhere". There are challenges here relating to change detection / ensuring the server is made aware of dependency changes. This could be expensive in some cases. * **"Dependency Changed" events**: Some assets have runtime artifacts that need to be re-generated when one of their dependencies change (ex: regenerate a material's bind group when a Texture needs to change). We are generating the dependency graph so we can definitely produce these events. Buuuuut generating these events will have a cost / they could be high frequency for some assets, so we might want this to be opt-in for specific cases. * **Investigate Storing More Information In Handles**: Handles can now store arbitrary information, which makes it cheaper and easier to access. How much should we move into them? Canonical asset load states (via atomics)? (`handle.is_loaded()` would be very cool). Should we store the entire asset and remove the `Assets<T>` collection? (`Arc<RwLock<Option<Image>>>`?) * **Support processing and loading files without extensions**: This is a pretty arbitrary restriction and could be supported with very minimal changes. * **Folder Meta**: It would be nice if we could define per folder processor configuration defaults (likely in a `.meta` or `.folder_meta` file). Things like "default to linear filtering for all Images in this folder". * **Replace async_broadcast with event-listener?** This might be approximately drop-in for some uses and it feels more light weight * **Support Running the AssetProcessor on the Web**: Most of the hard work is done here, but there are some easy straggling TODOs (make the transaction log an interface instead of a direct file writer so we can write a web storage backend, implement an AssetReader/AssetWriter that reads/writes to something like LocalStorage). * **Consider identifying and preventing circular dependencies**: This is especially important for "processor dependencies", as processing will silently never finish in these cases. * **Built-in/Inlined Asset Hot Reloading**: This PR regresses "built-in/inlined" asset hot reloading (previously provided by the DebugAssetServer). I'm intentionally punting this because I think it can be cleanly implemented with "multiple asset sources" by registering a "debug asset source" (ex: `debug://bevy_pbr/src/render/pbr.wgsl` asset paths) in combination with an AssetWatcher for that asset source and support for "manually loading pats with asset bytes instead of AssetReaders". The old DebugAssetServer was quite nasty and I'd love to avoid that hackery going forward. * **Investigate ways to remove double-parsing meta files**: Parsing meta files currently involves parsing once with "minimal" versions of the meta file to extract the type name of the loader/processor config, then parsing again to parse the "full" meta. This is suboptimal. We should be able to define custom deserializers that (1) assume the loader/processor type name comes first (2) dynamically looks up the loader/processor registrations to deserialize settings in-line (similar to components in the bevy scene format). Another alternative: deserialize as dynamic Reflect objects and then convert. * **More runtime loading configuration**: Support using the Handle type as a hint to select an asset loader (instead of relying on AssetPath extensions) * **More high level Processor trait implementations**: For example, it might be worth adding support for arbitrary chains of "asset transforms" that modify an in-memory asset representation between loading and saving. (ex: load a Mesh, run a `subdivide_mesh` transform, followed by a `flip_normals` transform, then save the mesh to an efficient compressed format). * **Bevy Scene Handle Deserialization**: (see the relevant [Draft TODO item](#draft-todo) for context) * **Explore High Level Load Interfaces**: See [this discussion](#discuss-on_loaded-high-level-interface) for one prototype. * **Asset Streaming**: It would be great if we could stream Assets (ex: stream a long video file piece by piece) * **ID Exchanging**: In this PR Asset Handles/AssetIds are bigger than they need to be because they have a Uuid enum variant. If we implement an "id exchanging" system that trades Uuids for "efficient runtime ids", we can cut down on the size of AssetIds, making them more efficient. This has some open design questions, such as how to spawn entities with "default" handle values (as these wouldn't have access to the exchange api in the current system). * **Asset Path Fixup Tooling**: Assets that inline asset paths inside them will break when an asset moves. The asset system provides the functionality to detect when paths break. We should build a framework that enables formats to define "path migrations". This is especially important for scene files. For editor-generated files, we should also consider using UUIDs (see other bullet point) to avoid the need to migrate in these cases. --------- Co-authored-by: BeastLe9enD <beastle9end@outlook.de> Co-authored-by: Mike <mike.hsu@gmail.com> Co-authored-by: Nicola Papale <nicopap@users.noreply.github.com>
2023-09-07 02:07:27 +00:00
[package.metadata.example.asset_processing]
name = "Asset Processing"
description = "Demonstrates how to process and load custom assets"
category = "Assets"
wasm = false
Example with repeated texture (#13176) # Objective Fixes #11136 . Fixes https://github.com/bevyengine/bevy/pull/11161. ## Solution - Set image sampler with repeated mode for u and v - set uv_transform of StandardMaterial to resizing params ## Testing Got this view on example run ![image](https://github.com/bevyengine/bevy/assets/17225606/a5f7c414-7966-4c31-97e1-320241ddc75b)
2024-05-05 17:29:26 +00:00
[[example]]
name = "repeated_texture"
path = "examples/asset/repeated_texture.rs"
doc-scrape-examples = true
[package.metadata.example.repeated_texture]
name = "Repeated texture configuration"
description = "How to configure the texture to repeat instead of the default clamp to edges"
category = "Assets"
wasm = true
Allow `AssetServer::load` to acquire a guard item. (#13051) # Objective Supercedes #12881 . Added a simple implementation that allows the user to react to multiple asset loads both synchronously and asynchronously. ## Solution Added `load_acquire`, that holds an item and drops it when loading is finished or failed. When used synchronously Hold an `Arc<()>`, check for `Arc::strong_count() == 1` when all loading completed. When used asynchronously Hold a `SemaphoreGuard`, await on `acquire_all` for completion. This implementation has more freedom than the original in my opinion. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Zachary Harrold <zac@harrold.com.au>
2024-05-23 13:28:29 +00:00
# Assets
[[example]]
name = "multi_asset_sync"
path = "examples/asset/multi_asset_sync.rs"
doc-scrape-examples = true
[package.metadata.example.multi_asset_sync]
name = "Mult-asset synchronization"
description = "Demonstrates how to wait for multiple assets to be loaded."
category = "Assets"
wasm = true
Example showing how to use AsyncComputeTaskPool and Tasks (#2180)
2021-05-23 20:13:55 +00:00
# Async Tasks
[[example]]
name = "async_compute"
path = "examples/async_tasks/async_compute.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Example showing how to use AsyncComputeTaskPool and Tasks (#2180)
2021-05-23 20:13:55 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.async_compute]
name = "Async Compute"
description = "How to use `AsyncComputeTaskPool` to complete longer running tasks"
category = "Async Tasks"
wasm = false
add examples on how to have a data source running in another thread / in a task pool thread (#2915) Add two examples on how to communicate with a task that is running either in another thread or in a thread from `AsyncComputeTaskPool`. Loosely based on https://github.com/bevyengine/bevy/discussions/1150
2022-02-05 01:52:47 +00:00
[[example]]
name = "external_source_external_thread"
path = "examples/async_tasks/external_source_external_thread.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
add examples on how to have a data source running in another thread / in a task pool thread (#2915) Add two examples on how to communicate with a task that is running either in another thread or in a thread from `AsyncComputeTaskPool`. Loosely based on https://github.com/bevyengine/bevy/discussions/1150
2022-02-05 01:52:47 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.external_source_external_thread]
name = "External Source of Data on an External Thread"
description = "How to use an external thread to run an infinite task and communicate with a channel"
category = "Async Tasks"
wasm = false
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
# Audio
audio: initial (very minimal) audio plugin
2020-07-16 20:46:51 +00:00
[[example]]
name = "audio"
path = "examples/audio/audio.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
audio: initial (very minimal) audio plugin
2020-07-16 20:46:51 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.audio]
name = "Audio"
description = "Shows how to load and play an audio file"
category = "Audio"
wasm = true
Audio control - play, pause, volume, speed, loop (#3948) # Objective - Add ways to control how audio is played ## Solution - playing a sound will return a (weak) handle to an asset that can be used to control playback - if the asset is dropped, it will detach the sink (same behaviour as now)
2022-03-01 01:12:11 +00:00
[[example]]
name = "audio_control"
path = "examples/audio/audio_control.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Audio control - play, pause, volume, speed, loop (#3948) # Objective - Add ways to control how audio is played ## Solution - playing a sound will return a (weak) handle to an asset that can be used to control playback - if the asset is dropped, it will detach the sink (same behaviour as now)
2022-03-01 01:12:11 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.audio_control]
name = "Audio Control"
description = "Shows how to load and play an audio file, and control how it's played"
category = "Audio"
wasm = true
Add `AddAudioSource` trait and improve `Decodable` docs (#6649) # Objective - Fixes #6361 - Fixes #6362 - Fixes #6364 ## Solution - Added an example for creating a custom `Decodable` type - Clarified the documentation on `Decodable` - Added an `AddAudioSource` trait and implemented it for `App` Co-authored-by: dis-da-moe <84386186+dis-da-moe@users.noreply.github.com>
2023-01-17 22:42:00 +00:00
[[example]]
name = "decodable"
path = "examples/audio/decodable.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add `AddAudioSource` trait and improve `Decodable` docs (#6649) # Objective - Fixes #6361 - Fixes #6362 - Fixes #6364 ## Solution - Added an example for creating a custom `Decodable` type - Clarified the documentation on `Decodable` - Added an `AddAudioSource` trait and implemented it for `App` Co-authored-by: dis-da-moe <84386186+dis-da-moe@users.noreply.github.com>
2023-01-17 22:42:00 +00:00
[package.metadata.example.decodable]
name = "Decodable"
description = "Shows how to create and register a custom audio source by implementing the `Decodable` type."
category = "Audio"
wasm = true
Programmed soundtrack example (#12774) Created soundtrack example, fade-in and fade-out features, added new assets, and updated credits. # Objective - Fixes #12651 ## Solution - Created a resource to hold the track list. - The audio assets are then loaded by the asset server and added to the track list. - Once the game is in a specific state, an `AudioBundle` is spawned and plays the appropriate track. - The audio volume starts at zero and is then incremented gradually until it reaches full volume. - Once the game state changes, the current track fades out, and a new one fades in at the same time, offering a relatively seamless transition. - Once a track is completely faded out, it is despawned from the app. - Game state changes are simulated through a `Timer` for simplicity. - Track change system is only run if there is a change in the `GameState` resource. - All tracks are used according to their respective licenses. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2024-03-29 20:32:30 +00:00
[[example]]
name = "soundtrack"
path = "examples/audio/soundtrack.rs"
doc-scrape-examples = true
[package.metadata.example.soundtrack]
name = "Soundtrack"
description = "Shows how to play different soundtracks based on game state"
category = "Audio"
wasm = true
Basic spatial audio (#6028) # Objective - Add basic spatial audio support to Bevy - this is what rodio supports, so no HRTF, just simple stereo channel manipulation - no "built-in" ECS support: `Emitter` and `Listener` should be components that would automatically update the positions This PR goal is to just expose rodio functionality, made possible with the recent update to rodio 0.16. A proper ECS integration opens a lot more questions, and would probably require an RFC Also updates rodio and fixes #6122
2023-02-20 15:31:07 +00:00
[[example]]
name = "spatial_audio_2d"
path = "examples/audio/spatial_audio_2d.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Basic spatial audio (#6028) # Objective - Add basic spatial audio support to Bevy - this is what rodio supports, so no HRTF, just simple stereo channel manipulation - no "built-in" ECS support: `Emitter` and `Listener` should be components that would automatically update the positions This PR goal is to just expose rodio functionality, made possible with the recent update to rodio 0.16. A proper ECS integration opens a lot more questions, and would probably require an RFC Also updates rodio and fixes #6122
2023-02-20 15:31:07 +00:00
[package.metadata.example.spatial_audio_2d]
name = "Spatial Audio 2D"
description = "Shows how to play spatial audio, and moving the emitter in 2D"
category = "Audio"
wasm = true
[[example]]
name = "spatial_audio_3d"
path = "examples/audio/spatial_audio_3d.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Basic spatial audio (#6028) # Objective - Add basic spatial audio support to Bevy - this is what rodio supports, so no HRTF, just simple stereo channel manipulation - no "built-in" ECS support: `Emitter` and `Listener` should be components that would automatically update the positions This PR goal is to just expose rodio functionality, made possible with the recent update to rodio 0.16. A proper ECS integration opens a lot more questions, and would probably require an RFC Also updates rodio and fixes #6122
2023-02-20 15:31:07 +00:00
[package.metadata.example.spatial_audio_3d]
name = "Spatial Audio 3D"
description = "Shows how to play spatial audio, and moving the emitter in 3D"
category = "Audio"
wasm = true
Added Pitch as an alternative sound source (#9225) # Objective My attempt at implementing #7515 ## Solution Added struct `Pitch` and implemented on it `Source` trait. ## Changelog ### Added - File pitch.rs to bevy_audio crate - Struct `Pitch` and type aliases for `AudioSourceBundle<Pitch>` and `SpatialAudioSourceBundle<Pitch>` - New example showing how to use `PitchBundle` ### Changed - `AudioPlugin` now adds system for `Pitch` audio --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2023-07-29 22:29:41 +00:00
[[example]]
name = "pitch"
path = "examples/audio/pitch.rs"
Fix some doc warnings (#12961) # Objective - Fix some doc warnings - Add doc-scrape-examples to all examples Moved from #12692 I run `cargo +nightly doc --workspace --all-features --no-deps -Zunstable-options -Zrustdoc-scrape-examples` <details> ``` warning: public documentation for `GzAssetLoaderError` links to private item `GzAssetLoader` --> examples/asset/asset_decompression.rs:24:47 | 24 | /// Possible errors that can be produced by [`GzAssetLoader`] | ^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: `bevy` (example "asset_decompression") generated 1 warning warning: unresolved link to `shape::Quad` --> examples/2d/mesh2d.rs:3:15 | 3 | //! [`Quad`]: shape::Quad | ^^^^^^^^^^^ no item named `shape` in scope | = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "mesh2d") generated 1 warning warning: unresolved link to `WorldQuery` --> examples/ecs/custom_query_param.rs:1:49 | 1 | //! This example illustrates the usage of the [`WorldQuery`] derive macro, which allows | ^^^^^^^^^^ no item named `WorldQuery` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "custom_query_param") generated 1 warning warning: unresolved link to `shape::Quad` --> examples/2d/mesh2d_vertex_color_texture.rs:4:15 | 4 | //! [`Quad`]: shape::Quad | ^^^^^^^^^^^ no item named `shape` in scope | = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "mesh2d_vertex_color_texture") generated 1 warning warning: public documentation for `TextPlugin` links to private item `CoolText` --> examples/asset/processing/asset_processing.rs:48:9 | 48 | /// * [`CoolText`]: a custom RON text format that supports dependencies and embedded dependencies | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: public documentation for `TextPlugin` links to private item `Text` --> examples/asset/processing/asset_processing.rs:49:9 | 49 | /// * [`Text`]: a "normal" plain text file | ^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: public documentation for `TextPlugin` links to private item `CoolText` --> examples/asset/processing/asset_processing.rs:51:57 | 51 | /// It also defines an asset processor that will load [`CoolText`], resolve embedded dependenc... | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: `bevy` (example "asset_processing") generated 3 warnings warning: public documentation for `CustomAssetLoaderError` links to private item `CustomAssetLoader` --> examples/asset/custom_asset.rs:20:47 | 20 | /// Possible errors that can be produced by [`CustomAssetLoader`] | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: public documentation for `BlobAssetLoaderError` links to private item `CustomAssetLoader` --> examples/asset/custom_asset.rs:61:47 | 61 | /// Possible errors that can be produced by [`CustomAssetLoader`] | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` ``` ``` warning: `bevy` (example "mesh2d") generated 1 warning warning: public documentation for `log_layers_ecs` links to private item `update_subscriber` --> examples/app/log_layers_ecs.rs:6:18 | 6 | //! Inside the [`update_subscriber`] function we will create a [`mpsc::Sender`] and a [`mpsc::R... | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: unresolved link to `AdvancedLayer` --> examples/app/log_layers_ecs.rs:7:72 | 7 | ... will go into the [`AdvancedLayer`] and the [`Receiver`](mpsc::Receiver) will | ^^^^^^^^^^^^^ no item named `AdvancedLayer` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: unresolved link to `LogEvents` --> examples/app/log_layers_ecs.rs:8:42 | 8 | //! go into a non-send resource called [`LogEvents`] (It has to be non-send because [`Receiver`... | ^^^^^^^^^ no item named `LogEvents` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` warning: public documentation for `log_layers_ecs` links to private item `transfer_log_events` --> examples/app/log_layers_ecs.rs:9:30 | 9 | //! From there we will use [`transfer_log_events`] to transfer log events from [`LogEvents`] to... | ^^^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: unresolved link to `LogEvents` --> examples/app/log_layers_ecs.rs:9:82 | 9 | ...nsfer log events from [`LogEvents`] to an ECS event called [`LogEvent`]. | ^^^^^^^^^ no item named `LogEvents` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` warning: public documentation for `log_layers_ecs` links to private item `LogEvent` --> examples/app/log_layers_ecs.rs:9:119 | 9 | ...nts`] to an ECS event called [`LogEvent`]. | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: public documentation for `log_layers_ecs` links to private item `LogEvent` --> examples/app/log_layers_ecs.rs:11:49 | 11 | //! Finally, after all that we can access the [`LogEvent`] event from our systems and use it. | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` ``` <details/>
2024-04-14 15:23:44 +00:00
doc-scrape-examples = true
Added Pitch as an alternative sound source (#9225) # Objective My attempt at implementing #7515 ## Solution Added struct `Pitch` and implemented on it `Source` trait. ## Changelog ### Added - File pitch.rs to bevy_audio crate - Struct `Pitch` and type aliases for `AudioSourceBundle<Pitch>` and `SpatialAudioSourceBundle<Pitch>` - New example showing how to use `PitchBundle` ### Changed - `AudioPlugin` now adds system for `Pitch` audio --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2023-07-29 22:29:41 +00:00
[package.metadata.example.pitch]
name = "Pitch"
description = "Shows how to directly play a simple pitch"
category = "Audio"
wasm = true
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
# Diagnostics
[[example]]
name = "log_diagnostics"
path = "examples/diagnostics/log_diagnostics.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.log_diagnostics]
name = "Log Diagnostics"
description = "Add a plugin that logs diagnostics, like frames per second (FPS), to the console"
category = "Diagnostics"
wasm = true
add diagnostic examples
2020-05-04 21:14:49 +00:00
[[example]]
name = "custom_diagnostic"
path = "examples/diagnostics/custom_diagnostic.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
add diagnostic examples
2020-05-04 21:14:49 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.custom_diagnostic]
name = "Custom Diagnostic"
description = "Shows how to create a custom diagnostic"
category = "Diagnostics"
wasm = true
Add example demonstrating how to enable / disable diagnostics (#14741) # Objective fixes #14569 ## Solution added an example to the diagnostic examples and linked the code to the docs of the diagnostic library itself. ## Testing I tested locally on my laptop in a web browser. Looked fine. You are able to collapse the whole "intro" part of the doc to get to the links sooner (for those who may think that including the example code here is annoying to scroll through) I would like people to run ```cargo doc``` and go the bevy_diagnostic page to see if they have any issues or suggestions. --- ## Showcase <img width="1067" alt="Screenshot 2024-08-14 at 12 52 16" src="https://github.com/user-attachments/assets/70b6c18a-0bb9-4656-ba53-c416f62c6116"> --------- Co-authored-by: dpeke <dpekelis@funstage.com>
2024-08-15 20:54:51 +00:00
[[example]]
name = "enabling_disabling_diagnostic"
path = "examples/diagnostics/enabling_disabling_diagnostic.rs"
doc-scrape-examples = true
[package.metadata.example.enabling_disabling_diagnostic]
name = "Enabling/disabling diagnostic"
description = "Shows how to disable/re-enable a Diagnostic during runtime"
category = "Diagnostics"
wasm = true
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
# ECS (Entity Component System)
add diagnostic examples
2020-05-04 21:14:49 +00:00
[[example]]
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
name = "ecs_guide"
path = "examples/ecs/ecs_guide.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
add diagnostic examples
2020-05-04 21:14:49 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.ecs_guide]
name = "ECS Guide"
description = "Full guide to Bevy's ECS"
category = "ECS (Entity Component System)"
wasm = false
Rename apply_system_buffers to apply_deferred (#8726) # Objective - `apply_system_buffers` is an unhelpful name: it introduces a new internal-only concept - this is particularly rough for beginners as reasoning about how commands work is a critical stumbling block ## Solution - rename `apply_system_buffers` to the more descriptive `apply_deferred` - rename related fields, arguments and methods in the internals fo bevy_ecs for consistency - update the docs ## Changelog `apply_system_buffers` has been renamed to `apply_deferred`, to more clearly communicate its intent and relation to `Deferred` system parameters like `Commands`. ## Migration Guide - `apply_system_buffers` has been renamed to `apply_deferred` - the `apply_system_buffers` method on the `System` trait has been renamed to `apply_deferred` - the `is_apply_system_buffers` function has been replaced by `is_apply_deferred` - `Executor::set_apply_final_buffers` is now `Executor::set_apply_final_deferred` - `Schedule::apply_system_buffers` is now `Schedule::apply_deferred` --------- Co-authored-by: JoJoJet <21144246+JoJoJet@users.noreply.github.com>
2023-06-02 14:04:13 +00:00
[package.metadata.example.apply_deferred]
Add example to show how to use `apply_system_buffers` (#7793) # Objective This PR adds an example that shows how to use `apply_system_buffers` and how to order it with respect to the relevant systems. It also shows how not ordering the systems can lead to unexpected behaviours. ## Solution Add the example.
2023-02-28 00:19:44 +00:00
name = "Apply System Buffers"
Rename apply_system_buffers to apply_deferred (#8726) # Objective - `apply_system_buffers` is an unhelpful name: it introduces a new internal-only concept - this is particularly rough for beginners as reasoning about how commands work is a critical stumbling block ## Solution - rename `apply_system_buffers` to the more descriptive `apply_deferred` - rename related fields, arguments and methods in the internals fo bevy_ecs for consistency - update the docs ## Changelog `apply_system_buffers` has been renamed to `apply_deferred`, to more clearly communicate its intent and relation to `Deferred` system parameters like `Commands`. ## Migration Guide - `apply_system_buffers` has been renamed to `apply_deferred` - the `apply_system_buffers` method on the `System` trait has been renamed to `apply_deferred` - the `is_apply_system_buffers` function has been replaced by `is_apply_deferred` - `Executor::set_apply_final_buffers` is now `Executor::set_apply_final_deferred` - `Schedule::apply_system_buffers` is now `Schedule::apply_deferred` --------- Co-authored-by: JoJoJet <21144246+JoJoJet@users.noreply.github.com>
2023-06-02 14:04:13 +00:00
description = "Show how to use `apply_deferred` system"
Add example to show how to use `apply_system_buffers` (#7793) # Objective This PR adds an example that shows how to use `apply_system_buffers` and how to order it with respect to the relevant systems. It also shows how not ordering the systems can lead to unexpected behaviours. ## Solution Add the example.
2023-02-28 00:19:44 +00:00
category = "ECS (Entity Component System)"
wasm = false
add `Flags<T>` as a query to get flags of component (#1172) add `Flags` as a query to get flags of component
2020-12-31 22:29:08 +00:00
[[example]]
Track source location in change detection (#14034) # Objective - Make it possible to know *what* changed your component or resource. - Common need when debugging, when you want to know the last code location that mutated a value in the ECS. - This feature would be very useful for the editor alongside system stepping. ## Solution - Adds the caller location to column data. - Mutations now `track_caller` all the way up to the public API. - Commands that invoke these functions immediately call `Location::caller`, and pass this into the functions, instead of the functions themselves attempting to get the caller. This would not work for commands which are deferred, as the commands are executed by the scheduler, not the user's code. ## Testing - The `component_change_detection` example now shows where the component was mutated: ``` 2024-07-28T06:57:48.946022Z INFO component_change_detection: Entity { index: 1, generation: 1 }: New value: MyComponent(0.0) 2024-07-28T06:57:49.004371Z INFO component_change_detection: Entity { index: 1, generation: 1 }: New value: MyComponent(1.0) 2024-07-28T06:57:49.012738Z WARN component_change_detection: Change detected! -> value: Ref(MyComponent(1.0)) -> added: false -> changed: true -> changed by: examples/ecs/component_change_detection.rs:36:23 ``` - It's also possible to inspect change location from a debugger: <img width="608" alt="image" src="https://github.com/user-attachments/assets/c90ecc7a-0462-457a-80ae-42e7f5d346b4"> --- ## Changelog - Added source locations to ECS change detection behind the `track_change_detection` flag. ## Migration Guide - Added `changed_by` field to many internal ECS functions used with change detection when the `track_change_detection` feature flag is enabled. Use Location::caller() to provide the source of the function call. --------- Co-authored-by: BD103 <59022059+BD103@users.noreply.github.com> Co-authored-by: Gino Valente <49806985+MrGVSV@users.noreply.github.com>
2024-07-30 12:02:38 +00:00
name = "change_detection"
path = "examples/ecs/change_detection.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Track source location in change detection (#14034) # Objective - Make it possible to know *what* changed your component or resource. - Common need when debugging, when you want to know the last code location that mutated a value in the ECS. - This feature would be very useful for the editor alongside system stepping. ## Solution - Adds the caller location to column data. - Mutations now `track_caller` all the way up to the public API. - Commands that invoke these functions immediately call `Location::caller`, and pass this into the functions, instead of the functions themselves attempting to get the caller. This would not work for commands which are deferred, as the commands are executed by the scheduler, not the user's code. ## Testing - The `component_change_detection` example now shows where the component was mutated: ``` 2024-07-28T06:57:48.946022Z INFO component_change_detection: Entity { index: 1, generation: 1 }: New value: MyComponent(0.0) 2024-07-28T06:57:49.004371Z INFO component_change_detection: Entity { index: 1, generation: 1 }: New value: MyComponent(1.0) 2024-07-28T06:57:49.012738Z WARN component_change_detection: Change detected! -> value: Ref(MyComponent(1.0)) -> added: false -> changed: true -> changed by: examples/ecs/component_change_detection.rs:36:23 ``` - It's also possible to inspect change location from a debugger: <img width="608" alt="image" src="https://github.com/user-attachments/assets/c90ecc7a-0462-457a-80ae-42e7f5d346b4"> --- ## Changelog - Added source locations to ECS change detection behind the `track_change_detection` flag. ## Migration Guide - Added `changed_by` field to many internal ECS functions used with change detection when the `track_change_detection` feature flag is enabled. Use Location::caller() to provide the source of the function call. --------- Co-authored-by: BD103 <59022059+BD103@users.noreply.github.com> Co-authored-by: Gino Valente <49806985+MrGVSV@users.noreply.github.com>
2024-07-30 12:02:38 +00:00
required-features = ["track_change_detection"]
add `Flags<T>` as a query to get flags of component (#1172) add `Flags` as a query to get flags of component
2020-12-31 22:29:08 +00:00
Track source location in change detection (#14034) # Objective - Make it possible to know *what* changed your component or resource. - Common need when debugging, when you want to know the last code location that mutated a value in the ECS. - This feature would be very useful for the editor alongside system stepping. ## Solution - Adds the caller location to column data. - Mutations now `track_caller` all the way up to the public API. - Commands that invoke these functions immediately call `Location::caller`, and pass this into the functions, instead of the functions themselves attempting to get the caller. This would not work for commands which are deferred, as the commands are executed by the scheduler, not the user's code. ## Testing - The `component_change_detection` example now shows where the component was mutated: ``` 2024-07-28T06:57:48.946022Z INFO component_change_detection: Entity { index: 1, generation: 1 }: New value: MyComponent(0.0) 2024-07-28T06:57:49.004371Z INFO component_change_detection: Entity { index: 1, generation: 1 }: New value: MyComponent(1.0) 2024-07-28T06:57:49.012738Z WARN component_change_detection: Change detected! -> value: Ref(MyComponent(1.0)) -> added: false -> changed: true -> changed by: examples/ecs/component_change_detection.rs:36:23 ``` - It's also possible to inspect change location from a debugger: <img width="608" alt="image" src="https://github.com/user-attachments/assets/c90ecc7a-0462-457a-80ae-42e7f5d346b4"> --- ## Changelog - Added source locations to ECS change detection behind the `track_change_detection` flag. ## Migration Guide - Added `changed_by` field to many internal ECS functions used with change detection when the `track_change_detection` feature flag is enabled. Use Location::caller() to provide the source of the function call. --------- Co-authored-by: BD103 <59022059+BD103@users.noreply.github.com> Co-authored-by: Gino Valente <49806985+MrGVSV@users.noreply.github.com>
2024-07-30 12:02:38 +00:00
[package.metadata.example.change_detection]
name = "Change Detection"
description = "Change detection on components and resources"
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
category = "ECS (Entity Component System)"
wasm = false
Component Lifecycle Hooks and a Deferred World (#10756) # Objective - Provide a reliable and performant mechanism to allows users to keep components synchronized with external sources: closing/opening sockets, updating indexes, debugging etc. - Implement a generic mechanism to provide mutable access to the world without allowing structural changes; this will not only be used here but is a foundational piece for observers, which are key for a performant implementation of relations. ## Solution - Implement a new type `DeferredWorld` (naming is not important, `StaticWorld` is also suitable) that wraps a world pointer and prevents user code from making any structural changes to the ECS; spawning entities, creating components, initializing resources etc. - Add component lifecycle hooks `on_add`, `on_insert` and `on_remove` that can be assigned callbacks in user code. --- ## Changelog - Add new `DeferredWorld` type. - Add new world methods: `register_component::<T>` and `register_component_with_descriptor`. These differ from `init_component` in that they provide mutable access to the created `ComponentInfo` but will panic if the component is already in any archetypes. These restrictions serve two purposes: 1. Prevent users from defining hooks for components that may already have associated hooks provided in another plugin. (a use case better served by observers) 2. Ensure that when an `Archetype` is created it gets the appropriate flags to early-out when triggering hooks. - Add methods to `ComponentInfo`: `on_add`, `on_insert` and `on_remove` to be used to register hooks of the form `fn(DeferredWorld, Entity, ComponentId)` - Modify `BundleInserter`, `BundleSpawner` and `EntityWorldMut` to trigger component hooks when appropriate. - Add bit flags to `Archetype` indicating whether or not any contained components have each type of hook, this can be expanded for other flags as needed. - Add `component_hooks` example to illustrate usage. Try it out! It's fun to mash keys. ## Safety The changes to component insertion, removal and deletion involve a large amount of unsafe code and it's fair for that to raise some concern. I have attempted to document it as clearly as possible and have confirmed that all the hooks examples are accepted by `cargo miri` as not causing any undefined behavior. The largest issue is in ensuring there are no outstanding references when passing a `DeferredWorld` to the hooks which requires some use of raw pointers (as was already happening to some degree in those places) and I have taken some time to ensure that is the case but feel free to let me know if I've missed anything. ## Performance These changes come with a small but measurable performance cost of between 1-5% on `add_remove` benchmarks and between 1-3% on `insert` benchmarks. One consideration to be made is the existence of the current `RemovedComponents` which is on average more costly than the addition of `on_remove` hooks due to the early-out, however hooks doesn't completely remove the need for `RemovedComponents` as there is a chance you want to respond to the removal of a component that already has an `on_remove` hook defined in another plugin, so I have not removed it here. I do intend to deprecate it with the introduction of observers in a follow up PR. ## Discussion Questions - Currently `DeferredWorld` implements `Deref` to `&World` which makes sense conceptually, however it does cause some issues with rust-analyzer providing autocomplete for `&mut World` references which is annoying. There are alternative implementations that may address this but involve more code churn so I have attempted them here. The other alternative is to not implement `Deref` at all but that leads to a large amount of API duplication. - `DeferredWorld`, `StaticWorld`, something else? - In adding support for hooks to `EntityWorldMut` I encountered some unfortunate difficulties with my desired API. If commands are flushed after each call i.e. `world.spawn() // flush commands .insert(A) // flush commands` the entity may be despawned while `EntityWorldMut` still exists which is invalid. An alternative was then to add `self.world.flush_commands()` to the drop implementation for `EntityWorldMut` but that runs into other problems for implementing functions like `into_unsafe_entity_cell`. For now I have implemented a `.flush()` which will flush the commands and consume `EntityWorldMut` or users can manually run `world.flush_commands()` after using `EntityWorldMut`. - In order to allowing querying on a deferred world we need implementations of `WorldQuery` to not break our guarantees of no structural changes through their `UnsafeWorldCell`. All our implementations do this, but there isn't currently any safety documentation specifying what is or isn't allowed for an implementation, just for the caller, (they also shouldn't be aliasing components they didn't specify access for etc.) is that something we should start doing? (see 10752) Please check out the example `component_hooks` or the tests in `bundle.rs` for usage examples. I will continue to expand this description as I go. See #10839 for a more ergonomic API built on top of this one that isn't subject to the same restrictions and supports `SystemParam` dependency injection.
2024-03-01 14:59:22 +00:00
[[example]]
name = "component_hooks"
path = "examples/ecs/component_hooks.rs"
doc-scrape-examples = true
[package.metadata.example.component_hooks]
name = "Component Hooks"
description = "Define component hooks to manage component lifecycle events"
category = "ECS (Entity Component System)"
wasm = false
Add custom schedule example (#11527) # Objective Fixes #11411 ## Solution - Added a simple example how to create and configure custom schedules that are run by the `Main` schedule. - Spot checked some of the API docs used, fixed `App::add_schedule` docs that referred to a function argument that was removed by #9600. ## Open Questions - While spot checking the docs, I noticed that the `Schedule` label is stored in a field called `name` instead of `label`. This seems unintuitive since the term label is used everywhere else. Should we change that field name? It was introduced in #9600. If so, I do think this change would be out of scope for this PR that mainly adds the example.
2024-01-25 17:51:53 +00:00
[[example]]
name = "custom_schedule"
path = "examples/ecs/custom_schedule.rs"
doc-scrape-examples = true
[package.metadata.example.custom_schedule]
name = "Custom Schedule"
description = "Demonstrates how to add custom schedules"
category = "ECS (Entity Component System)"
wasm = false
Implement `WorldQuery` derive macro (#2713) # Objective - Closes #786 - Closes #2252 - Closes #2588 This PR implements a derive macro that allows users to define their queries as structs with named fields. ## Example ```rust #[derive(WorldQuery)] #[world_query(derive(Debug))] struct NumQuery<'w, T: Component, P: Component> { entity: Entity, u: UNumQuery<'w>, generic: GenericQuery<'w, T, P>, } #[derive(WorldQuery)] #[world_query(derive(Debug))] struct UNumQuery<'w> { u_16: &'w u16, u_32_opt: Option<&'w u32>, } #[derive(WorldQuery)] #[world_query(derive(Debug))] struct GenericQuery<'w, T: Component, P: Component> { generic: (&'w T, &'w P), } #[derive(WorldQuery)] #[world_query(filter)] struct NumQueryFilter<T: Component, P: Component> { _u_16: With<u16>, _u_32: With<u32>, _or: Or<(With<i16>, Changed<u16>, Added<u32>)>, _generic_tuple: (With<T>, With<P>), _without: Without<Option<u16>>, _tp: PhantomData<(T, P)>, } fn print_nums_readonly(query: Query<NumQuery<u64, i64>, NumQueryFilter<u64, i64>>) { for num in query.iter() { println!("{:#?}", num); } } #[derive(WorldQuery)] #[world_query(mutable, derive(Debug))] struct MutNumQuery<'w, T: Component, P: Component> { i_16: &'w mut i16, i_32_opt: Option<&'w mut i32>, } fn print_nums(mut query: Query<MutNumQuery, NumQueryFilter<u64, i64>>) { for num in query.iter_mut() { println!("{:#?}", num); } } ``` ## TODOs: - [x] Add support for `&T` and `&mut T` - [x] Test - [x] Add support for optional types - [x] Test - [x] Add support for `Entity` - [x] Test - [x] Add support for nested `WorldQuery` - [x] Test - [x] Add support for tuples - [x] Test - [x] Add support for generics - [x] Test - [x] Add support for query filters - [x] Test - [x] Add support for `PhantomData` - [x] Test - [x] Refactor `read_world_query_field_type_info` - [x] Properly document `readonly` attribute for nested queries and the static assertions that guarantee safety - [x] Test that we never implement `ReadOnlyFetch` for types that need mutable access - [x] Test that we insert static assertions for nested `WorldQuery` that a user marked as readonly
2022-02-24 00:19:49 +00:00
[[example]]
name = "custom_query_param"
path = "examples/ecs/custom_query_param.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Implement `WorldQuery` derive macro (#2713) # Objective - Closes #786 - Closes #2252 - Closes #2588 This PR implements a derive macro that allows users to define their queries as structs with named fields. ## Example ```rust #[derive(WorldQuery)] #[world_query(derive(Debug))] struct NumQuery<'w, T: Component, P: Component> { entity: Entity, u: UNumQuery<'w>, generic: GenericQuery<'w, T, P>, } #[derive(WorldQuery)] #[world_query(derive(Debug))] struct UNumQuery<'w> { u_16: &'w u16, u_32_opt: Option<&'w u32>, } #[derive(WorldQuery)] #[world_query(derive(Debug))] struct GenericQuery<'w, T: Component, P: Component> { generic: (&'w T, &'w P), } #[derive(WorldQuery)] #[world_query(filter)] struct NumQueryFilter<T: Component, P: Component> { _u_16: With<u16>, _u_32: With<u32>, _or: Or<(With<i16>, Changed<u16>, Added<u32>)>, _generic_tuple: (With<T>, With<P>), _without: Without<Option<u16>>, _tp: PhantomData<(T, P)>, } fn print_nums_readonly(query: Query<NumQuery<u64, i64>, NumQueryFilter<u64, i64>>) { for num in query.iter() { println!("{:#?}", num); } } #[derive(WorldQuery)] #[world_query(mutable, derive(Debug))] struct MutNumQuery<'w, T: Component, P: Component> { i_16: &'w mut i16, i_32_opt: Option<&'w mut i32>, } fn print_nums(mut query: Query<MutNumQuery, NumQueryFilter<u64, i64>>) { for num in query.iter_mut() { println!("{:#?}", num); } } ``` ## TODOs: - [x] Add support for `&T` and `&mut T` - [x] Test - [x] Add support for optional types - [x] Test - [x] Add support for `Entity` - [x] Test - [x] Add support for nested `WorldQuery` - [x] Test - [x] Add support for tuples - [x] Test - [x] Add support for generics - [x] Test - [x] Add support for query filters - [x] Test - [x] Add support for `PhantomData` - [x] Test - [x] Refactor `read_world_query_field_type_info` - [x] Properly document `readonly` attribute for nested queries and the static assertions that guarantee safety - [x] Test that we never implement `ReadOnlyFetch` for types that need mutable access - [x] Test that we insert static assertions for nested `WorldQuery` that a user marked as readonly
2022-02-24 00:19:49 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.custom_query_param]
name = "Custom Query Parameters"
description = "Groups commonly used compound queries and query filters into a single type"
category = "ECS (Entity Component System)"
wasm = false
Dynamic queries and builder API (#9774) # Objective Expand the existing `Query` API to support more dynamic use cases i.e. scripting. ## Prior Art - #6390 - #8308 - #10037 ## Solution - Create a `QueryBuilder` with runtime methods to define the set of component accesses for a built query. - Create new `WorldQueryData` implementations `FilteredEntityMut` and `FilteredEntityRef` as variants of `EntityMut` and `EntityRef` that provide run time checked access to the components included in a given query. - Add new methods to `Query` to create "query lens" with a subset of the access of the initial query. ### Query Builder The `QueryBuilder` API allows you to define a query at runtime. At it's most basic use it will simply create a query with the corresponding type signature: ```rust let query = QueryBuilder::<Entity, With<A>>::new(&mut world).build(); // is equivalent to let query = QueryState::<Entity, With<A>>::new(&mut world); ``` Before calling `.build()` you also have the opportunity to add additional accesses and filters. Here is a simple example where we add additional filter terms: ```rust let entity_a = world.spawn((A(0), B(0))).id(); let entity_b = world.spawn((A(0), C(0))).id(); let mut query_a = QueryBuilder::<Entity>::new(&mut world) .with::<A>() .without::<C>() .build(); assert_eq!(entity_a, query_a.single(&world)); ``` This alone is useful in that allows you to decide which archetypes your query will match at runtime. However it is also very limited, consider a case like the following: ```rust let query_a = QueryBuilder::<&A>::new(&mut world) // Add an additional access .data::<&B>() .build(); ``` This will grant the query an additional read access to component B however we have no way of accessing the data while iterating as the type signature still only includes &A. For an even more concrete example of this consider dynamic components: ```rust let query_a = QueryBuilder::<Entity>::new(&mut world) // Adding a filter is easy since it doesn't need be read later .with_id(component_id_a) // How do I access the data of this component? .ref_id(component_id_b) .build(); ``` With this in mind the `QueryBuilder` API seems somewhat incomplete by itself, we need some way method of accessing the components dynamically. So here's one: ### Query Transmutation If the problem is not having the component in the type signature why not just add it? This PR also adds transmute methods to `QueryBuilder` and `QueryState`. Here's a simple example: ```rust world.spawn(A(0)); world.spawn((A(1), B(0))); let mut query = QueryBuilder::<()>::new(&mut world) .with::<B>() .transmute::<&A>() .build(); query.iter(&world).for_each(|a| assert_eq!(a.0, 1)); ``` The `QueryState` and `QueryBuilder` transmute methods look quite similar but are different in one respect. Transmuting a builder will always succeed as it will just add the additional accesses needed for the new terms if they weren't already included. Transmuting a `QueryState` will panic in the case that the new type signature would give it access it didn't already have, for example: ```rust let query = QueryState::<&A, Option<&B>>::new(&mut world); /// This is fine, the access for Option<&A> is less restrictive than &A query.transmute::<Option<&A>>(&world); /// Oh no, this would allow access to &B on entities that might not have it, so it panics query.transmute::<&B>(&world); /// This is right out query.transmute::<&C>(&world); ``` This is quite an appealing API to also have available on `Query` however it does pose one additional wrinkle: In order to to change the iterator we need to create a new `QueryState` to back it. `Query` doesn't own it's own state though, it just borrows it, so we need a place to borrow it from. This is why `QueryLens` exists, it is a place to store the new state so it can be borrowed when you call `.query()` leaving you with an API like this: ```rust fn function_that_takes_a_query(query: &Query<&A>) { // ... } fn system(query: Query<(&A, &B)>) { let lens = query.transmute_lens::<&A>(); let q = lens.query(); function_that_takes_a_query(&q); } ``` Now you may be thinking: Hey, wait a second, you introduced the problem with dynamic components and then described a solution that only works for static components! Ok, you got me, I guess we need a bit more: ### Filtered Entity References Currently the only way you can access dynamic components on entities through a query is with either `EntityMut` or `EntityRef`, however these can access all components and so conflict with all other accesses. This PR introduces `FilteredEntityMut` and `FilteredEntityRef` as alternatives that have additional runtime checking to prevent accessing components that you shouldn't. This way you can build a query with a `QueryBuilder` and actually access the components you asked for: ```rust let mut query = QueryBuilder::<FilteredEntityRef>::new(&mut world) .ref_id(component_id_a) .with(component_id_b) .build(); let entity_ref = query.single(&world); // Returns Some(Ptr) as we have that component and are allowed to read it let a = entity_ref.get_by_id(component_id_a); // Will return None even though the entity does have the component, as we are not allowed to read it let b = entity_ref.get_by_id(component_id_b); ``` For the most part these new structs have the exact same methods as their non-filtered equivalents. Putting all of this together we can do some truly dynamic ECS queries, check out the `dynamic` example to see it in action: ``` Commands: comp, c Create new components spawn, s Spawn entities query, q Query for entities Enter a command with no parameters for usage. > c A, B, C, Data 4 Component A created with id: 0 Component B created with id: 1 Component C created with id: 2 Component Data created with id: 3 > s A, B, Data 1 Entity spawned with id: 0v0 > s A, C, Data 0 Entity spawned with id: 1v0 > q &Data 0v0: Data: [1, 0, 0, 0] 1v0: Data: [0, 0, 0, 0] > q B, &mut Data 0v0: Data: [2, 1, 1, 1] > q B || C, &Data 0v0: Data: [2, 1, 1, 1] 1v0: Data: [0, 0, 0, 0] ``` ## Changelog - Add new `transmute_lens` methods to `Query`. - Add new types `QueryBuilder`, `FilteredEntityMut`, `FilteredEntityRef` and `QueryLens` - `update_archetype_component_access` has been removed, archetype component accesses are now determined by the accesses set in `update_component_access` - Added method `set_access` to `WorldQuery`, this is called before `update_component_access` for queries that have a restricted set of accesses, such as those built by `QueryBuilder` or `QueryLens`. This is primarily used by the `FilteredEntity*` variants and has an empty trait implementation. - Added method `get_state` to `WorldQuery` as a fallible version of `init_state` when you don't have `&mut World` access. ## Future Work Improve performance of `FilteredEntityMut` and `FilteredEntityRef`, currently they have to determine the accesses a query has in a given archetype during iteration which is far from ideal, especially since we already did the work when matching the archetype in the first place. To avoid making more internal API changes I have left it out of this PR. --------- Co-authored-by: Mike Hsu <mike.hsu@gmail.com>
2024-01-16 19:16:49 +00:00
[[example]]
name = "dynamic"
path = "examples/ecs/dynamic.rs"
doc-scrape-examples = true
[package.metadata.example.dynamic]
name = "Dynamic ECS"
description = "Dynamically create components, spawn entities with those components and query those components"
category = "ECS (Entity Component System)"
wasm = false
organize examples and add ecs guide
2020-05-01 20:12:47 +00:00
[[example]]
name = "event"
path = "examples/ecs/event.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
organize examples and add ecs guide
2020-05-01 20:12:47 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.event]
name = "Event"
description = "Illustrates event creation, activation, and reception"
category = "ECS (Entity Component System)"
wasm = false
Add an example demonstrating how to send and receive events in the same system (#11574) # Objective - Sending and receiving events of the same type in the same system is a reasonably common need, generally due to event filtering. - However, actually doing so is non-trivial, as the borrow checker simultaneous hates mutable and immutable access. ## Solution - Demonstrate two sensible patterns for doing so. - Update the `ManualEventReader` docs to be more clear and link to this example. --------- Co-authored-by: Alice Cecile <alice.i.cecil@gmail.com> Co-authored-by: Joona Aalto <jondolf.dev@gmail.com> Co-authored-by: ickk <git@ickk.io>
2024-01-29 16:41:27 +00:00
[[example]]
name = "send_and_receive_events"
path = "examples/ecs/send_and_receive_events.rs"
doc-scrape-examples = true
[package.metadata.example.send_and_receive_events]
name = "Send and receive events"
description = "Demonstrates how to send and receive events of the same type in a single system"
category = "ECS (Entity Component System)"
wasm = false
Schedule v2 (#1021) Schedule V2
2020-12-13 02:04:42 +00:00
[[example]]
name = "fixed_timestep"
path = "examples/ecs/fixed_timestep.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Schedule v2 (#1021) Schedule V2
2020-12-13 02:04:42 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.fixed_timestep]
name = "Fixed Timestep"
description = "Shows how to create systems that run every fixed timestep, rather than every tick"
category = "ECS (Entity Component System)"
wasm = false
Add generic systems example (#2636) # Objective My attempt at fixing #2142. My very first attempt at contributing to Bevy so more than open to any feedback. I borrowed heavily from the [Bevy Cheatbook page](https://bevy-cheatbook.github.io/patterns/generic-systems.html?highlight=generic#generic-systems). ## Solution Fairly straightforward example using a clean up system to delete entities that are coupled with app state after exiting that state. Co-authored-by: B-Janson <brandon@canva.com>
2022-02-08 16:24:46 +00:00
[[example]]
name = "generic_system"
path = "examples/ecs/generic_system.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add generic systems example (#2636) # Objective My attempt at fixing #2142. My very first attempt at contributing to Bevy so more than open to any feedback. I borrowed heavily from the [Bevy Cheatbook page](https://bevy-cheatbook.github.io/patterns/generic-systems.html?highlight=generic#generic-systems). ## Solution Fairly straightforward example using a clean up system to delete entities that are coupled with app state after exiting that state. Co-authored-by: B-Janson <brandon@canva.com>
2022-02-08 16:24:46 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.generic_system]
name = "Generic System"
description = "Shows how to create systems that can be reused with different types"
category = "ECS (Entity Component System)"
wasm = false
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
[[example]]
name = "hierarchy"
path = "examples/ecs/hierarchy.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.hierarchy]
name = "Hierarchy"
description = "Creates a hierarchy of parents and children entities"
category = "ECS (Entity Component System)"
wasm = false
Add a method `iter_combinations` on query to iterate over combinations of query results (#1763) Related to [discussion on discord](https://discord.com/channels/691052431525675048/742569353878437978/824731187724681289) With const generics, it is now possible to write generic iterator over multiple entities at once. This enables patterns of query iterations like ```rust for [e1, e2, e3] in query.iter_combinations() { // do something with relation of all three entities } ``` The compiler is able to infer the correct iterator for given size of array, so either of those work ```rust for [e1, e2] in query.iter_combinations() { ... } for [e1, e2, e3] in query.iter_combinations() { ... } ``` This feature can be very useful for systems like collision detection. When you ask for permutations of size K of N entities: - if K == N, you get one result of all entities - if K < N, you get all possible subsets of N with size K, without repetition - if K > N, the result set is empty (no permutation of size K exist) Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2021-05-17 23:33:47 +00:00
[[example]]
name = "iter_combinations"
path = "examples/ecs/iter_combinations.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add a method `iter_combinations` on query to iterate over combinations of query results (#1763) Related to [discussion on discord](https://discord.com/channels/691052431525675048/742569353878437978/824731187724681289) With const generics, it is now possible to write generic iterator over multiple entities at once. This enables patterns of query iterations like ```rust for [e1, e2, e3] in query.iter_combinations() { // do something with relation of all three entities } ``` The compiler is able to infer the correct iterator for given size of array, so either of those work ```rust for [e1, e2] in query.iter_combinations() { ... } for [e1, e2, e3] in query.iter_combinations() { ... } ``` This feature can be very useful for systems like collision detection. When you ask for permutations of size K of N entities: - if K == N, you get one result of all entities - if K < N, you get all possible subsets of N with size K, without repetition - if K > N, the result set is empty (no permutation of size K exist) Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2021-05-17 23:33:47 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.iter_combinations]
name = "Iter Combinations"
description = "Shows how to iterate over combinations of query results"
category = "ECS (Entity Component System)"
wasm = true
One Shot Systems (#8963) I'm adopting this ~~child~~ PR. # Objective - Working with exclusive world access is not always easy: in many cases, a standard system or three is more ergonomic to write, and more modularly maintainable. - For small, one-off tasks (commonly handled with scripting), running an event-reader system incurs a small but flat overhead cost and muddies the schedule. - Certain forms of logic (e.g. turn-based games) want very fine-grained linear and/or branching control over logic. - SystemState is not automatically cached, and so performance can suffer and change detection breaks. - Fixes https://github.com/bevyengine/bevy/issues/2192. - Partial workaround for https://github.com/bevyengine/bevy/issues/279. ## Solution - Adds a SystemRegistry resource to the World, which stores initialized systems keyed by their SystemSet. - Allows users to call world.run_system(my_system) and commands.run_system(my_system), without re-initializing or losing state (essential for change detection). - Add a Callback type to enable convenient use of dynamic one shot systems and reduce the mental overhead of working with Box<dyn SystemSet>. - Allow users to run systems based on their SystemSet, enabling more complex user-made abstractions. ## Future work - Parameterized one-shot systems would improve reusability and bring them closer to events and commands. The API could be something like run_system_with_input(my_system, my_input) and use the In SystemParam. - We should evaluate the unification of commands and one-shot systems since they are two different ways to run logic on demand over a World. ### Prior attempts - https://github.com/bevyengine/bevy/pull/2234 - https://github.com/bevyengine/bevy/pull/2417 - https://github.com/bevyengine/bevy/pull/4090 - https://github.com/bevyengine/bevy/pull/7999 This PR continues the work done in https://github.com/bevyengine/bevy/pull/7999. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Federico Rinaldi <gisquerin@gmail.com> Co-authored-by: MinerSebas <66798382+MinerSebas@users.noreply.github.com> Co-authored-by: Aevyrie <aevyrie@gmail.com> Co-authored-by: Alejandro Pascual Pozo <alejandro.pascual.pozo@gmail.com> Co-authored-by: Rob Parrett <robparrett@gmail.com> Co-authored-by: François <mockersf@gmail.com> Co-authored-by: Dmytro Banin <banind@cs.washington.edu> Co-authored-by: James Liu <contact@jamessliu.com>
2023-09-19 20:17:05 +00:00
[[example]]
name = "one_shot_systems"
path = "examples/ecs/one_shot_systems.rs"
Fix some doc warnings (#12961) # Objective - Fix some doc warnings - Add doc-scrape-examples to all examples Moved from #12692 I run `cargo +nightly doc --workspace --all-features --no-deps -Zunstable-options -Zrustdoc-scrape-examples` <details> ``` warning: public documentation for `GzAssetLoaderError` links to private item `GzAssetLoader` --> examples/asset/asset_decompression.rs:24:47 | 24 | /// Possible errors that can be produced by [`GzAssetLoader`] | ^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: `bevy` (example "asset_decompression") generated 1 warning warning: unresolved link to `shape::Quad` --> examples/2d/mesh2d.rs:3:15 | 3 | //! [`Quad`]: shape::Quad | ^^^^^^^^^^^ no item named `shape` in scope | = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "mesh2d") generated 1 warning warning: unresolved link to `WorldQuery` --> examples/ecs/custom_query_param.rs:1:49 | 1 | //! This example illustrates the usage of the [`WorldQuery`] derive macro, which allows | ^^^^^^^^^^ no item named `WorldQuery` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "custom_query_param") generated 1 warning warning: unresolved link to `shape::Quad` --> examples/2d/mesh2d_vertex_color_texture.rs:4:15 | 4 | //! [`Quad`]: shape::Quad | ^^^^^^^^^^^ no item named `shape` in scope | = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "mesh2d_vertex_color_texture") generated 1 warning warning: public documentation for `TextPlugin` links to private item `CoolText` --> examples/asset/processing/asset_processing.rs:48:9 | 48 | /// * [`CoolText`]: a custom RON text format that supports dependencies and embedded dependencies | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: public documentation for `TextPlugin` links to private item `Text` --> examples/asset/processing/asset_processing.rs:49:9 | 49 | /// * [`Text`]: a "normal" plain text file | ^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: public documentation for `TextPlugin` links to private item `CoolText` --> examples/asset/processing/asset_processing.rs:51:57 | 51 | /// It also defines an asset processor that will load [`CoolText`], resolve embedded dependenc... | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: `bevy` (example "asset_processing") generated 3 warnings warning: public documentation for `CustomAssetLoaderError` links to private item `CustomAssetLoader` --> examples/asset/custom_asset.rs:20:47 | 20 | /// Possible errors that can be produced by [`CustomAssetLoader`] | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: public documentation for `BlobAssetLoaderError` links to private item `CustomAssetLoader` --> examples/asset/custom_asset.rs:61:47 | 61 | /// Possible errors that can be produced by [`CustomAssetLoader`] | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` ``` ``` warning: `bevy` (example "mesh2d") generated 1 warning warning: public documentation for `log_layers_ecs` links to private item `update_subscriber` --> examples/app/log_layers_ecs.rs:6:18 | 6 | //! Inside the [`update_subscriber`] function we will create a [`mpsc::Sender`] and a [`mpsc::R... | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: unresolved link to `AdvancedLayer` --> examples/app/log_layers_ecs.rs:7:72 | 7 | ... will go into the [`AdvancedLayer`] and the [`Receiver`](mpsc::Receiver) will | ^^^^^^^^^^^^^ no item named `AdvancedLayer` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: unresolved link to `LogEvents` --> examples/app/log_layers_ecs.rs:8:42 | 8 | //! go into a non-send resource called [`LogEvents`] (It has to be non-send because [`Receiver`... | ^^^^^^^^^ no item named `LogEvents` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` warning: public documentation for `log_layers_ecs` links to private item `transfer_log_events` --> examples/app/log_layers_ecs.rs:9:30 | 9 | //! From there we will use [`transfer_log_events`] to transfer log events from [`LogEvents`] to... | ^^^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: unresolved link to `LogEvents` --> examples/app/log_layers_ecs.rs:9:82 | 9 | ...nsfer log events from [`LogEvents`] to an ECS event called [`LogEvent`]. | ^^^^^^^^^ no item named `LogEvents` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` warning: public documentation for `log_layers_ecs` links to private item `LogEvent` --> examples/app/log_layers_ecs.rs:9:119 | 9 | ...nts`] to an ECS event called [`LogEvent`]. | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: public documentation for `log_layers_ecs` links to private item `LogEvent` --> examples/app/log_layers_ecs.rs:11:49 | 11 | //! Finally, after all that we can access the [`LogEvent`] event from our systems and use it. | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` ``` <details/>
2024-04-14 15:23:44 +00:00
doc-scrape-examples = true
One Shot Systems (#8963) I'm adopting this ~~child~~ PR. # Objective - Working with exclusive world access is not always easy: in many cases, a standard system or three is more ergonomic to write, and more modularly maintainable. - For small, one-off tasks (commonly handled with scripting), running an event-reader system incurs a small but flat overhead cost and muddies the schedule. - Certain forms of logic (e.g. turn-based games) want very fine-grained linear and/or branching control over logic. - SystemState is not automatically cached, and so performance can suffer and change detection breaks. - Fixes https://github.com/bevyengine/bevy/issues/2192. - Partial workaround for https://github.com/bevyengine/bevy/issues/279. ## Solution - Adds a SystemRegistry resource to the World, which stores initialized systems keyed by their SystemSet. - Allows users to call world.run_system(my_system) and commands.run_system(my_system), without re-initializing or losing state (essential for change detection). - Add a Callback type to enable convenient use of dynamic one shot systems and reduce the mental overhead of working with Box<dyn SystemSet>. - Allow users to run systems based on their SystemSet, enabling more complex user-made abstractions. ## Future work - Parameterized one-shot systems would improve reusability and bring them closer to events and commands. The API could be something like run_system_with_input(my_system, my_input) and use the In SystemParam. - We should evaluate the unification of commands and one-shot systems since they are two different ways to run logic on demand over a World. ### Prior attempts - https://github.com/bevyengine/bevy/pull/2234 - https://github.com/bevyengine/bevy/pull/2417 - https://github.com/bevyengine/bevy/pull/4090 - https://github.com/bevyengine/bevy/pull/7999 This PR continues the work done in https://github.com/bevyengine/bevy/pull/7999. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Federico Rinaldi <gisquerin@gmail.com> Co-authored-by: MinerSebas <66798382+MinerSebas@users.noreply.github.com> Co-authored-by: Aevyrie <aevyrie@gmail.com> Co-authored-by: Alejandro Pascual Pozo <alejandro.pascual.pozo@gmail.com> Co-authored-by: Rob Parrett <robparrett@gmail.com> Co-authored-by: François <mockersf@gmail.com> Co-authored-by: Dmytro Banin <banind@cs.washington.edu> Co-authored-by: James Liu <contact@jamessliu.com>
2023-09-19 20:17:05 +00:00
[package.metadata.example.one_shot_systems]
name = "One Shot Systems"
description = "Shows how to flexibly run systems without scheduling them"
category = "ECS (Entity Component System)"
wasm = false
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
[[example]]
name = "parallel_query"
path = "examples/ecs/parallel_query.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.parallel_query]
name = "Parallel Query"
description = "Illustrates parallel queries with `ParallelIterator`"
category = "ECS (Entity Component System)"
wasm = false
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
[[example]]
name = "removal_detection"
path = "examples/ecs/removal_detection.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.removal_detection]
name = "Removal Detection"
Migrate engine to Schedule v3 (#7267) Huge thanks to @maniwani, @devil-ira, @hymm, @cart, @superdump and @jakobhellermann for the help with this PR. # Objective - Followup #6587. - Minimal integration for the Stageless Scheduling RFC: https://github.com/bevyengine/rfcs/pull/45 ## Solution - [x] Remove old scheduling module - [x] Migrate new methods to no longer use extension methods - [x] Fix compiler errors - [x] Fix benchmarks - [x] Fix examples - [x] Fix docs - [x] Fix tests ## Changelog ### Added - a large number of methods on `App` to work with schedules ergonomically - the `CoreSchedule` enum - `App::add_extract_system` via the `RenderingAppExtension` trait extension method - the private `prepare_view_uniforms` system now has a public system set for scheduling purposes, called `ViewSet::PrepareUniforms` ### Removed - stages, and all code that mentions stages - states have been dramatically simplified, and no longer use a stack - `RunCriteriaLabel` - `AsSystemLabel` trait - `on_hierarchy_reports_enabled` run criteria (now just uses an ad hoc resource checking run condition) - systems in `RenderSet/Stage::Extract` no longer warn when they do not read data from the main world - `RunCriteriaLabel` - `transform_propagate_system_set`: this was a nonstandard pattern that didn't actually provide enough control. The systems are already `pub`: the docs have been updated to ensure that the third-party usage is clear. ### Changed - `System::default_labels` is now `System::default_system_sets`. - `App::add_default_labels` is now `App::add_default_sets` - `CoreStage` and `StartupStage` enums are now `CoreSet` and `StartupSet` - `App::add_system_set` was renamed to `App::add_systems` - The `StartupSchedule` label is now defined as part of the `CoreSchedules` enum - `.label(SystemLabel)` is now referred to as `.in_set(SystemSet)` - `SystemLabel` trait was replaced by `SystemSet` - `SystemTypeIdLabel<T>` was replaced by `SystemSetType<T>` - The `ReportHierarchyIssue` resource now has a public constructor (`new`), and implements `PartialEq` - Fixed time steps now use a schedule (`CoreSchedule::FixedTimeStep`) rather than a run criteria. - Adding rendering extraction systems now panics rather than silently failing if no subapp with the `RenderApp` label is found. - the `calculate_bounds` system, with the `CalculateBounds` label, is now in `CoreSet::Update`, rather than in `CoreSet::PostUpdate` before commands are applied. - `SceneSpawnerSystem` now runs under `CoreSet::Update`, rather than `CoreStage::PreUpdate.at_end()`. - `bevy_pbr::add_clusters` is no longer an exclusive system - the top level `bevy_ecs::schedule` module was replaced with `bevy_ecs::scheduling` - `tick_global_task_pools_on_main_thread` is no longer run as an exclusive system. Instead, it has been replaced by `tick_global_task_pools`, which uses a `NonSend` resource to force running on the main thread. ## Migration Guide - Calls to `.label(MyLabel)` should be replaced with `.in_set(MySet)` - Stages have been removed. Replace these with system sets, and then add command flushes using the `apply_system_buffers` exclusive system where needed. - The `CoreStage`, `StartupStage, `RenderStage` and `AssetStage` enums have been replaced with `CoreSet`, `StartupSet, `RenderSet` and `AssetSet`. The same scheduling guarantees have been preserved. - Systems are no longer added to `CoreSet::Update` by default. Add systems manually if this behavior is needed, although you should consider adding your game logic systems to `CoreSchedule::FixedTimestep` instead for more reliable framerate-independent behavior. - Similarly, startup systems are no longer part of `StartupSet::Startup` by default. In most cases, this won't matter to you. - For example, `add_system_to_stage(CoreStage::PostUpdate, my_system)` should be replaced with - `add_system(my_system.in_set(CoreSet::PostUpdate)` - When testing systems or otherwise running them in a headless fashion, simply construct and run a schedule using `Schedule::new()` and `World::run_schedule` rather than constructing stages - Run criteria have been renamed to run conditions. These can now be combined with each other and with states. - Looping run criteria and state stacks have been removed. Use an exclusive system that runs a schedule if you need this level of control over system control flow. - For app-level control flow over which schedules get run when (such as for rollback networking), create your own schedule and insert it under the `CoreSchedule::Outer` label. - Fixed timesteps are now evaluated in a schedule, rather than controlled via run criteria. The `run_fixed_timestep` system runs this schedule between `CoreSet::First` and `CoreSet::PreUpdate` by default. - Command flush points introduced by `AssetStage` have been removed. If you were relying on these, add them back manually. - Adding extract systems is now typically done directly on the main app. Make sure the `RenderingAppExtension` trait is in scope, then call `app.add_extract_system(my_system)`. - the `calculate_bounds` system, with the `CalculateBounds` label, is now in `CoreSet::Update`, rather than in `CoreSet::PostUpdate` before commands are applied. You may need to order your movement systems to occur before this system in order to avoid system order ambiguities in culling behavior. - the `RenderLabel` `AppLabel` was renamed to `RenderApp` for clarity - `App::add_state` now takes 0 arguments: the starting state is set based on the `Default` impl. - Instead of creating `SystemSet` containers for systems that run in stages, simply use `.on_enter::<State::Variant>()` or its `on_exit` or `on_update` siblings. - `SystemLabel` derives should be replaced with `SystemSet`. You will also need to add the `Debug`, `PartialEq`, `Eq`, and `Hash` traits to satisfy the new trait bounds. - `with_run_criteria` has been renamed to `run_if`. Run criteria have been renamed to run conditions for clarity, and should now simply return a bool. - States have been dramatically simplified: there is no longer a "state stack". To queue a transition to the next state, call `NextState::set` ## TODO - [x] remove dead methods on App and World - [x] add `App::add_system_to_schedule` and `App::add_systems_to_schedule` - [x] avoid adding the default system set at inappropriate times - [x] remove any accidental cycles in the default plugins schedule - [x] migrate benchmarks - [x] expose explicit labels for the built-in command flush points - [x] migrate engine code - [x] remove all mentions of stages from the docs - [x] verify docs for States - [x] fix uses of exclusive systems that use .end / .at_start / .before_commands - [x] migrate RenderStage and AssetStage - [x] migrate examples - [x] ensure that transform propagation is exported in a sufficiently public way (the systems are already pub) - [x] ensure that on_enter schedules are run at least once before the main app - [x] re-enable opt-in to execution order ambiguities - [x] revert change to `update_bounds` to ensure it runs in `PostUpdate` - [x] test all examples - [x] unbreak directional lights - [x] unbreak shadows (see 3d_scene, 3d_shape, lighting, transparaency_3d examples) - [x] game menu example shows loading screen and menu simultaneously - [x] display settings menu is a blank screen - [x] `without_winit` example panics - [x] ensure all tests pass - [x] SubApp doc test fails - [x] runs_spawn_local tasks fails - [x] [Fix panic_when_hierachy_cycle test hanging](https://github.com/alice-i-cecile/bevy/pull/120) ## Points of Difficulty and Controversy **Reviewers, please give feedback on these and look closely** 1. Default sets, from the RFC, have been removed. These added a tremendous amount of implicit complexity and result in hard to debug scheduling errors. They're going to be tackled in the form of "base sets" by @cart in a followup. 2. The outer schedule controls which schedule is run when `App::update` is called. 3. I implemented `Label for `Box<dyn Label>` for our label types. This enables us to store schedule labels in concrete form, and then later run them. I ran into the same set of problems when working with one-shot systems. We've previously investigated this pattern in depth, and it does not appear to lead to extra indirection with nested boxes. 4. `SubApp::update` simply runs the default schedule once. This sucks, but this whole API is incomplete and this was the minimal changeset. 5. `time_system` and `tick_global_task_pools_on_main_thread` no longer use exclusive systems to attempt to force scheduling order 6. Implemetnation strategy for fixed timesteps 7. `AssetStage` was migrated to `AssetSet` without reintroducing command flush points. These did not appear to be used, and it's nice to remove these bottlenecks. 8. Migration of `bevy_render/lib.rs` and pipelined rendering. The logic here is unusually tricky, as we have complex scheduling requirements. ## Future Work (ideally before 0.10) - Rename schedule_v3 module to schedule or scheduling - Add a derive macro to states, and likely a `EnumIter` trait of some form - Figure out what exactly to do with the "systems added should basically work by default" problem - Improve ergonomics for working with fixed timesteps and states - Polish FixedTime API to match Time - Rebase and merge #7415 - Resolve all internal ambiguities (blocked on better tools, especially #7442) - Add "base sets" to replace the removed default sets.
2023-02-06 02:04:50 +00:00
description = "Query for entities that had a specific component removed earlier in the current frame"
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
category = "ECS (Entity Component System)"
wasm = false
Add example for run conditions (#7652) Added an example for run conditions. Fixes #7646 if we wait till #7605 is merged and include some of it features.
2023-02-18 05:32:59 +00:00
[[example]]
name = "run_conditions"
path = "examples/ecs/run_conditions.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add example for run conditions (#7652) Added an example for run conditions. Fixes #7646 if we wait till #7605 is merged and include some of it features.
2023-02-18 05:32:59 +00:00
[package.metadata.example.run_conditions]
name = "Run Conditions"
description = "Run systems only when one or multiple conditions are met"
category = "ECS (Entity Component System)"
wasm = false
`QuerySingle` family of system params (#15476) # Objective Add the following system params: - `QuerySingle<D, F>` - Valid if only one matching entity exists, - `Option<QuerySingle<D, F>>` - Valid if zero or one matching entity exists. As @chescock pointed out, we don't need `Mut` variants. Fixes: #15264 ## Solution Implement the type and both variants of system params. Also implement `ReadOnlySystemParam` for readonly queries. Added a new ECS example `fallible_params` which showcases `SingleQuery` usage. In the future we might want to add `NonEmptyQuery`, `NonEmptyEventReader` and `Res` to it (or maybe just stop at mentioning it). ## Testing Tested with the example. There is a lot of warning spam so we might want to implement #15391.
2024-09-28 19:35:27 +00:00
[[example]]
name = "fallible_params"
path = "examples/ecs/fallible_params.rs"
doc-scrape-examples = true
[package.metadata.example.fallible_params]
name = "Fallible System Parameters"
description = "Systems are skipped if their parameters cannot be acquired"
category = "ECS (Entity Component System)"
wasm = false
organize examples and add ecs guide
2020-05-01 20:12:47 +00:00
[[example]]
name = "startup_system"
path = "examples/ecs/startup_system.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
organize examples and add ecs guide
2020-05-01 20:12:47 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.startup_system]
name = "Startup System"
description = "Demonstrates a startup system (one that runs once when the app starts up)"
category = "ECS (Entity Component System)"
wasm = false
Schedule v2 (#1021) Schedule V2
2020-12-13 02:04:42 +00:00
[[example]]
Generalize `StateTransitionEvent<S>` to allow identity transitions (#13579) # Objective This PR addresses one of the issues from [discord state discussion](https://discord.com/channels/691052431525675048/1237949214017716356). Same-state transitions can be desirable, so there should exist a hook for them. Fixes https://github.com/bevyengine/bevy/issues/9130. ## Solution - Allow `StateTransitionEvent<S>` to contain identity transitions. - Ignore identity transitions at schedule running level (`OnExit`, `OnTransition`, `OnEnter`). - Propagate identity transitions through `SubStates` and `ComputedStates`. - Add example about registering custom transition schedules. ## Changelog - `StateTransitionEvent<S>` can be emitted with same `exited` and `entered` state. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2024-06-04 14:23:24 +00:00
name = "states"
path = "examples/state/states.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Move utilities from examples to `bevy_state` and add concept of state-scoped entities (#13649) # Objective Move `StateScoped` and `log_transitions` to `bevy_state`, since they're useful for end users. Addresses #12852, although not in the way the issue had in mind. ## Solution - Added `bevy_hierarchy` to default features of `bevy_state`. - Move `log_transitions` to `transitions` module. - Move `StateScoped` to `state_scoped` module, gated behind `bevy_hierarchy` feature. - Refreshed implementation. - Added `enable_state_coped_entities<S: States>()` to add required machinery to `App` for clearing state-scoped entities. ## Changelog - Added `log_transitions` for displaying state transitions. - Added `StateScoped` for binding entity lifetime to state and app `enable_state_coped_entities` to register cleaning behavior. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: François Mockers <francois.mockers@vleue.com>
2024-06-04 11:44:34 +00:00
required-features = ["bevy_dev_tools"]
Schedule v2 (#1021) Schedule V2
2020-12-13 02:04:42 +00:00
Generalize `StateTransitionEvent<S>` to allow identity transitions (#13579) # Objective This PR addresses one of the issues from [discord state discussion](https://discord.com/channels/691052431525675048/1237949214017716356). Same-state transitions can be desirable, so there should exist a hook for them. Fixes https://github.com/bevyengine/bevy/issues/9130. ## Solution - Allow `StateTransitionEvent<S>` to contain identity transitions. - Ignore identity transitions at schedule running level (`OnExit`, `OnTransition`, `OnEnter`). - Propagate identity transitions through `SubStates` and `ComputedStates`. - Add example about registering custom transition schedules. ## Changelog - `StateTransitionEvent<S>` can be emitted with same `exited` and `entered` state. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2024-06-04 14:23:24 +00:00
[package.metadata.example.states]
name = "States"
description = "Illustrates how to use States to control transitioning from a Menu state to an InGame state."
Separate state crate (#13216) # Objective Extracts the state mechanisms into a new crate called "bevy_state". This comes with a few goals: - state wasn't really an inherent machinery of the ecs system, and so keeping it within bevy_ecs felt forced - by mixing it in with bevy_ecs, the maintainability of our more robust state system was significantly compromised moving state into a new crate makes it easier to encapsulate as it's own feature, and easier to read and understand since it's no longer a single, massive file. ## Solution move the state-related elements from bevy_ecs to a new crate ## Testing - Did you test these changes? If so, how? all the automated tests migrated and passed, ran the pre-existing examples without changes to validate. --- ## Migration Guide Since bevy_state is now gated behind the `bevy_state` feature, projects that use state but don't use the `default-features` will need to add that feature flag. Since it is no longer part of bevy_ecs, projects that use bevy_ecs directly will need to manually pull in `bevy_state`, trigger the StateTransition schedule, and handle any of the elements that bevy_app currently sets up. --------- Co-authored-by: Kristoffer Søholm <k.soeholm@gmail.com>
2024-05-09 18:06:05 +00:00
category = "State"
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
wasm = false
Computed State & Sub States (#11426) ## Summary/Description This PR extends states to allow support for a wider variety of state types and patterns, by providing 3 distinct types of state: - Standard [`States`] can only be changed by manually setting the [`NextState<S>`] resource. These states are the baseline on which the other state types are built, and can be used on their own for many simple patterns. See the [state example](https://github.com/bevyengine/bevy/blob/latest/examples/ecs/state.rs) for a simple use case - these are the states that existed so far in Bevy. - [`SubStates`] are children of other states - they can be changed manually using [`NextState<S>`], but are removed from the [`World`] if the source states aren't in the right state. See the [sub_states example](https://github.com/lee-orr/bevy/blob/derived_state/examples/ecs/sub_states.rs) for a simple use case based on the derive macro, or read the trait docs for more complex scenarios. - [`ComputedStates`] are fully derived from other states - they provide a [`compute`](ComputedStates::compute) method that takes in the source states and returns their derived value. They are particularly useful for situations where a simplified view of the source states is necessary - such as having an `InAMenu` computed state derived from a source state that defines multiple distinct menus. See the [computed state example](https://github.com/lee-orr/bevy/blob/derived_state/examples/ecs/computed_states.rscomputed_states.rs) to see a sampling of uses for these states. # Objective This PR is another attempt at allowing Bevy to better handle complex state objects in a manner that doesn't rely on strict equality. While my previous attempts (https://github.com/bevyengine/bevy/pull/10088 and https://github.com/bevyengine/bevy/pull/9957) relied on complex matching capacities at the point of adding a system to application, this one instead relies on deterministically deriving simple states from more complex ones. As a result, it does not require any special macros, nor does it change any other interactions with the state system once you define and add your derived state. It also maintains a degree of distinction between `State` and just normal application state - your derivations have to end up being discreet pre-determined values, meaning there is less of a risk/temptation to place a significant amount of logic and data within a given state. ### Addition - Sub States closes #9942 After some conversation with Maintainers & SMEs, a significant concern was that people might attempt to use this feature as if it were sub-states, and find themselves unable to use it appropriately. Since `ComputedState` is mainly a state matching feature, while `SubStates` are more of a state mutation related feature - but one that is easy to add with the help of the machinery introduced by `ComputedState`, it was added here as well. The relevant discussion is here: https://discord.com/channels/691052431525675048/1200556329803186316 ## Solution closes #11358 The solution is to create a new type of state - one implementing `ComputedStates` - which is deterministically tied to one or more other states. Implementors write a function to transform the source states into the computed state, and it gets triggered whenever one of the source states changes. In addition, we added the `FreelyMutableState` trait , which is implemented as part of the derive macro for `States`. This allows us to limit use of `NextState<S>` to states that are actually mutable, preventing mis-use of `ComputedStates`. --- ## Changelog - Added `ComputedStates` trait - Added `FreelyMutableState` trait - Converted `NextState` resource to an Enum, with `Unchanged` and `Pending` - Added `App::add_computed_state::<S: ComputedStates>()`, to allow for easily adding derived states to an App. - Moved the `StateTransition` schedule label from `bevy_app` to `bevy_ecs` - but maintained the export in `bevy_app` for continuity. - Modified the process for updating states. Instead of just having an `apply_state_transition` system that can be added anywhere, we now have a multi-stage process that has to run within the `StateTransition` label. First, all the state changes are calculated - manual transitions rely on `apply_state_transition`, while computed transitions run their computation process before both call `internal_apply_state_transition` to apply the transition, send out the transition event, trigger dependent states, and record which exit/transition/enter schedules need to occur. Once all the states have been updated, the transition schedules are called - first the exit schedules, then transition schedules and finally enter schedules. - Added `SubStates` trait - Adjusted `apply_state_transition` to be a no-op if the `State<S>` resource doesn't exist ## Migration Guide If the user accessed the NextState resource's value directly or created them from scratch they will need to adjust to use the new enum variants: - if they created a `NextState(Some(S))` - they should now use `NextState::Pending(S)` - if they created a `NextState(None)` -they should now use `NextState::Unchanged` - if they matched on the `NextState` value, they would need to make the adjustments above If the user manually utilized `apply_state_transition`, they should instead use systems that trigger the `StateTransition` schedule. --- ## Future Work There is still some future potential work in the area, but I wanted to keep these potential features and changes separate to keep the scope here contained, and keep the core of it easy to understand and use. However, I do want to note some of these things, both as inspiration to others and an illustration of what this PR could unlock. - `NextState::Remove` - Now that the `State` related mechanisms all utilize options (#11417), it's fairly easy to add support for explicit state removal. And while `ComputedStates` can add and remove themselves, right now `FreelyMutableState`s can't be removed from within the state system. While it existed originally in this PR, it is a different question with a separate scope and usability concerns - so having it as it's own future PR seems like the best approach. This feature currently lives in a separate branch in my fork, and the differences between it and this PR can be seen here: https://github.com/lee-orr/bevy/pull/5 - `NextState::ReEnter` - this would allow you to trigger exit & entry systems for the current state type. We can potentially also add a `NextState::ReEnterRecirsive` to also re-trigger any states that depend on the current one. - More mechanisms for `State` updates - This PR would finally make states that aren't a set of exclusive Enums useful, and with that comes the question of setting state more effectively. Right now, to update a state you either need to fully create the new state, or include the `Res<Option<State<S>>>` resource in your system, clone the state, mutate it, and then use `NextState.set(my_mutated_state)` to make it the pending next state. There are a few other potential methods that could be implemented in future PRs: - Inverse Compute States - these would essentially be compute states that have an additional (manually defined) function that can be used to nudge the source states so that they result in the computed states having a given value. For example, you could use set the `IsPaused` state, and it would attempt to pause or unpause the game by modifying the `AppState` as needed. - Closure-based state modification - this would involve adding a `NextState.modify(f: impl Fn(Option<S> -> Option<S>)` method, and then you can pass in closures or function pointers to adjust the state as needed. - Message-based state modification - this would involve either creating states that can respond to specific messages, similar to Elm or Redux. These could either use the `NextState` mechanism or the Event mechanism. - ~`SubStates` - which are essentially a hybrid of computed and manual states. In the simplest (and most likely) version, they would work by having a computed element that determines whether the state should exist, and if it should has the capacity to add a new version in, but then any changes to it's content would be freely mutated.~ this feature is now part of this PR. See above. - Lastly, since states are getting more complex there might be value in moving them out of `bevy_ecs` and into their own crate, or at least out of the `schedule` module into a `states` module. #11087 As mentioned, all these future work elements are TBD and are explicitly not part of this PR - I just wanted to provide them as potential explorations for the future. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Marcel Champagne <voiceofmarcel@gmail.com> Co-authored-by: MiniaczQ <xnetroidpl@gmail.com>
2024-05-02 19:36:23 +00:00
[[example]]
name = "sub_states"
Separate state crate (#13216) # Objective Extracts the state mechanisms into a new crate called "bevy_state". This comes with a few goals: - state wasn't really an inherent machinery of the ecs system, and so keeping it within bevy_ecs felt forced - by mixing it in with bevy_ecs, the maintainability of our more robust state system was significantly compromised moving state into a new crate makes it easier to encapsulate as it's own feature, and easier to read and understand since it's no longer a single, massive file. ## Solution move the state-related elements from bevy_ecs to a new crate ## Testing - Did you test these changes? If so, how? all the automated tests migrated and passed, ran the pre-existing examples without changes to validate. --- ## Migration Guide Since bevy_state is now gated behind the `bevy_state` feature, projects that use state but don't use the `default-features` will need to add that feature flag. Since it is no longer part of bevy_ecs, projects that use bevy_ecs directly will need to manually pull in `bevy_state`, trigger the StateTransition schedule, and handle any of the elements that bevy_app currently sets up. --------- Co-authored-by: Kristoffer Søholm <k.soeholm@gmail.com>
2024-05-09 18:06:05 +00:00
path = "examples/state/sub_states.rs"
Computed State & Sub States (#11426) ## Summary/Description This PR extends states to allow support for a wider variety of state types and patterns, by providing 3 distinct types of state: - Standard [`States`] can only be changed by manually setting the [`NextState<S>`] resource. These states are the baseline on which the other state types are built, and can be used on their own for many simple patterns. See the [state example](https://github.com/bevyengine/bevy/blob/latest/examples/ecs/state.rs) for a simple use case - these are the states that existed so far in Bevy. - [`SubStates`] are children of other states - they can be changed manually using [`NextState<S>`], but are removed from the [`World`] if the source states aren't in the right state. See the [sub_states example](https://github.com/lee-orr/bevy/blob/derived_state/examples/ecs/sub_states.rs) for a simple use case based on the derive macro, or read the trait docs for more complex scenarios. - [`ComputedStates`] are fully derived from other states - they provide a [`compute`](ComputedStates::compute) method that takes in the source states and returns their derived value. They are particularly useful for situations where a simplified view of the source states is necessary - such as having an `InAMenu` computed state derived from a source state that defines multiple distinct menus. See the [computed state example](https://github.com/lee-orr/bevy/blob/derived_state/examples/ecs/computed_states.rscomputed_states.rs) to see a sampling of uses for these states. # Objective This PR is another attempt at allowing Bevy to better handle complex state objects in a manner that doesn't rely on strict equality. While my previous attempts (https://github.com/bevyengine/bevy/pull/10088 and https://github.com/bevyengine/bevy/pull/9957) relied on complex matching capacities at the point of adding a system to application, this one instead relies on deterministically deriving simple states from more complex ones. As a result, it does not require any special macros, nor does it change any other interactions with the state system once you define and add your derived state. It also maintains a degree of distinction between `State` and just normal application state - your derivations have to end up being discreet pre-determined values, meaning there is less of a risk/temptation to place a significant amount of logic and data within a given state. ### Addition - Sub States closes #9942 After some conversation with Maintainers & SMEs, a significant concern was that people might attempt to use this feature as if it were sub-states, and find themselves unable to use it appropriately. Since `ComputedState` is mainly a state matching feature, while `SubStates` are more of a state mutation related feature - but one that is easy to add with the help of the machinery introduced by `ComputedState`, it was added here as well. The relevant discussion is here: https://discord.com/channels/691052431525675048/1200556329803186316 ## Solution closes #11358 The solution is to create a new type of state - one implementing `ComputedStates` - which is deterministically tied to one or more other states. Implementors write a function to transform the source states into the computed state, and it gets triggered whenever one of the source states changes. In addition, we added the `FreelyMutableState` trait , which is implemented as part of the derive macro for `States`. This allows us to limit use of `NextState<S>` to states that are actually mutable, preventing mis-use of `ComputedStates`. --- ## Changelog - Added `ComputedStates` trait - Added `FreelyMutableState` trait - Converted `NextState` resource to an Enum, with `Unchanged` and `Pending` - Added `App::add_computed_state::<S: ComputedStates>()`, to allow for easily adding derived states to an App. - Moved the `StateTransition` schedule label from `bevy_app` to `bevy_ecs` - but maintained the export in `bevy_app` for continuity. - Modified the process for updating states. Instead of just having an `apply_state_transition` system that can be added anywhere, we now have a multi-stage process that has to run within the `StateTransition` label. First, all the state changes are calculated - manual transitions rely on `apply_state_transition`, while computed transitions run their computation process before both call `internal_apply_state_transition` to apply the transition, send out the transition event, trigger dependent states, and record which exit/transition/enter schedules need to occur. Once all the states have been updated, the transition schedules are called - first the exit schedules, then transition schedules and finally enter schedules. - Added `SubStates` trait - Adjusted `apply_state_transition` to be a no-op if the `State<S>` resource doesn't exist ## Migration Guide If the user accessed the NextState resource's value directly or created them from scratch they will need to adjust to use the new enum variants: - if they created a `NextState(Some(S))` - they should now use `NextState::Pending(S)` - if they created a `NextState(None)` -they should now use `NextState::Unchanged` - if they matched on the `NextState` value, they would need to make the adjustments above If the user manually utilized `apply_state_transition`, they should instead use systems that trigger the `StateTransition` schedule. --- ## Future Work There is still some future potential work in the area, but I wanted to keep these potential features and changes separate to keep the scope here contained, and keep the core of it easy to understand and use. However, I do want to note some of these things, both as inspiration to others and an illustration of what this PR could unlock. - `NextState::Remove` - Now that the `State` related mechanisms all utilize options (#11417), it's fairly easy to add support for explicit state removal. And while `ComputedStates` can add and remove themselves, right now `FreelyMutableState`s can't be removed from within the state system. While it existed originally in this PR, it is a different question with a separate scope and usability concerns - so having it as it's own future PR seems like the best approach. This feature currently lives in a separate branch in my fork, and the differences between it and this PR can be seen here: https://github.com/lee-orr/bevy/pull/5 - `NextState::ReEnter` - this would allow you to trigger exit & entry systems for the current state type. We can potentially also add a `NextState::ReEnterRecirsive` to also re-trigger any states that depend on the current one. - More mechanisms for `State` updates - This PR would finally make states that aren't a set of exclusive Enums useful, and with that comes the question of setting state more effectively. Right now, to update a state you either need to fully create the new state, or include the `Res<Option<State<S>>>` resource in your system, clone the state, mutate it, and then use `NextState.set(my_mutated_state)` to make it the pending next state. There are a few other potential methods that could be implemented in future PRs: - Inverse Compute States - these would essentially be compute states that have an additional (manually defined) function that can be used to nudge the source states so that they result in the computed states having a given value. For example, you could use set the `IsPaused` state, and it would attempt to pause or unpause the game by modifying the `AppState` as needed. - Closure-based state modification - this would involve adding a `NextState.modify(f: impl Fn(Option<S> -> Option<S>)` method, and then you can pass in closures or function pointers to adjust the state as needed. - Message-based state modification - this would involve either creating states that can respond to specific messages, similar to Elm or Redux. These could either use the `NextState` mechanism or the Event mechanism. - ~`SubStates` - which are essentially a hybrid of computed and manual states. In the simplest (and most likely) version, they would work by having a computed element that determines whether the state should exist, and if it should has the capacity to add a new version in, but then any changes to it's content would be freely mutated.~ this feature is now part of this PR. See above. - Lastly, since states are getting more complex there might be value in moving them out of `bevy_ecs` and into their own crate, or at least out of the `schedule` module into a `states` module. #11087 As mentioned, all these future work elements are TBD and are explicitly not part of this PR - I just wanted to provide them as potential explorations for the future. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Marcel Champagne <voiceofmarcel@gmail.com> Co-authored-by: MiniaczQ <xnetroidpl@gmail.com>
2024-05-02 19:36:23 +00:00
doc-scrape-examples = true
Move utilities from examples to `bevy_state` and add concept of state-scoped entities (#13649) # Objective Move `StateScoped` and `log_transitions` to `bevy_state`, since they're useful for end users. Addresses #12852, although not in the way the issue had in mind. ## Solution - Added `bevy_hierarchy` to default features of `bevy_state`. - Move `log_transitions` to `transitions` module. - Move `StateScoped` to `state_scoped` module, gated behind `bevy_hierarchy` feature. - Refreshed implementation. - Added `enable_state_coped_entities<S: States>()` to add required machinery to `App` for clearing state-scoped entities. ## Changelog - Added `log_transitions` for displaying state transitions. - Added `StateScoped` for binding entity lifetime to state and app `enable_state_coped_entities` to register cleaning behavior. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: François Mockers <francois.mockers@vleue.com>
2024-06-04 11:44:34 +00:00
required-features = ["bevy_dev_tools"]
Computed State & Sub States (#11426) ## Summary/Description This PR extends states to allow support for a wider variety of state types and patterns, by providing 3 distinct types of state: - Standard [`States`] can only be changed by manually setting the [`NextState<S>`] resource. These states are the baseline on which the other state types are built, and can be used on their own for many simple patterns. See the [state example](https://github.com/bevyengine/bevy/blob/latest/examples/ecs/state.rs) for a simple use case - these are the states that existed so far in Bevy. - [`SubStates`] are children of other states - they can be changed manually using [`NextState<S>`], but are removed from the [`World`] if the source states aren't in the right state. See the [sub_states example](https://github.com/lee-orr/bevy/blob/derived_state/examples/ecs/sub_states.rs) for a simple use case based on the derive macro, or read the trait docs for more complex scenarios. - [`ComputedStates`] are fully derived from other states - they provide a [`compute`](ComputedStates::compute) method that takes in the source states and returns their derived value. They are particularly useful for situations where a simplified view of the source states is necessary - such as having an `InAMenu` computed state derived from a source state that defines multiple distinct menus. See the [computed state example](https://github.com/lee-orr/bevy/blob/derived_state/examples/ecs/computed_states.rscomputed_states.rs) to see a sampling of uses for these states. # Objective This PR is another attempt at allowing Bevy to better handle complex state objects in a manner that doesn't rely on strict equality. While my previous attempts (https://github.com/bevyengine/bevy/pull/10088 and https://github.com/bevyengine/bevy/pull/9957) relied on complex matching capacities at the point of adding a system to application, this one instead relies on deterministically deriving simple states from more complex ones. As a result, it does not require any special macros, nor does it change any other interactions with the state system once you define and add your derived state. It also maintains a degree of distinction between `State` and just normal application state - your derivations have to end up being discreet pre-determined values, meaning there is less of a risk/temptation to place a significant amount of logic and data within a given state. ### Addition - Sub States closes #9942 After some conversation with Maintainers & SMEs, a significant concern was that people might attempt to use this feature as if it were sub-states, and find themselves unable to use it appropriately. Since `ComputedState` is mainly a state matching feature, while `SubStates` are more of a state mutation related feature - but one that is easy to add with the help of the machinery introduced by `ComputedState`, it was added here as well. The relevant discussion is here: https://discord.com/channels/691052431525675048/1200556329803186316 ## Solution closes #11358 The solution is to create a new type of state - one implementing `ComputedStates` - which is deterministically tied to one or more other states. Implementors write a function to transform the source states into the computed state, and it gets triggered whenever one of the source states changes. In addition, we added the `FreelyMutableState` trait , which is implemented as part of the derive macro for `States`. This allows us to limit use of `NextState<S>` to states that are actually mutable, preventing mis-use of `ComputedStates`. --- ## Changelog - Added `ComputedStates` trait - Added `FreelyMutableState` trait - Converted `NextState` resource to an Enum, with `Unchanged` and `Pending` - Added `App::add_computed_state::<S: ComputedStates>()`, to allow for easily adding derived states to an App. - Moved the `StateTransition` schedule label from `bevy_app` to `bevy_ecs` - but maintained the export in `bevy_app` for continuity. - Modified the process for updating states. Instead of just having an `apply_state_transition` system that can be added anywhere, we now have a multi-stage process that has to run within the `StateTransition` label. First, all the state changes are calculated - manual transitions rely on `apply_state_transition`, while computed transitions run their computation process before both call `internal_apply_state_transition` to apply the transition, send out the transition event, trigger dependent states, and record which exit/transition/enter schedules need to occur. Once all the states have been updated, the transition schedules are called - first the exit schedules, then transition schedules and finally enter schedules. - Added `SubStates` trait - Adjusted `apply_state_transition` to be a no-op if the `State<S>` resource doesn't exist ## Migration Guide If the user accessed the NextState resource's value directly or created them from scratch they will need to adjust to use the new enum variants: - if they created a `NextState(Some(S))` - they should now use `NextState::Pending(S)` - if they created a `NextState(None)` -they should now use `NextState::Unchanged` - if they matched on the `NextState` value, they would need to make the adjustments above If the user manually utilized `apply_state_transition`, they should instead use systems that trigger the `StateTransition` schedule. --- ## Future Work There is still some future potential work in the area, but I wanted to keep these potential features and changes separate to keep the scope here contained, and keep the core of it easy to understand and use. However, I do want to note some of these things, both as inspiration to others and an illustration of what this PR could unlock. - `NextState::Remove` - Now that the `State` related mechanisms all utilize options (#11417), it's fairly easy to add support for explicit state removal. And while `ComputedStates` can add and remove themselves, right now `FreelyMutableState`s can't be removed from within the state system. While it existed originally in this PR, it is a different question with a separate scope and usability concerns - so having it as it's own future PR seems like the best approach. This feature currently lives in a separate branch in my fork, and the differences between it and this PR can be seen here: https://github.com/lee-orr/bevy/pull/5 - `NextState::ReEnter` - this would allow you to trigger exit & entry systems for the current state type. We can potentially also add a `NextState::ReEnterRecirsive` to also re-trigger any states that depend on the current one. - More mechanisms for `State` updates - This PR would finally make states that aren't a set of exclusive Enums useful, and with that comes the question of setting state more effectively. Right now, to update a state you either need to fully create the new state, or include the `Res<Option<State<S>>>` resource in your system, clone the state, mutate it, and then use `NextState.set(my_mutated_state)` to make it the pending next state. There are a few other potential methods that could be implemented in future PRs: - Inverse Compute States - these would essentially be compute states that have an additional (manually defined) function that can be used to nudge the source states so that they result in the computed states having a given value. For example, you could use set the `IsPaused` state, and it would attempt to pause or unpause the game by modifying the `AppState` as needed. - Closure-based state modification - this would involve adding a `NextState.modify(f: impl Fn(Option<S> -> Option<S>)` method, and then you can pass in closures or function pointers to adjust the state as needed. - Message-based state modification - this would involve either creating states that can respond to specific messages, similar to Elm or Redux. These could either use the `NextState` mechanism or the Event mechanism. - ~`SubStates` - which are essentially a hybrid of computed and manual states. In the simplest (and most likely) version, they would work by having a computed element that determines whether the state should exist, and if it should has the capacity to add a new version in, but then any changes to it's content would be freely mutated.~ this feature is now part of this PR. See above. - Lastly, since states are getting more complex there might be value in moving them out of `bevy_ecs` and into their own crate, or at least out of the `schedule` module into a `states` module. #11087 As mentioned, all these future work elements are TBD and are explicitly not part of this PR - I just wanted to provide them as potential explorations for the future. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Marcel Champagne <voiceofmarcel@gmail.com> Co-authored-by: MiniaczQ <xnetroidpl@gmail.com>
2024-05-02 19:36:23 +00:00
[package.metadata.example.sub_states]
name = "Sub States"
description = "Using Sub States for hierarchical state handling."
Separate state crate (#13216) # Objective Extracts the state mechanisms into a new crate called "bevy_state". This comes with a few goals: - state wasn't really an inherent machinery of the ecs system, and so keeping it within bevy_ecs felt forced - by mixing it in with bevy_ecs, the maintainability of our more robust state system was significantly compromised moving state into a new crate makes it easier to encapsulate as it's own feature, and easier to read and understand since it's no longer a single, massive file. ## Solution move the state-related elements from bevy_ecs to a new crate ## Testing - Did you test these changes? If so, how? all the automated tests migrated and passed, ran the pre-existing examples without changes to validate. --- ## Migration Guide Since bevy_state is now gated behind the `bevy_state` feature, projects that use state but don't use the `default-features` will need to add that feature flag. Since it is no longer part of bevy_ecs, projects that use bevy_ecs directly will need to manually pull in `bevy_state`, trigger the StateTransition schedule, and handle any of the elements that bevy_app currently sets up. --------- Co-authored-by: Kristoffer Søholm <k.soeholm@gmail.com>
2024-05-09 18:06:05 +00:00
category = "State"
Computed State & Sub States (#11426) ## Summary/Description This PR extends states to allow support for a wider variety of state types and patterns, by providing 3 distinct types of state: - Standard [`States`] can only be changed by manually setting the [`NextState<S>`] resource. These states are the baseline on which the other state types are built, and can be used on their own for many simple patterns. See the [state example](https://github.com/bevyengine/bevy/blob/latest/examples/ecs/state.rs) for a simple use case - these are the states that existed so far in Bevy. - [`SubStates`] are children of other states - they can be changed manually using [`NextState<S>`], but are removed from the [`World`] if the source states aren't in the right state. See the [sub_states example](https://github.com/lee-orr/bevy/blob/derived_state/examples/ecs/sub_states.rs) for a simple use case based on the derive macro, or read the trait docs for more complex scenarios. - [`ComputedStates`] are fully derived from other states - they provide a [`compute`](ComputedStates::compute) method that takes in the source states and returns their derived value. They are particularly useful for situations where a simplified view of the source states is necessary - such as having an `InAMenu` computed state derived from a source state that defines multiple distinct menus. See the [computed state example](https://github.com/lee-orr/bevy/blob/derived_state/examples/ecs/computed_states.rscomputed_states.rs) to see a sampling of uses for these states. # Objective This PR is another attempt at allowing Bevy to better handle complex state objects in a manner that doesn't rely on strict equality. While my previous attempts (https://github.com/bevyengine/bevy/pull/10088 and https://github.com/bevyengine/bevy/pull/9957) relied on complex matching capacities at the point of adding a system to application, this one instead relies on deterministically deriving simple states from more complex ones. As a result, it does not require any special macros, nor does it change any other interactions with the state system once you define and add your derived state. It also maintains a degree of distinction between `State` and just normal application state - your derivations have to end up being discreet pre-determined values, meaning there is less of a risk/temptation to place a significant amount of logic and data within a given state. ### Addition - Sub States closes #9942 After some conversation with Maintainers & SMEs, a significant concern was that people might attempt to use this feature as if it were sub-states, and find themselves unable to use it appropriately. Since `ComputedState` is mainly a state matching feature, while `SubStates` are more of a state mutation related feature - but one that is easy to add with the help of the machinery introduced by `ComputedState`, it was added here as well. The relevant discussion is here: https://discord.com/channels/691052431525675048/1200556329803186316 ## Solution closes #11358 The solution is to create a new type of state - one implementing `ComputedStates` - which is deterministically tied to one or more other states. Implementors write a function to transform the source states into the computed state, and it gets triggered whenever one of the source states changes. In addition, we added the `FreelyMutableState` trait , which is implemented as part of the derive macro for `States`. This allows us to limit use of `NextState<S>` to states that are actually mutable, preventing mis-use of `ComputedStates`. --- ## Changelog - Added `ComputedStates` trait - Added `FreelyMutableState` trait - Converted `NextState` resource to an Enum, with `Unchanged` and `Pending` - Added `App::add_computed_state::<S: ComputedStates>()`, to allow for easily adding derived states to an App. - Moved the `StateTransition` schedule label from `bevy_app` to `bevy_ecs` - but maintained the export in `bevy_app` for continuity. - Modified the process for updating states. Instead of just having an `apply_state_transition` system that can be added anywhere, we now have a multi-stage process that has to run within the `StateTransition` label. First, all the state changes are calculated - manual transitions rely on `apply_state_transition`, while computed transitions run their computation process before both call `internal_apply_state_transition` to apply the transition, send out the transition event, trigger dependent states, and record which exit/transition/enter schedules need to occur. Once all the states have been updated, the transition schedules are called - first the exit schedules, then transition schedules and finally enter schedules. - Added `SubStates` trait - Adjusted `apply_state_transition` to be a no-op if the `State<S>` resource doesn't exist ## Migration Guide If the user accessed the NextState resource's value directly or created them from scratch they will need to adjust to use the new enum variants: - if they created a `NextState(Some(S))` - they should now use `NextState::Pending(S)` - if they created a `NextState(None)` -they should now use `NextState::Unchanged` - if they matched on the `NextState` value, they would need to make the adjustments above If the user manually utilized `apply_state_transition`, they should instead use systems that trigger the `StateTransition` schedule. --- ## Future Work There is still some future potential work in the area, but I wanted to keep these potential features and changes separate to keep the scope here contained, and keep the core of it easy to understand and use. However, I do want to note some of these things, both as inspiration to others and an illustration of what this PR could unlock. - `NextState::Remove` - Now that the `State` related mechanisms all utilize options (#11417), it's fairly easy to add support for explicit state removal. And while `ComputedStates` can add and remove themselves, right now `FreelyMutableState`s can't be removed from within the state system. While it existed originally in this PR, it is a different question with a separate scope and usability concerns - so having it as it's own future PR seems like the best approach. This feature currently lives in a separate branch in my fork, and the differences between it and this PR can be seen here: https://github.com/lee-orr/bevy/pull/5 - `NextState::ReEnter` - this would allow you to trigger exit & entry systems for the current state type. We can potentially also add a `NextState::ReEnterRecirsive` to also re-trigger any states that depend on the current one. - More mechanisms for `State` updates - This PR would finally make states that aren't a set of exclusive Enums useful, and with that comes the question of setting state more effectively. Right now, to update a state you either need to fully create the new state, or include the `Res<Option<State<S>>>` resource in your system, clone the state, mutate it, and then use `NextState.set(my_mutated_state)` to make it the pending next state. There are a few other potential methods that could be implemented in future PRs: - Inverse Compute States - these would essentially be compute states that have an additional (manually defined) function that can be used to nudge the source states so that they result in the computed states having a given value. For example, you could use set the `IsPaused` state, and it would attempt to pause or unpause the game by modifying the `AppState` as needed. - Closure-based state modification - this would involve adding a `NextState.modify(f: impl Fn(Option<S> -> Option<S>)` method, and then you can pass in closures or function pointers to adjust the state as needed. - Message-based state modification - this would involve either creating states that can respond to specific messages, similar to Elm or Redux. These could either use the `NextState` mechanism or the Event mechanism. - ~`SubStates` - which are essentially a hybrid of computed and manual states. In the simplest (and most likely) version, they would work by having a computed element that determines whether the state should exist, and if it should has the capacity to add a new version in, but then any changes to it's content would be freely mutated.~ this feature is now part of this PR. See above. - Lastly, since states are getting more complex there might be value in moving them out of `bevy_ecs` and into their own crate, or at least out of the `schedule` module into a `states` module. #11087 As mentioned, all these future work elements are TBD and are explicitly not part of this PR - I just wanted to provide them as potential explorations for the future. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Marcel Champagne <voiceofmarcel@gmail.com> Co-authored-by: MiniaczQ <xnetroidpl@gmail.com>
2024-05-02 19:36:23 +00:00
wasm = false
[[example]]
name = "computed_states"
Separate state crate (#13216) # Objective Extracts the state mechanisms into a new crate called "bevy_state". This comes with a few goals: - state wasn't really an inherent machinery of the ecs system, and so keeping it within bevy_ecs felt forced - by mixing it in with bevy_ecs, the maintainability of our more robust state system was significantly compromised moving state into a new crate makes it easier to encapsulate as it's own feature, and easier to read and understand since it's no longer a single, massive file. ## Solution move the state-related elements from bevy_ecs to a new crate ## Testing - Did you test these changes? If so, how? all the automated tests migrated and passed, ran the pre-existing examples without changes to validate. --- ## Migration Guide Since bevy_state is now gated behind the `bevy_state` feature, projects that use state but don't use the `default-features` will need to add that feature flag. Since it is no longer part of bevy_ecs, projects that use bevy_ecs directly will need to manually pull in `bevy_state`, trigger the StateTransition schedule, and handle any of the elements that bevy_app currently sets up. --------- Co-authored-by: Kristoffer Søholm <k.soeholm@gmail.com>
2024-05-09 18:06:05 +00:00
path = "examples/state/computed_states.rs"
Computed State & Sub States (#11426) ## Summary/Description This PR extends states to allow support for a wider variety of state types and patterns, by providing 3 distinct types of state: - Standard [`States`] can only be changed by manually setting the [`NextState<S>`] resource. These states are the baseline on which the other state types are built, and can be used on their own for many simple patterns. See the [state example](https://github.com/bevyengine/bevy/blob/latest/examples/ecs/state.rs) for a simple use case - these are the states that existed so far in Bevy. - [`SubStates`] are children of other states - they can be changed manually using [`NextState<S>`], but are removed from the [`World`] if the source states aren't in the right state. See the [sub_states example](https://github.com/lee-orr/bevy/blob/derived_state/examples/ecs/sub_states.rs) for a simple use case based on the derive macro, or read the trait docs for more complex scenarios. - [`ComputedStates`] are fully derived from other states - they provide a [`compute`](ComputedStates::compute) method that takes in the source states and returns their derived value. They are particularly useful for situations where a simplified view of the source states is necessary - such as having an `InAMenu` computed state derived from a source state that defines multiple distinct menus. See the [computed state example](https://github.com/lee-orr/bevy/blob/derived_state/examples/ecs/computed_states.rscomputed_states.rs) to see a sampling of uses for these states. # Objective This PR is another attempt at allowing Bevy to better handle complex state objects in a manner that doesn't rely on strict equality. While my previous attempts (https://github.com/bevyengine/bevy/pull/10088 and https://github.com/bevyengine/bevy/pull/9957) relied on complex matching capacities at the point of adding a system to application, this one instead relies on deterministically deriving simple states from more complex ones. As a result, it does not require any special macros, nor does it change any other interactions with the state system once you define and add your derived state. It also maintains a degree of distinction between `State` and just normal application state - your derivations have to end up being discreet pre-determined values, meaning there is less of a risk/temptation to place a significant amount of logic and data within a given state. ### Addition - Sub States closes #9942 After some conversation with Maintainers & SMEs, a significant concern was that people might attempt to use this feature as if it were sub-states, and find themselves unable to use it appropriately. Since `ComputedState` is mainly a state matching feature, while `SubStates` are more of a state mutation related feature - but one that is easy to add with the help of the machinery introduced by `ComputedState`, it was added here as well. The relevant discussion is here: https://discord.com/channels/691052431525675048/1200556329803186316 ## Solution closes #11358 The solution is to create a new type of state - one implementing `ComputedStates` - which is deterministically tied to one or more other states. Implementors write a function to transform the source states into the computed state, and it gets triggered whenever one of the source states changes. In addition, we added the `FreelyMutableState` trait , which is implemented as part of the derive macro for `States`. This allows us to limit use of `NextState<S>` to states that are actually mutable, preventing mis-use of `ComputedStates`. --- ## Changelog - Added `ComputedStates` trait - Added `FreelyMutableState` trait - Converted `NextState` resource to an Enum, with `Unchanged` and `Pending` - Added `App::add_computed_state::<S: ComputedStates>()`, to allow for easily adding derived states to an App. - Moved the `StateTransition` schedule label from `bevy_app` to `bevy_ecs` - but maintained the export in `bevy_app` for continuity. - Modified the process for updating states. Instead of just having an `apply_state_transition` system that can be added anywhere, we now have a multi-stage process that has to run within the `StateTransition` label. First, all the state changes are calculated - manual transitions rely on `apply_state_transition`, while computed transitions run their computation process before both call `internal_apply_state_transition` to apply the transition, send out the transition event, trigger dependent states, and record which exit/transition/enter schedules need to occur. Once all the states have been updated, the transition schedules are called - first the exit schedules, then transition schedules and finally enter schedules. - Added `SubStates` trait - Adjusted `apply_state_transition` to be a no-op if the `State<S>` resource doesn't exist ## Migration Guide If the user accessed the NextState resource's value directly or created them from scratch they will need to adjust to use the new enum variants: - if they created a `NextState(Some(S))` - they should now use `NextState::Pending(S)` - if they created a `NextState(None)` -they should now use `NextState::Unchanged` - if they matched on the `NextState` value, they would need to make the adjustments above If the user manually utilized `apply_state_transition`, they should instead use systems that trigger the `StateTransition` schedule. --- ## Future Work There is still some future potential work in the area, but I wanted to keep these potential features and changes separate to keep the scope here contained, and keep the core of it easy to understand and use. However, I do want to note some of these things, both as inspiration to others and an illustration of what this PR could unlock. - `NextState::Remove` - Now that the `State` related mechanisms all utilize options (#11417), it's fairly easy to add support for explicit state removal. And while `ComputedStates` can add and remove themselves, right now `FreelyMutableState`s can't be removed from within the state system. While it existed originally in this PR, it is a different question with a separate scope and usability concerns - so having it as it's own future PR seems like the best approach. This feature currently lives in a separate branch in my fork, and the differences between it and this PR can be seen here: https://github.com/lee-orr/bevy/pull/5 - `NextState::ReEnter` - this would allow you to trigger exit & entry systems for the current state type. We can potentially also add a `NextState::ReEnterRecirsive` to also re-trigger any states that depend on the current one. - More mechanisms for `State` updates - This PR would finally make states that aren't a set of exclusive Enums useful, and with that comes the question of setting state more effectively. Right now, to update a state you either need to fully create the new state, or include the `Res<Option<State<S>>>` resource in your system, clone the state, mutate it, and then use `NextState.set(my_mutated_state)` to make it the pending next state. There are a few other potential methods that could be implemented in future PRs: - Inverse Compute States - these would essentially be compute states that have an additional (manually defined) function that can be used to nudge the source states so that they result in the computed states having a given value. For example, you could use set the `IsPaused` state, and it would attempt to pause or unpause the game by modifying the `AppState` as needed. - Closure-based state modification - this would involve adding a `NextState.modify(f: impl Fn(Option<S> -> Option<S>)` method, and then you can pass in closures or function pointers to adjust the state as needed. - Message-based state modification - this would involve either creating states that can respond to specific messages, similar to Elm or Redux. These could either use the `NextState` mechanism or the Event mechanism. - ~`SubStates` - which are essentially a hybrid of computed and manual states. In the simplest (and most likely) version, they would work by having a computed element that determines whether the state should exist, and if it should has the capacity to add a new version in, but then any changes to it's content would be freely mutated.~ this feature is now part of this PR. See above. - Lastly, since states are getting more complex there might be value in moving them out of `bevy_ecs` and into their own crate, or at least out of the `schedule` module into a `states` module. #11087 As mentioned, all these future work elements are TBD and are explicitly not part of this PR - I just wanted to provide them as potential explorations for the future. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Marcel Champagne <voiceofmarcel@gmail.com> Co-authored-by: MiniaczQ <xnetroidpl@gmail.com>
2024-05-02 19:36:23 +00:00
doc-scrape-examples = true
Move utilities from examples to `bevy_state` and add concept of state-scoped entities (#13649) # Objective Move `StateScoped` and `log_transitions` to `bevy_state`, since they're useful for end users. Addresses #12852, although not in the way the issue had in mind. ## Solution - Added `bevy_hierarchy` to default features of `bevy_state`. - Move `log_transitions` to `transitions` module. - Move `StateScoped` to `state_scoped` module, gated behind `bevy_hierarchy` feature. - Refreshed implementation. - Added `enable_state_coped_entities<S: States>()` to add required machinery to `App` for clearing state-scoped entities. ## Changelog - Added `log_transitions` for displaying state transitions. - Added `StateScoped` for binding entity lifetime to state and app `enable_state_coped_entities` to register cleaning behavior. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: François Mockers <francois.mockers@vleue.com>
2024-06-04 11:44:34 +00:00
required-features = ["bevy_dev_tools"]
Computed State & Sub States (#11426) ## Summary/Description This PR extends states to allow support for a wider variety of state types and patterns, by providing 3 distinct types of state: - Standard [`States`] can only be changed by manually setting the [`NextState<S>`] resource. These states are the baseline on which the other state types are built, and can be used on their own for many simple patterns. See the [state example](https://github.com/bevyengine/bevy/blob/latest/examples/ecs/state.rs) for a simple use case - these are the states that existed so far in Bevy. - [`SubStates`] are children of other states - they can be changed manually using [`NextState<S>`], but are removed from the [`World`] if the source states aren't in the right state. See the [sub_states example](https://github.com/lee-orr/bevy/blob/derived_state/examples/ecs/sub_states.rs) for a simple use case based on the derive macro, or read the trait docs for more complex scenarios. - [`ComputedStates`] are fully derived from other states - they provide a [`compute`](ComputedStates::compute) method that takes in the source states and returns their derived value. They are particularly useful for situations where a simplified view of the source states is necessary - such as having an `InAMenu` computed state derived from a source state that defines multiple distinct menus. See the [computed state example](https://github.com/lee-orr/bevy/blob/derived_state/examples/ecs/computed_states.rscomputed_states.rs) to see a sampling of uses for these states. # Objective This PR is another attempt at allowing Bevy to better handle complex state objects in a manner that doesn't rely on strict equality. While my previous attempts (https://github.com/bevyengine/bevy/pull/10088 and https://github.com/bevyengine/bevy/pull/9957) relied on complex matching capacities at the point of adding a system to application, this one instead relies on deterministically deriving simple states from more complex ones. As a result, it does not require any special macros, nor does it change any other interactions with the state system once you define and add your derived state. It also maintains a degree of distinction between `State` and just normal application state - your derivations have to end up being discreet pre-determined values, meaning there is less of a risk/temptation to place a significant amount of logic and data within a given state. ### Addition - Sub States closes #9942 After some conversation with Maintainers & SMEs, a significant concern was that people might attempt to use this feature as if it were sub-states, and find themselves unable to use it appropriately. Since `ComputedState` is mainly a state matching feature, while `SubStates` are more of a state mutation related feature - but one that is easy to add with the help of the machinery introduced by `ComputedState`, it was added here as well. The relevant discussion is here: https://discord.com/channels/691052431525675048/1200556329803186316 ## Solution closes #11358 The solution is to create a new type of state - one implementing `ComputedStates` - which is deterministically tied to one or more other states. Implementors write a function to transform the source states into the computed state, and it gets triggered whenever one of the source states changes. In addition, we added the `FreelyMutableState` trait , which is implemented as part of the derive macro for `States`. This allows us to limit use of `NextState<S>` to states that are actually mutable, preventing mis-use of `ComputedStates`. --- ## Changelog - Added `ComputedStates` trait - Added `FreelyMutableState` trait - Converted `NextState` resource to an Enum, with `Unchanged` and `Pending` - Added `App::add_computed_state::<S: ComputedStates>()`, to allow for easily adding derived states to an App. - Moved the `StateTransition` schedule label from `bevy_app` to `bevy_ecs` - but maintained the export in `bevy_app` for continuity. - Modified the process for updating states. Instead of just having an `apply_state_transition` system that can be added anywhere, we now have a multi-stage process that has to run within the `StateTransition` label. First, all the state changes are calculated - manual transitions rely on `apply_state_transition`, while computed transitions run their computation process before both call `internal_apply_state_transition` to apply the transition, send out the transition event, trigger dependent states, and record which exit/transition/enter schedules need to occur. Once all the states have been updated, the transition schedules are called - first the exit schedules, then transition schedules and finally enter schedules. - Added `SubStates` trait - Adjusted `apply_state_transition` to be a no-op if the `State<S>` resource doesn't exist ## Migration Guide If the user accessed the NextState resource's value directly or created them from scratch they will need to adjust to use the new enum variants: - if they created a `NextState(Some(S))` - they should now use `NextState::Pending(S)` - if they created a `NextState(None)` -they should now use `NextState::Unchanged` - if they matched on the `NextState` value, they would need to make the adjustments above If the user manually utilized `apply_state_transition`, they should instead use systems that trigger the `StateTransition` schedule. --- ## Future Work There is still some future potential work in the area, but I wanted to keep these potential features and changes separate to keep the scope here contained, and keep the core of it easy to understand and use. However, I do want to note some of these things, both as inspiration to others and an illustration of what this PR could unlock. - `NextState::Remove` - Now that the `State` related mechanisms all utilize options (#11417), it's fairly easy to add support for explicit state removal. And while `ComputedStates` can add and remove themselves, right now `FreelyMutableState`s can't be removed from within the state system. While it existed originally in this PR, it is a different question with a separate scope and usability concerns - so having it as it's own future PR seems like the best approach. This feature currently lives in a separate branch in my fork, and the differences between it and this PR can be seen here: https://github.com/lee-orr/bevy/pull/5 - `NextState::ReEnter` - this would allow you to trigger exit & entry systems for the current state type. We can potentially also add a `NextState::ReEnterRecirsive` to also re-trigger any states that depend on the current one. - More mechanisms for `State` updates - This PR would finally make states that aren't a set of exclusive Enums useful, and with that comes the question of setting state more effectively. Right now, to update a state you either need to fully create the new state, or include the `Res<Option<State<S>>>` resource in your system, clone the state, mutate it, and then use `NextState.set(my_mutated_state)` to make it the pending next state. There are a few other potential methods that could be implemented in future PRs: - Inverse Compute States - these would essentially be compute states that have an additional (manually defined) function that can be used to nudge the source states so that they result in the computed states having a given value. For example, you could use set the `IsPaused` state, and it would attempt to pause or unpause the game by modifying the `AppState` as needed. - Closure-based state modification - this would involve adding a `NextState.modify(f: impl Fn(Option<S> -> Option<S>)` method, and then you can pass in closures or function pointers to adjust the state as needed. - Message-based state modification - this would involve either creating states that can respond to specific messages, similar to Elm or Redux. These could either use the `NextState` mechanism or the Event mechanism. - ~`SubStates` - which are essentially a hybrid of computed and manual states. In the simplest (and most likely) version, they would work by having a computed element that determines whether the state should exist, and if it should has the capacity to add a new version in, but then any changes to it's content would be freely mutated.~ this feature is now part of this PR. See above. - Lastly, since states are getting more complex there might be value in moving them out of `bevy_ecs` and into their own crate, or at least out of the `schedule` module into a `states` module. #11087 As mentioned, all these future work elements are TBD and are explicitly not part of this PR - I just wanted to provide them as potential explorations for the future. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Marcel Champagne <voiceofmarcel@gmail.com> Co-authored-by: MiniaczQ <xnetroidpl@gmail.com>
2024-05-02 19:36:23 +00:00
[package.metadata.example.computed_states]
name = "Computed States"
Generalize `StateTransitionEvent<S>` to allow identity transitions (#13579) # Objective This PR addresses one of the issues from [discord state discussion](https://discord.com/channels/691052431525675048/1237949214017716356). Same-state transitions can be desirable, so there should exist a hook for them. Fixes https://github.com/bevyengine/bevy/issues/9130. ## Solution - Allow `StateTransitionEvent<S>` to contain identity transitions. - Ignore identity transitions at schedule running level (`OnExit`, `OnTransition`, `OnEnter`). - Propagate identity transitions through `SubStates` and `ComputedStates`. - Add example about registering custom transition schedules. ## Changelog - `StateTransitionEvent<S>` can be emitted with same `exited` and `entered` state. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2024-06-04 14:23:24 +00:00
description = "Advanced state patterns using Computed States."
category = "State"
wasm = false
[[example]]
name = "custom_transitions"
path = "examples/state/custom_transitions.rs"
doc-scrape-examples = true
required-features = ["bevy_dev_tools"]
[package.metadata.example.custom_transitions]
name = "Custom State Transition Behavior"
description = "Creating and working with custom state transition schedules."
Separate state crate (#13216) # Objective Extracts the state mechanisms into a new crate called "bevy_state". This comes with a few goals: - state wasn't really an inherent machinery of the ecs system, and so keeping it within bevy_ecs felt forced - by mixing it in with bevy_ecs, the maintainability of our more robust state system was significantly compromised moving state into a new crate makes it easier to encapsulate as it's own feature, and easier to read and understand since it's no longer a single, massive file. ## Solution move the state-related elements from bevy_ecs to a new crate ## Testing - Did you test these changes? If so, how? all the automated tests migrated and passed, ran the pre-existing examples without changes to validate. --- ## Migration Guide Since bevy_state is now gated behind the `bevy_state` feature, projects that use state but don't use the `default-features` will need to add that feature flag. Since it is no longer part of bevy_ecs, projects that use bevy_ecs directly will need to manually pull in `bevy_state`, trigger the StateTransition schedule, and handle any of the elements that bevy_app currently sets up. --------- Co-authored-by: Kristoffer Søholm <k.soeholm@gmail.com>
2024-05-09 18:06:05 +00:00
category = "State"
Computed State & Sub States (#11426) ## Summary/Description This PR extends states to allow support for a wider variety of state types and patterns, by providing 3 distinct types of state: - Standard [`States`] can only be changed by manually setting the [`NextState<S>`] resource. These states are the baseline on which the other state types are built, and can be used on their own for many simple patterns. See the [state example](https://github.com/bevyengine/bevy/blob/latest/examples/ecs/state.rs) for a simple use case - these are the states that existed so far in Bevy. - [`SubStates`] are children of other states - they can be changed manually using [`NextState<S>`], but are removed from the [`World`] if the source states aren't in the right state. See the [sub_states example](https://github.com/lee-orr/bevy/blob/derived_state/examples/ecs/sub_states.rs) for a simple use case based on the derive macro, or read the trait docs for more complex scenarios. - [`ComputedStates`] are fully derived from other states - they provide a [`compute`](ComputedStates::compute) method that takes in the source states and returns their derived value. They are particularly useful for situations where a simplified view of the source states is necessary - such as having an `InAMenu` computed state derived from a source state that defines multiple distinct menus. See the [computed state example](https://github.com/lee-orr/bevy/blob/derived_state/examples/ecs/computed_states.rscomputed_states.rs) to see a sampling of uses for these states. # Objective This PR is another attempt at allowing Bevy to better handle complex state objects in a manner that doesn't rely on strict equality. While my previous attempts (https://github.com/bevyengine/bevy/pull/10088 and https://github.com/bevyengine/bevy/pull/9957) relied on complex matching capacities at the point of adding a system to application, this one instead relies on deterministically deriving simple states from more complex ones. As a result, it does not require any special macros, nor does it change any other interactions with the state system once you define and add your derived state. It also maintains a degree of distinction between `State` and just normal application state - your derivations have to end up being discreet pre-determined values, meaning there is less of a risk/temptation to place a significant amount of logic and data within a given state. ### Addition - Sub States closes #9942 After some conversation with Maintainers & SMEs, a significant concern was that people might attempt to use this feature as if it were sub-states, and find themselves unable to use it appropriately. Since `ComputedState` is mainly a state matching feature, while `SubStates` are more of a state mutation related feature - but one that is easy to add with the help of the machinery introduced by `ComputedState`, it was added here as well. The relevant discussion is here: https://discord.com/channels/691052431525675048/1200556329803186316 ## Solution closes #11358 The solution is to create a new type of state - one implementing `ComputedStates` - which is deterministically tied to one or more other states. Implementors write a function to transform the source states into the computed state, and it gets triggered whenever one of the source states changes. In addition, we added the `FreelyMutableState` trait , which is implemented as part of the derive macro for `States`. This allows us to limit use of `NextState<S>` to states that are actually mutable, preventing mis-use of `ComputedStates`. --- ## Changelog - Added `ComputedStates` trait - Added `FreelyMutableState` trait - Converted `NextState` resource to an Enum, with `Unchanged` and `Pending` - Added `App::add_computed_state::<S: ComputedStates>()`, to allow for easily adding derived states to an App. - Moved the `StateTransition` schedule label from `bevy_app` to `bevy_ecs` - but maintained the export in `bevy_app` for continuity. - Modified the process for updating states. Instead of just having an `apply_state_transition` system that can be added anywhere, we now have a multi-stage process that has to run within the `StateTransition` label. First, all the state changes are calculated - manual transitions rely on `apply_state_transition`, while computed transitions run their computation process before both call `internal_apply_state_transition` to apply the transition, send out the transition event, trigger dependent states, and record which exit/transition/enter schedules need to occur. Once all the states have been updated, the transition schedules are called - first the exit schedules, then transition schedules and finally enter schedules. - Added `SubStates` trait - Adjusted `apply_state_transition` to be a no-op if the `State<S>` resource doesn't exist ## Migration Guide If the user accessed the NextState resource's value directly or created them from scratch they will need to adjust to use the new enum variants: - if they created a `NextState(Some(S))` - they should now use `NextState::Pending(S)` - if they created a `NextState(None)` -they should now use `NextState::Unchanged` - if they matched on the `NextState` value, they would need to make the adjustments above If the user manually utilized `apply_state_transition`, they should instead use systems that trigger the `StateTransition` schedule. --- ## Future Work There is still some future potential work in the area, but I wanted to keep these potential features and changes separate to keep the scope here contained, and keep the core of it easy to understand and use. However, I do want to note some of these things, both as inspiration to others and an illustration of what this PR could unlock. - `NextState::Remove` - Now that the `State` related mechanisms all utilize options (#11417), it's fairly easy to add support for explicit state removal. And while `ComputedStates` can add and remove themselves, right now `FreelyMutableState`s can't be removed from within the state system. While it existed originally in this PR, it is a different question with a separate scope and usability concerns - so having it as it's own future PR seems like the best approach. This feature currently lives in a separate branch in my fork, and the differences between it and this PR can be seen here: https://github.com/lee-orr/bevy/pull/5 - `NextState::ReEnter` - this would allow you to trigger exit & entry systems for the current state type. We can potentially also add a `NextState::ReEnterRecirsive` to also re-trigger any states that depend on the current one. - More mechanisms for `State` updates - This PR would finally make states that aren't a set of exclusive Enums useful, and with that comes the question of setting state more effectively. Right now, to update a state you either need to fully create the new state, or include the `Res<Option<State<S>>>` resource in your system, clone the state, mutate it, and then use `NextState.set(my_mutated_state)` to make it the pending next state. There are a few other potential methods that could be implemented in future PRs: - Inverse Compute States - these would essentially be compute states that have an additional (manually defined) function that can be used to nudge the source states so that they result in the computed states having a given value. For example, you could use set the `IsPaused` state, and it would attempt to pause or unpause the game by modifying the `AppState` as needed. - Closure-based state modification - this would involve adding a `NextState.modify(f: impl Fn(Option<S> -> Option<S>)` method, and then you can pass in closures or function pointers to adjust the state as needed. - Message-based state modification - this would involve either creating states that can respond to specific messages, similar to Elm or Redux. These could either use the `NextState` mechanism or the Event mechanism. - ~`SubStates` - which are essentially a hybrid of computed and manual states. In the simplest (and most likely) version, they would work by having a computed element that determines whether the state should exist, and if it should has the capacity to add a new version in, but then any changes to it's content would be freely mutated.~ this feature is now part of this PR. See above. - Lastly, since states are getting more complex there might be value in moving them out of `bevy_ecs` and into their own crate, or at least out of the `schedule` module into a `states` module. #11087 As mentioned, all these future work elements are TBD and are explicitly not part of this PR - I just wanted to provide them as potential explorations for the future. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Marcel Champagne <voiceofmarcel@gmail.com> Co-authored-by: MiniaczQ <xnetroidpl@gmail.com>
2024-05-02 19:36:23 +00:00
wasm = false
System Inputs, Outputs, Chaining, and Registration Ergo (#876) System Inputs, Outputs, Chaining, and Registration Ergo
2020-11-17 02:18:00 +00:00
[[example]]
Rename system chaining to system piping (#6230) # Objective > System chaining is a confusing name: it implies the ability to construct non-linear graphs, and suggests a sense of system ordering that is only incidentally true. Instead, it actually works by passing data from one system to the next, much like the pipe operator. > In the accepted [stageless RFC](https://github.com/bevyengine/rfcs/blob/main/rfcs/45-stageless.md), this concept is renamed to piping, and "system chaining" is used to construct groups of systems with ordering dependencies between them. Fixes #6225. ## Changelog System chaining has been renamed to system piping to improve clarity (and free up the name for new ordering APIs). ## Migration Guide The `.chain(handler_system)` method on systems is now `.pipe(handler_system)`. The `IntoChainSystem` trait is now `IntoPipeSystem`, and the `ChainSystem` struct is now `PipeSystem`.
2022-10-11 15:21:12 +00:00
name = "system_piping"
path = "examples/ecs/system_piping.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
System Inputs, Outputs, Chaining, and Registration Ergo (#876) System Inputs, Outputs, Chaining, and Registration Ergo
2020-11-17 02:18:00 +00:00
Rename system chaining to system piping (#6230) # Objective > System chaining is a confusing name: it implies the ability to construct non-linear graphs, and suggests a sense of system ordering that is only incidentally true. Instead, it actually works by passing data from one system to the next, much like the pipe operator. > In the accepted [stageless RFC](https://github.com/bevyengine/rfcs/blob/main/rfcs/45-stageless.md), this concept is renamed to piping, and "system chaining" is used to construct groups of systems with ordering dependencies between them. Fixes #6225. ## Changelog System chaining has been renamed to system piping to improve clarity (and free up the name for new ordering APIs). ## Migration Guide The `.chain(handler_system)` method on systems is now `.pipe(handler_system)`. The `IntoChainSystem` trait is now `IntoPipeSystem`, and the `ChainSystem` struct is now `PipeSystem`.
2022-10-11 15:21:12 +00:00
[package.metadata.example.system_piping]
name = "System Piping"
description = "Pipe the output of one system into a second, allowing you to handle any errors gracefully"
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
category = "ECS (Entity Component System)"
wasm = false
Added example of creating a system from a closure (#4327) Fixes #4262
2022-04-27 18:02:07 +00:00
[[example]]
name = "system_closure"
path = "examples/ecs/system_closure.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Added example of creating a system from a closure (#4327) Fixes #4262
2022-04-27 18:02:07 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.system_closure]
name = "System Closure"
description = "Show how to use closures as systems, and how to configure `Local` variables by capturing external state"
category = "ECS (Entity Component System)"
wasm = false
Add docs & example for SystemParam (#1435) It took me a little while to figure out how to use the `SystemParam` derive macro to easily create my own params. So I figured I'd add some docs and an example with what I learned. - Fixed a bug in the `SystemParam` derive macro where it didn't detect the correct crate name when used in an example (no longer relevant, replaced by #1426 - see further) - Added some doc comments and a short example code block in the docs for the `SystemParam` trait - Added a more complete example with explanatory comments in examples
2021-03-03 03:11:11 +00:00
[[example]]
name = "system_param"
path = "examples/ecs/system_param.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add docs & example for SystemParam (#1435) It took me a little while to figure out how to use the `SystemParam` derive macro to easily create my own params. So I figured I'd add some docs and an example with what I learned. - Fixed a bug in the `SystemParam` derive macro where it didn't detect the correct crate name when used in an example (no longer relevant, replaced by #1426 - see further) - Added some doc comments and a short example code block in the docs for the `SystemParam` trait - Added a more complete example with explanatory comments in examples
2021-03-03 03:11:11 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.system_param]
name = "System Parameter"
description = "Illustrates creating custom system parameters with `SystemParam`"
category = "ECS (Entity Component System)"
wasm = false
System Stepping implemented as Resource (#8453) # Objective Add interactive system debugging capabilities to bevy, providing step/break/continue style capabilities to running system schedules. * Original implementation: #8063 - `ignore_stepping()` everywhere was too much complexity * Schedule-config & Resource discussion: #8168 - Decided on selective adding of Schedules & Resource-based control ## Solution Created `Stepping` Resource. This resource can be used to enable stepping on a per-schedule basis. Systems within schedules can be individually configured to: * AlwaysRun: Ignore any stepping state and run every frame * NeverRun: Never run while stepping is enabled - this allows for disabling of systems while debugging * Break: If we're running the full frame, stop before this system is run Stepping provides two modes of execution that reflect traditional debuggers: * Step-based: Only execute one system at a time * Continue/Break: Run all systems, but stop before running a system marked as Break ### Demo https://user-images.githubusercontent.com/857742/233630981-99f3bbda-9ca6-4cc4-a00f-171c4946dc47.mov Breakout has been modified to use Stepping. The game runs normally for a couple of seconds, then stepping is enabled and the game appears to pause. A list of Schedules & Systems appears with a cursor at the first System in the list. The demo then steps forward full frames using the spacebar until the ball is about to hit a brick. Then we step system by system as the ball impacts a brick, showing the cursor moving through the individual systems. Finally the demo switches back to frame stepping as the ball changes course. ### Limitations Due to architectural constraints in bevy, there are some cases systems stepping will not function as a user would expect. #### Event-driven systems Stepping does not support systems that are driven by `Event`s as events are flushed after 1-2 frames. Although game systems are not running while stepping, ignored systems are still running every frame, so events will be flushed. This presents to the user as stepping the event-driven system never executes the system. It does execute, but the events have already been flushed. This can be resolved by changing event handling to use a buffer for events, and only dropping an event once all readers have read it. The work-around to allow these systems to properly execute during stepping is to have them ignore stepping: `app.add_systems(event_driven_system.ignore_stepping())`. This was done in the breakout example to ensure sound played even while stepping. #### Conditional Systems When a system is stepped, it is given an opportunity to run. If the conditions of the system say it should not run, it will not. Similar to Event-driven systems, if a system is conditional, and that condition is only true for a very small time window, then stepping the system may not execute the system. This includes depending on any sort of external clock. This exhibits to the user as the system not always running when it is stepped. A solution to this limitation is to ensure any conditions are consistent while stepping is enabled. For example, all systems that modify any state the condition uses should also enable stepping. #### State-transition Systems Stepping is configured on the per-`Schedule` level, requiring the user to have a `ScheduleLabel`. To support state-transition systems, bevy generates needed schedules dynamically. Currently it’s very difficult (if not impossible, I haven’t verified) for the user to get the labels for these schedules. Without ready access to the dynamically generated schedules, and a resolution for the `Event` lifetime, **stepping of the state-transition systems is not supported** --- ## Changelog - `Schedule::run()` updated to consult `Stepping` Resource to determine which Systems to run each frame - Added `Schedule.label` as a `BoxedSystemLabel`, along with supporting `Schedule::set_label()` and `Schedule::label()` methods - `Stepping` needed to know which `Schedule` was running, and prior to this PR, `Schedule` didn't track its own label - Would have preferred to add `Schedule::with_label()` and remove `Schedule::new()`, but this PR touches enough already - Added calls to `Schedule.set_label()` to `App` and `World` as needed - Added `Stepping` resource - Added `Stepping::begin_frame()` system to `MainSchedulePlugin` - Run before `Main::run_main()` - Notifies any `Stepping` Resource a new render frame is starting ## Migration Guide - Add a call to `Schedule::set_label()` for any custom `Schedule` - This is only required if the `Schedule` will be stepped --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2024-02-03 05:18:38 +00:00
[[example]]
name = "system_stepping"
path = "examples/ecs/system_stepping.rs"
doc-scrape-examples = true
Remove stepping from default features (#12847) # Objective Fix #11931 ## Solution - Make stepping a non-default feature - Adjust documentation and examples - In particular, make the breakout example not show the stepping prompt if compiled without the feature (shows a log message instead) --- ## Changelog - Removed `bevy_debug_stepping` from default features ## Migration Guide The system-by-system stepping feature is now disabled by default; to use it, enable the `bevy_debug_stepping` feature explicitly: ```toml [dependencies] bevy = { version = "0.14", features = ["bevy_debug_stepping"] } ``` Code using [`Stepping`](https://docs.rs/bevy/latest/bevy/ecs/schedule/struct.Stepping.html) will still compile with the feature disabled, but will print a runtime error message to the console if the application attempts to enable stepping. --------- Co-authored-by: James Liu <contact@jamessliu.com> Co-authored-by: François Mockers <francois.mockers@vleue.com>
2024-04-03 19:16:02 +00:00
required-features = ["bevy_debug_stepping"]
System Stepping implemented as Resource (#8453) # Objective Add interactive system debugging capabilities to bevy, providing step/break/continue style capabilities to running system schedules. * Original implementation: #8063 - `ignore_stepping()` everywhere was too much complexity * Schedule-config & Resource discussion: #8168 - Decided on selective adding of Schedules & Resource-based control ## Solution Created `Stepping` Resource. This resource can be used to enable stepping on a per-schedule basis. Systems within schedules can be individually configured to: * AlwaysRun: Ignore any stepping state and run every frame * NeverRun: Never run while stepping is enabled - this allows for disabling of systems while debugging * Break: If we're running the full frame, stop before this system is run Stepping provides two modes of execution that reflect traditional debuggers: * Step-based: Only execute one system at a time * Continue/Break: Run all systems, but stop before running a system marked as Break ### Demo https://user-images.githubusercontent.com/857742/233630981-99f3bbda-9ca6-4cc4-a00f-171c4946dc47.mov Breakout has been modified to use Stepping. The game runs normally for a couple of seconds, then stepping is enabled and the game appears to pause. A list of Schedules & Systems appears with a cursor at the first System in the list. The demo then steps forward full frames using the spacebar until the ball is about to hit a brick. Then we step system by system as the ball impacts a brick, showing the cursor moving through the individual systems. Finally the demo switches back to frame stepping as the ball changes course. ### Limitations Due to architectural constraints in bevy, there are some cases systems stepping will not function as a user would expect. #### Event-driven systems Stepping does not support systems that are driven by `Event`s as events are flushed after 1-2 frames. Although game systems are not running while stepping, ignored systems are still running every frame, so events will be flushed. This presents to the user as stepping the event-driven system never executes the system. It does execute, but the events have already been flushed. This can be resolved by changing event handling to use a buffer for events, and only dropping an event once all readers have read it. The work-around to allow these systems to properly execute during stepping is to have them ignore stepping: `app.add_systems(event_driven_system.ignore_stepping())`. This was done in the breakout example to ensure sound played even while stepping. #### Conditional Systems When a system is stepped, it is given an opportunity to run. If the conditions of the system say it should not run, it will not. Similar to Event-driven systems, if a system is conditional, and that condition is only true for a very small time window, then stepping the system may not execute the system. This includes depending on any sort of external clock. This exhibits to the user as the system not always running when it is stepped. A solution to this limitation is to ensure any conditions are consistent while stepping is enabled. For example, all systems that modify any state the condition uses should also enable stepping. #### State-transition Systems Stepping is configured on the per-`Schedule` level, requiring the user to have a `ScheduleLabel`. To support state-transition systems, bevy generates needed schedules dynamically. Currently it’s very difficult (if not impossible, I haven’t verified) for the user to get the labels for these schedules. Without ready access to the dynamically generated schedules, and a resolution for the `Event` lifetime, **stepping of the state-transition systems is not supported** --- ## Changelog - `Schedule::run()` updated to consult `Stepping` Resource to determine which Systems to run each frame - Added `Schedule.label` as a `BoxedSystemLabel`, along with supporting `Schedule::set_label()` and `Schedule::label()` methods - `Stepping` needed to know which `Schedule` was running, and prior to this PR, `Schedule` didn't track its own label - Would have preferred to add `Schedule::with_label()` and remove `Schedule::new()`, but this PR touches enough already - Added calls to `Schedule.set_label()` to `App` and `World` as needed - Added `Stepping` resource - Added `Stepping::begin_frame()` system to `MainSchedulePlugin` - Run before `Main::run_main()` - Notifies any `Stepping` Resource a new render frame is starting ## Migration Guide - Add a call to `Schedule::set_label()` for any custom `Schedule` - This is only required if the `Schedule` will be stepped --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2024-02-03 05:18:38 +00:00
[package.metadata.example.system_stepping]
name = "System Stepping"
Remove stepping from default features (#12847) # Objective Fix #11931 ## Solution - Make stepping a non-default feature - Adjust documentation and examples - In particular, make the breakout example not show the stepping prompt if compiled without the feature (shows a log message instead) --- ## Changelog - Removed `bevy_debug_stepping` from default features ## Migration Guide The system-by-system stepping feature is now disabled by default; to use it, enable the `bevy_debug_stepping` feature explicitly: ```toml [dependencies] bevy = { version = "0.14", features = ["bevy_debug_stepping"] } ``` Code using [`Stepping`](https://docs.rs/bevy/latest/bevy/ecs/schedule/struct.Stepping.html) will still compile with the feature disabled, but will print a runtime error message to the console if the application attempts to enable stepping. --------- Co-authored-by: James Liu <contact@jamessliu.com> Co-authored-by: François Mockers <francois.mockers@vleue.com>
2024-04-03 19:16:02 +00:00
description = "Demonstrate stepping through systems in order of execution."
System Stepping implemented as Resource (#8453) # Objective Add interactive system debugging capabilities to bevy, providing step/break/continue style capabilities to running system schedules. * Original implementation: #8063 - `ignore_stepping()` everywhere was too much complexity * Schedule-config & Resource discussion: #8168 - Decided on selective adding of Schedules & Resource-based control ## Solution Created `Stepping` Resource. This resource can be used to enable stepping on a per-schedule basis. Systems within schedules can be individually configured to: * AlwaysRun: Ignore any stepping state and run every frame * NeverRun: Never run while stepping is enabled - this allows for disabling of systems while debugging * Break: If we're running the full frame, stop before this system is run Stepping provides two modes of execution that reflect traditional debuggers: * Step-based: Only execute one system at a time * Continue/Break: Run all systems, but stop before running a system marked as Break ### Demo https://user-images.githubusercontent.com/857742/233630981-99f3bbda-9ca6-4cc4-a00f-171c4946dc47.mov Breakout has been modified to use Stepping. The game runs normally for a couple of seconds, then stepping is enabled and the game appears to pause. A list of Schedules & Systems appears with a cursor at the first System in the list. The demo then steps forward full frames using the spacebar until the ball is about to hit a brick. Then we step system by system as the ball impacts a brick, showing the cursor moving through the individual systems. Finally the demo switches back to frame stepping as the ball changes course. ### Limitations Due to architectural constraints in bevy, there are some cases systems stepping will not function as a user would expect. #### Event-driven systems Stepping does not support systems that are driven by `Event`s as events are flushed after 1-2 frames. Although game systems are not running while stepping, ignored systems are still running every frame, so events will be flushed. This presents to the user as stepping the event-driven system never executes the system. It does execute, but the events have already been flushed. This can be resolved by changing event handling to use a buffer for events, and only dropping an event once all readers have read it. The work-around to allow these systems to properly execute during stepping is to have them ignore stepping: `app.add_systems(event_driven_system.ignore_stepping())`. This was done in the breakout example to ensure sound played even while stepping. #### Conditional Systems When a system is stepped, it is given an opportunity to run. If the conditions of the system say it should not run, it will not. Similar to Event-driven systems, if a system is conditional, and that condition is only true for a very small time window, then stepping the system may not execute the system. This includes depending on any sort of external clock. This exhibits to the user as the system not always running when it is stepped. A solution to this limitation is to ensure any conditions are consistent while stepping is enabled. For example, all systems that modify any state the condition uses should also enable stepping. #### State-transition Systems Stepping is configured on the per-`Schedule` level, requiring the user to have a `ScheduleLabel`. To support state-transition systems, bevy generates needed schedules dynamically. Currently it’s very difficult (if not impossible, I haven’t verified) for the user to get the labels for these schedules. Without ready access to the dynamically generated schedules, and a resolution for the `Event` lifetime, **stepping of the state-transition systems is not supported** --- ## Changelog - `Schedule::run()` updated to consult `Stepping` Resource to determine which Systems to run each frame - Added `Schedule.label` as a `BoxedSystemLabel`, along with supporting `Schedule::set_label()` and `Schedule::label()` methods - `Stepping` needed to know which `Schedule` was running, and prior to this PR, `Schedule` didn't track its own label - Would have preferred to add `Schedule::with_label()` and remove `Schedule::new()`, but this PR touches enough already - Added calls to `Schedule.set_label()` to `App` and `World` as needed - Added `Stepping` resource - Added `Stepping::begin_frame()` system to `MainSchedulePlugin` - Run before `Main::run_main()` - Notifies any `Stepping` Resource a new render frame is starting ## Migration Guide - Add a call to `Schedule::set_label()` for any custom `Schedule` - This is only required if the `Schedule` will be stepped --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2024-02-03 05:18:38 +00:00
category = "ECS (Entity Component System)"
wasm = false
Example time api (#10204) # Objective - Fixes #10133 ## Solution - Add a new example that focuses on using `Virtual` time ## Changelog ### Added - new `virtual_time` example ### Changed - moved `time` & `timers` examples to the new `examples/time` folder
2023-10-28 16:05:03 +00:00
# Time
Unify `FixedTime` and `Time` while fixing several problems (#8964) # Objective Current `FixedTime` and `Time` have several problems. This pull aims to fix many of them at once. - If there is a longer pause between app updates, time will jump forward a lot at once and fixed time will iterate on `FixedUpdate` for a large number of steps. If the pause is merely seconds, then this will just mean jerkiness and possible unexpected behaviour in gameplay. If the pause is hours/days as with OS suspend, the game will appear to freeze until it has caught up with real time. - If calculating a fixed step takes longer than specified fixed step period, the game will enter a death spiral where rendering each frame takes longer and longer due to more and more fixed step updates being run per frame and the game appears to freeze. - There is no way to see current fixed step elapsed time inside fixed steps. In order to track this, the game designer needs to add a custom system inside `FixedUpdate` that calculates elapsed or step count in a resource. - Access to delta time inside fixed step is `FixedStep::period` rather than `Time::delta`. This, coupled with the issue that `Time::elapsed` isn't available at all for fixed steps, makes it that time requiring systems are either implemented to be run in `FixedUpdate` or `Update`, but rarely work in both. - Fixes #8800 - Fixes #8543 - Fixes #7439 - Fixes #5692 ## Solution - Create a generic `Time<T>` clock that has no processing logic but which can be instantiated for multiple usages. This is also exposed for users to add custom clocks. - Create three standard clocks, `Time<Real>`, `Time<Virtual>` and `Time<Fixed>`, all of which contain their individual logic. - Create one "default" clock, which is just `Time` (or `Time<()>`), which will be overwritten from `Time<Virtual>` on each update, and `Time<Fixed>` inside `FixedUpdate` schedule. This way systems that do not care specifically which time they track can work both in `Update` and `FixedUpdate` without changes and the behaviour is intuitive. - Add `max_delta` to virtual time update, which limits how much can be added to virtual time by a single update. This fixes both the behaviour after a long freeze, and also the death spiral by limiting how many fixed timestep iterations there can be per update. Possible future work could be adding `max_accumulator` to add a sort of "leaky bucket" time processing to possibly smooth out jumps in time while keeping frame rate stable. - Many minor tweaks and clarifications to the time functions and their documentation. ## Changelog - `Time::raw_delta()`, `Time::raw_elapsed()` and related methods are moved to `Time<Real>::delta()` and `Time<Real>::elapsed()` and now match `Time` API - `FixedTime` is now `Time<Fixed>` and matches `Time` API. - `Time<Fixed>` default timestep is now 64 Hz, or 15625 microseconds. - `Time` inside `FixedUpdate` now reflects fixed timestep time, making systems portable between `Update ` and `FixedUpdate`. - `Time::pause()`, `Time::set_relative_speed()` and related methods must now be called as `Time<Virtual>::pause()` etc. - There is a new `max_delta` setting in `Time<Virtual>` that limits how much the clock can jump by a single update. The default value is 0.25 seconds. - Removed `on_fixed_timer()` condition as `on_timer()` does the right thing inside `FixedUpdate` now. ## Migration Guide - Change all `Res<Time>` instances that access `raw_delta()`, `raw_elapsed()` and related methods to `Res<Time<Real>>` and `delta()`, `elapsed()`, etc. - Change access to `period` from `Res<FixedTime>` to `Res<Time<Fixed>>` and use `delta()`. - The default timestep has been changed from 60 Hz to 64 Hz. If you wish to restore the old behaviour, use `app.insert_resource(Time::<Fixed>::from_hz(60.0))`. - Change `app.insert_resource(FixedTime::new(duration))` to `app.insert_resource(Time::<Fixed>::from_duration(duration))` - Change `app.insert_resource(FixedTime::new_from_secs(secs))` to `app.insert_resource(Time::<Fixed>::from_seconds(secs))` - Change `system.on_fixed_timer(duration)` to `system.on_timer(duration)`. Timers in systems placed in `FixedUpdate` schedule automatically use the fixed time clock. - Change `ResMut<Time>` calls to `pause()`, `is_paused()`, `set_relative_speed()` and related methods to `ResMut<Time<Virtual>>` calls. The API is the same, with the exception that `relative_speed()` will return the actual last ste relative speed, while `effective_relative_speed()` returns 0.0 if the time is paused and corresponds to the speed that was set when the update for the current frame started. ## Todo - [x] Update pull name and description - [x] Top level documentation on usage - [x] Fix examples - [x] Decide on default `max_delta` value - [x] Decide naming of the three clocks: is `Real`, `Virtual`, `Fixed` good? - [x] Decide if the three clock inner structures should be in prelude - [x] Decide on best way to configure values at startup: is manually inserting a new clock instance okay, or should there be config struct separately? - [x] Fix links in docs - [x] Decide what should be public and what not - [x] Decide how `wrap_period` should be handled when it is changed - [x] ~~Add toggles to disable setting the clock as default?~~ No, separate pull if needed. - [x] Add tests - [x] Reformat, ensure adheres to conventions etc. - [x] Build documentation and see that it looks correct ## Contributors Huge thanks to @alice-i-cecile and @maniwani while building this pull. It was a shared effort! --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Cameron <51241057+maniwani@users.noreply.github.com> Co-authored-by: Jerome Humbert <djeedai@gmail.com>
2023-10-16 01:57:55 +00:00
[[example]]
name = "time"
Example time api (#10204) # Objective - Fixes #10133 ## Solution - Add a new example that focuses on using `Virtual` time ## Changelog ### Added - new `virtual_time` example ### Changed - moved `time` & `timers` examples to the new `examples/time` folder
2023-10-28 16:05:03 +00:00
path = "examples/time/time.rs"
Fix some doc warnings (#12961) # Objective - Fix some doc warnings - Add doc-scrape-examples to all examples Moved from #12692 I run `cargo +nightly doc --workspace --all-features --no-deps -Zunstable-options -Zrustdoc-scrape-examples` <details> ``` warning: public documentation for `GzAssetLoaderError` links to private item `GzAssetLoader` --> examples/asset/asset_decompression.rs:24:47 | 24 | /// Possible errors that can be produced by [`GzAssetLoader`] | ^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: `bevy` (example "asset_decompression") generated 1 warning warning: unresolved link to `shape::Quad` --> examples/2d/mesh2d.rs:3:15 | 3 | //! [`Quad`]: shape::Quad | ^^^^^^^^^^^ no item named `shape` in scope | = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "mesh2d") generated 1 warning warning: unresolved link to `WorldQuery` --> examples/ecs/custom_query_param.rs:1:49 | 1 | //! This example illustrates the usage of the [`WorldQuery`] derive macro, which allows | ^^^^^^^^^^ no item named `WorldQuery` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "custom_query_param") generated 1 warning warning: unresolved link to `shape::Quad` --> examples/2d/mesh2d_vertex_color_texture.rs:4:15 | 4 | //! [`Quad`]: shape::Quad | ^^^^^^^^^^^ no item named `shape` in scope | = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "mesh2d_vertex_color_texture") generated 1 warning warning: public documentation for `TextPlugin` links to private item `CoolText` --> examples/asset/processing/asset_processing.rs:48:9 | 48 | /// * [`CoolText`]: a custom RON text format that supports dependencies and embedded dependencies | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: public documentation for `TextPlugin` links to private item `Text` --> examples/asset/processing/asset_processing.rs:49:9 | 49 | /// * [`Text`]: a "normal" plain text file | ^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: public documentation for `TextPlugin` links to private item `CoolText` --> examples/asset/processing/asset_processing.rs:51:57 | 51 | /// It also defines an asset processor that will load [`CoolText`], resolve embedded dependenc... | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: `bevy` (example "asset_processing") generated 3 warnings warning: public documentation for `CustomAssetLoaderError` links to private item `CustomAssetLoader` --> examples/asset/custom_asset.rs:20:47 | 20 | /// Possible errors that can be produced by [`CustomAssetLoader`] | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: public documentation for `BlobAssetLoaderError` links to private item `CustomAssetLoader` --> examples/asset/custom_asset.rs:61:47 | 61 | /// Possible errors that can be produced by [`CustomAssetLoader`] | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` ``` ``` warning: `bevy` (example "mesh2d") generated 1 warning warning: public documentation for `log_layers_ecs` links to private item `update_subscriber` --> examples/app/log_layers_ecs.rs:6:18 | 6 | //! Inside the [`update_subscriber`] function we will create a [`mpsc::Sender`] and a [`mpsc::R... | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: unresolved link to `AdvancedLayer` --> examples/app/log_layers_ecs.rs:7:72 | 7 | ... will go into the [`AdvancedLayer`] and the [`Receiver`](mpsc::Receiver) will | ^^^^^^^^^^^^^ no item named `AdvancedLayer` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: unresolved link to `LogEvents` --> examples/app/log_layers_ecs.rs:8:42 | 8 | //! go into a non-send resource called [`LogEvents`] (It has to be non-send because [`Receiver`... | ^^^^^^^^^ no item named `LogEvents` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` warning: public documentation for `log_layers_ecs` links to private item `transfer_log_events` --> examples/app/log_layers_ecs.rs:9:30 | 9 | //! From there we will use [`transfer_log_events`] to transfer log events from [`LogEvents`] to... | ^^^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: unresolved link to `LogEvents` --> examples/app/log_layers_ecs.rs:9:82 | 9 | ...nsfer log events from [`LogEvents`] to an ECS event called [`LogEvent`]. | ^^^^^^^^^ no item named `LogEvents` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` warning: public documentation for `log_layers_ecs` links to private item `LogEvent` --> examples/app/log_layers_ecs.rs:9:119 | 9 | ...nts`] to an ECS event called [`LogEvent`]. | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: public documentation for `log_layers_ecs` links to private item `LogEvent` --> examples/app/log_layers_ecs.rs:11:49 | 11 | //! Finally, after all that we can access the [`LogEvent`] event from our systems and use it. | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` ``` <details/>
2024-04-14 15:23:44 +00:00
doc-scrape-examples = true
Unify `FixedTime` and `Time` while fixing several problems (#8964) # Objective Current `FixedTime` and `Time` have several problems. This pull aims to fix many of them at once. - If there is a longer pause between app updates, time will jump forward a lot at once and fixed time will iterate on `FixedUpdate` for a large number of steps. If the pause is merely seconds, then this will just mean jerkiness and possible unexpected behaviour in gameplay. If the pause is hours/days as with OS suspend, the game will appear to freeze until it has caught up with real time. - If calculating a fixed step takes longer than specified fixed step period, the game will enter a death spiral where rendering each frame takes longer and longer due to more and more fixed step updates being run per frame and the game appears to freeze. - There is no way to see current fixed step elapsed time inside fixed steps. In order to track this, the game designer needs to add a custom system inside `FixedUpdate` that calculates elapsed or step count in a resource. - Access to delta time inside fixed step is `FixedStep::period` rather than `Time::delta`. This, coupled with the issue that `Time::elapsed` isn't available at all for fixed steps, makes it that time requiring systems are either implemented to be run in `FixedUpdate` or `Update`, but rarely work in both. - Fixes #8800 - Fixes #8543 - Fixes #7439 - Fixes #5692 ## Solution - Create a generic `Time<T>` clock that has no processing logic but which can be instantiated for multiple usages. This is also exposed for users to add custom clocks. - Create three standard clocks, `Time<Real>`, `Time<Virtual>` and `Time<Fixed>`, all of which contain their individual logic. - Create one "default" clock, which is just `Time` (or `Time<()>`), which will be overwritten from `Time<Virtual>` on each update, and `Time<Fixed>` inside `FixedUpdate` schedule. This way systems that do not care specifically which time they track can work both in `Update` and `FixedUpdate` without changes and the behaviour is intuitive. - Add `max_delta` to virtual time update, which limits how much can be added to virtual time by a single update. This fixes both the behaviour after a long freeze, and also the death spiral by limiting how many fixed timestep iterations there can be per update. Possible future work could be adding `max_accumulator` to add a sort of "leaky bucket" time processing to possibly smooth out jumps in time while keeping frame rate stable. - Many minor tweaks and clarifications to the time functions and their documentation. ## Changelog - `Time::raw_delta()`, `Time::raw_elapsed()` and related methods are moved to `Time<Real>::delta()` and `Time<Real>::elapsed()` and now match `Time` API - `FixedTime` is now `Time<Fixed>` and matches `Time` API. - `Time<Fixed>` default timestep is now 64 Hz, or 15625 microseconds. - `Time` inside `FixedUpdate` now reflects fixed timestep time, making systems portable between `Update ` and `FixedUpdate`. - `Time::pause()`, `Time::set_relative_speed()` and related methods must now be called as `Time<Virtual>::pause()` etc. - There is a new `max_delta` setting in `Time<Virtual>` that limits how much the clock can jump by a single update. The default value is 0.25 seconds. - Removed `on_fixed_timer()` condition as `on_timer()` does the right thing inside `FixedUpdate` now. ## Migration Guide - Change all `Res<Time>` instances that access `raw_delta()`, `raw_elapsed()` and related methods to `Res<Time<Real>>` and `delta()`, `elapsed()`, etc. - Change access to `period` from `Res<FixedTime>` to `Res<Time<Fixed>>` and use `delta()`. - The default timestep has been changed from 60 Hz to 64 Hz. If you wish to restore the old behaviour, use `app.insert_resource(Time::<Fixed>::from_hz(60.0))`. - Change `app.insert_resource(FixedTime::new(duration))` to `app.insert_resource(Time::<Fixed>::from_duration(duration))` - Change `app.insert_resource(FixedTime::new_from_secs(secs))` to `app.insert_resource(Time::<Fixed>::from_seconds(secs))` - Change `system.on_fixed_timer(duration)` to `system.on_timer(duration)`. Timers in systems placed in `FixedUpdate` schedule automatically use the fixed time clock. - Change `ResMut<Time>` calls to `pause()`, `is_paused()`, `set_relative_speed()` and related methods to `ResMut<Time<Virtual>>` calls. The API is the same, with the exception that `relative_speed()` will return the actual last ste relative speed, while `effective_relative_speed()` returns 0.0 if the time is paused and corresponds to the speed that was set when the update for the current frame started. ## Todo - [x] Update pull name and description - [x] Top level documentation on usage - [x] Fix examples - [x] Decide on default `max_delta` value - [x] Decide naming of the three clocks: is `Real`, `Virtual`, `Fixed` good? - [x] Decide if the three clock inner structures should be in prelude - [x] Decide on best way to configure values at startup: is manually inserting a new clock instance okay, or should there be config struct separately? - [x] Fix links in docs - [x] Decide what should be public and what not - [x] Decide how `wrap_period` should be handled when it is changed - [x] ~~Add toggles to disable setting the clock as default?~~ No, separate pull if needed. - [x] Add tests - [x] Reformat, ensure adheres to conventions etc. - [x] Build documentation and see that it looks correct ## Contributors Huge thanks to @alice-i-cecile and @maniwani while building this pull. It was a shared effort! --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Cameron <51241057+maniwani@users.noreply.github.com> Co-authored-by: Jerome Humbert <djeedai@gmail.com>
2023-10-16 01:57:55 +00:00
[package.metadata.example.time]
name = "Time handling"
description = "Explains how Time is handled in ECS"
Example time api (#10204) # Objective - Fixes #10133 ## Solution - Add a new example that focuses on using `Virtual` time ## Changelog ### Added - new `virtual_time` example ### Changed - moved `time` & `timers` examples to the new `examples/time` folder
2023-10-28 16:05:03 +00:00
category = "Time"
wasm = false
[[example]]
name = "virtual_time"
path = "examples/time/virtual_time.rs"
Fix some doc warnings (#12961) # Objective - Fix some doc warnings - Add doc-scrape-examples to all examples Moved from #12692 I run `cargo +nightly doc --workspace --all-features --no-deps -Zunstable-options -Zrustdoc-scrape-examples` <details> ``` warning: public documentation for `GzAssetLoaderError` links to private item `GzAssetLoader` --> examples/asset/asset_decompression.rs:24:47 | 24 | /// Possible errors that can be produced by [`GzAssetLoader`] | ^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: `bevy` (example "asset_decompression") generated 1 warning warning: unresolved link to `shape::Quad` --> examples/2d/mesh2d.rs:3:15 | 3 | //! [`Quad`]: shape::Quad | ^^^^^^^^^^^ no item named `shape` in scope | = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "mesh2d") generated 1 warning warning: unresolved link to `WorldQuery` --> examples/ecs/custom_query_param.rs:1:49 | 1 | //! This example illustrates the usage of the [`WorldQuery`] derive macro, which allows | ^^^^^^^^^^ no item named `WorldQuery` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "custom_query_param") generated 1 warning warning: unresolved link to `shape::Quad` --> examples/2d/mesh2d_vertex_color_texture.rs:4:15 | 4 | //! [`Quad`]: shape::Quad | ^^^^^^^^^^^ no item named `shape` in scope | = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "mesh2d_vertex_color_texture") generated 1 warning warning: public documentation for `TextPlugin` links to private item `CoolText` --> examples/asset/processing/asset_processing.rs:48:9 | 48 | /// * [`CoolText`]: a custom RON text format that supports dependencies and embedded dependencies | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: public documentation for `TextPlugin` links to private item `Text` --> examples/asset/processing/asset_processing.rs:49:9 | 49 | /// * [`Text`]: a "normal" plain text file | ^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: public documentation for `TextPlugin` links to private item `CoolText` --> examples/asset/processing/asset_processing.rs:51:57 | 51 | /// It also defines an asset processor that will load [`CoolText`], resolve embedded dependenc... | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: `bevy` (example "asset_processing") generated 3 warnings warning: public documentation for `CustomAssetLoaderError` links to private item `CustomAssetLoader` --> examples/asset/custom_asset.rs:20:47 | 20 | /// Possible errors that can be produced by [`CustomAssetLoader`] | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: public documentation for `BlobAssetLoaderError` links to private item `CustomAssetLoader` --> examples/asset/custom_asset.rs:61:47 | 61 | /// Possible errors that can be produced by [`CustomAssetLoader`] | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` ``` ``` warning: `bevy` (example "mesh2d") generated 1 warning warning: public documentation for `log_layers_ecs` links to private item `update_subscriber` --> examples/app/log_layers_ecs.rs:6:18 | 6 | //! Inside the [`update_subscriber`] function we will create a [`mpsc::Sender`] and a [`mpsc::R... | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: unresolved link to `AdvancedLayer` --> examples/app/log_layers_ecs.rs:7:72 | 7 | ... will go into the [`AdvancedLayer`] and the [`Receiver`](mpsc::Receiver) will | ^^^^^^^^^^^^^ no item named `AdvancedLayer` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: unresolved link to `LogEvents` --> examples/app/log_layers_ecs.rs:8:42 | 8 | //! go into a non-send resource called [`LogEvents`] (It has to be non-send because [`Receiver`... | ^^^^^^^^^ no item named `LogEvents` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` warning: public documentation for `log_layers_ecs` links to private item `transfer_log_events` --> examples/app/log_layers_ecs.rs:9:30 | 9 | //! From there we will use [`transfer_log_events`] to transfer log events from [`LogEvents`] to... | ^^^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: unresolved link to `LogEvents` --> examples/app/log_layers_ecs.rs:9:82 | 9 | ...nsfer log events from [`LogEvents`] to an ECS event called [`LogEvent`]. | ^^^^^^^^^ no item named `LogEvents` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` warning: public documentation for `log_layers_ecs` links to private item `LogEvent` --> examples/app/log_layers_ecs.rs:9:119 | 9 | ...nts`] to an ECS event called [`LogEvent`]. | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: public documentation for `log_layers_ecs` links to private item `LogEvent` --> examples/app/log_layers_ecs.rs:11:49 | 11 | //! Finally, after all that we can access the [`LogEvent`] event from our systems and use it. | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` ``` <details/>
2024-04-14 15:23:44 +00:00
doc-scrape-examples = true
Example time api (#10204) # Objective - Fixes #10133 ## Solution - Add a new example that focuses on using `Virtual` time ## Changelog ### Added - new `virtual_time` example ### Changed - moved `time` & `timers` examples to the new `examples/time` folder
2023-10-28 16:05:03 +00:00
[package.metadata.example.virtual_time]
name = "Virtual time"
description = "Shows how `Time<Virtual>` can be used to pause, resume, slow down and speed up a game."
category = "Time"
Unify `FixedTime` and `Time` while fixing several problems (#8964) # Objective Current `FixedTime` and `Time` have several problems. This pull aims to fix many of them at once. - If there is a longer pause between app updates, time will jump forward a lot at once and fixed time will iterate on `FixedUpdate` for a large number of steps. If the pause is merely seconds, then this will just mean jerkiness and possible unexpected behaviour in gameplay. If the pause is hours/days as with OS suspend, the game will appear to freeze until it has caught up with real time. - If calculating a fixed step takes longer than specified fixed step period, the game will enter a death spiral where rendering each frame takes longer and longer due to more and more fixed step updates being run per frame and the game appears to freeze. - There is no way to see current fixed step elapsed time inside fixed steps. In order to track this, the game designer needs to add a custom system inside `FixedUpdate` that calculates elapsed or step count in a resource. - Access to delta time inside fixed step is `FixedStep::period` rather than `Time::delta`. This, coupled with the issue that `Time::elapsed` isn't available at all for fixed steps, makes it that time requiring systems are either implemented to be run in `FixedUpdate` or `Update`, but rarely work in both. - Fixes #8800 - Fixes #8543 - Fixes #7439 - Fixes #5692 ## Solution - Create a generic `Time<T>` clock that has no processing logic but which can be instantiated for multiple usages. This is also exposed for users to add custom clocks. - Create three standard clocks, `Time<Real>`, `Time<Virtual>` and `Time<Fixed>`, all of which contain their individual logic. - Create one "default" clock, which is just `Time` (or `Time<()>`), which will be overwritten from `Time<Virtual>` on each update, and `Time<Fixed>` inside `FixedUpdate` schedule. This way systems that do not care specifically which time they track can work both in `Update` and `FixedUpdate` without changes and the behaviour is intuitive. - Add `max_delta` to virtual time update, which limits how much can be added to virtual time by a single update. This fixes both the behaviour after a long freeze, and also the death spiral by limiting how many fixed timestep iterations there can be per update. Possible future work could be adding `max_accumulator` to add a sort of "leaky bucket" time processing to possibly smooth out jumps in time while keeping frame rate stable. - Many minor tweaks and clarifications to the time functions and their documentation. ## Changelog - `Time::raw_delta()`, `Time::raw_elapsed()` and related methods are moved to `Time<Real>::delta()` and `Time<Real>::elapsed()` and now match `Time` API - `FixedTime` is now `Time<Fixed>` and matches `Time` API. - `Time<Fixed>` default timestep is now 64 Hz, or 15625 microseconds. - `Time` inside `FixedUpdate` now reflects fixed timestep time, making systems portable between `Update ` and `FixedUpdate`. - `Time::pause()`, `Time::set_relative_speed()` and related methods must now be called as `Time<Virtual>::pause()` etc. - There is a new `max_delta` setting in `Time<Virtual>` that limits how much the clock can jump by a single update. The default value is 0.25 seconds. - Removed `on_fixed_timer()` condition as `on_timer()` does the right thing inside `FixedUpdate` now. ## Migration Guide - Change all `Res<Time>` instances that access `raw_delta()`, `raw_elapsed()` and related methods to `Res<Time<Real>>` and `delta()`, `elapsed()`, etc. - Change access to `period` from `Res<FixedTime>` to `Res<Time<Fixed>>` and use `delta()`. - The default timestep has been changed from 60 Hz to 64 Hz. If you wish to restore the old behaviour, use `app.insert_resource(Time::<Fixed>::from_hz(60.0))`. - Change `app.insert_resource(FixedTime::new(duration))` to `app.insert_resource(Time::<Fixed>::from_duration(duration))` - Change `app.insert_resource(FixedTime::new_from_secs(secs))` to `app.insert_resource(Time::<Fixed>::from_seconds(secs))` - Change `system.on_fixed_timer(duration)` to `system.on_timer(duration)`. Timers in systems placed in `FixedUpdate` schedule automatically use the fixed time clock. - Change `ResMut<Time>` calls to `pause()`, `is_paused()`, `set_relative_speed()` and related methods to `ResMut<Time<Virtual>>` calls. The API is the same, with the exception that `relative_speed()` will return the actual last ste relative speed, while `effective_relative_speed()` returns 0.0 if the time is paused and corresponds to the speed that was set when the update for the current frame started. ## Todo - [x] Update pull name and description - [x] Top level documentation on usage - [x] Fix examples - [x] Decide on default `max_delta` value - [x] Decide naming of the three clocks: is `Real`, `Virtual`, `Fixed` good? - [x] Decide if the three clock inner structures should be in prelude - [x] Decide on best way to configure values at startup: is manually inserting a new clock instance okay, or should there be config struct separately? - [x] Fix links in docs - [x] Decide what should be public and what not - [x] Decide how `wrap_period` should be handled when it is changed - [x] ~~Add toggles to disable setting the clock as default?~~ No, separate pull if needed. - [x] Add tests - [x] Reformat, ensure adheres to conventions etc. - [x] Build documentation and see that it looks correct ## Contributors Huge thanks to @alice-i-cecile and @maniwani while building this pull. It was a shared effort! --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Cameron <51241057+maniwani@users.noreply.github.com> Co-authored-by: Jerome Humbert <djeedai@gmail.com>
2023-10-16 01:57:55 +00:00
wasm = false
Timer Polishing (#931) * Pause stops ticks. Consistent getter method names. Update tests. * Add timing example * Format with the nightly formatter Co-authored-by: Amber Kowalski <amberkowalski03@gmail.com>
2020-11-27 19:39:33 +00:00
[[example]]
name = "timers"
Example time api (#10204) # Objective - Fixes #10133 ## Solution - Add a new example that focuses on using `Virtual` time ## Changelog ### Added - new `virtual_time` example ### Changed - moved `time` & `timers` examples to the new `examples/time` folder
2023-10-28 16:05:03 +00:00
path = "examples/time/timers.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Timer Polishing (#931) * Pause stops ticks. Consistent getter method names. Update tests. * Add timing example * Format with the nightly formatter Co-authored-by: Amber Kowalski <amberkowalski03@gmail.com>
2020-11-27 19:39:33 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.timers]
name = "Timers"
description = "Illustrates ticking `Timer` resources inside systems and handling their state"
Example time api (#10204) # Objective - Fixes #10133 ## Solution - Add a new example that focuses on using `Virtual` time ## Changelog ### Added - new `virtual_time` example ### Changed - moved `time` & `timers` examples to the new `examples/time` folder
2023-10-28 16:05:03 +00:00
category = "Time"
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
wasm = false
Example time api (#10204) # Objective - Fixes #10133 ## Solution - Add a new example that focuses on using `Virtual` time ## Changelog ### Added - new `virtual_time` example ### Changed - moved `time` & `timers` examples to the new `examples/time` folder
2023-10-28 16:05:03 +00:00
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
# Games
3d game example (#1252) 3d game example
2021-01-21 22:10:02 +00:00
[[example]]
name = "alien_cake_addict"
Group stress test examples (#4289) # Objective - Several examples are useful for qualitative tests of Bevy's performance - By contrast, these are less useful for learning material: they are often relatively complex and have large amounts of setup and are performance optimized. ## Solution - Move bevymark, many_sprites and many_cubes into the new stress_tests example folder - Move contributors into the games folder: unlike the remaining examples in the 2d folder, it is not focused on demonstrating a clear feature.
2022-04-10 02:05:21 +00:00
path = "examples/games/alien_cake_addict.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
3d game example (#1252) 3d game example
2021-01-21 22:10:02 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.alien_cake_addict]
name = "Alien Cake Addict"
description = "Eat the cakes. Eat them all. An example 3D game"
category = "Games"
wasm = true
add breakout example game
2020-06-27 04:40:09 +00:00
[[example]]
name = "breakout"
Group stress test examples (#4289) # Objective - Several examples are useful for qualitative tests of Bevy's performance - By contrast, these are less useful for learning material: they are often relatively complex and have large amounts of setup and are performance optimized. ## Solution - Move bevymark, many_sprites and many_cubes into the new stress_tests example folder - Move contributors into the games folder: unlike the remaining examples in the 2d folder, it is not focused on demonstrating a clear feature.
2022-04-10 02:05:21 +00:00
path = "examples/games/breakout.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Group stress test examples (#4289) # Objective - Several examples are useful for qualitative tests of Bevy's performance - By contrast, these are less useful for learning material: they are often relatively complex and have large amounts of setup and are performance optimized. ## Solution - Move bevymark, many_sprites and many_cubes into the new stress_tests example folder - Move contributors into the games folder: unlike the remaining examples in the 2d folder, it is not focused on demonstrating a clear feature.
2022-04-10 02:05:21 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.breakout]
name = "Breakout"
Remove stepping from default features (#12847) # Objective Fix #11931 ## Solution - Make stepping a non-default feature - Adjust documentation and examples - In particular, make the breakout example not show the stepping prompt if compiled without the feature (shows a log message instead) --- ## Changelog - Removed `bevy_debug_stepping` from default features ## Migration Guide The system-by-system stepping feature is now disabled by default; to use it, enable the `bevy_debug_stepping` feature explicitly: ```toml [dependencies] bevy = { version = "0.14", features = ["bevy_debug_stepping"] } ``` Code using [`Stepping`](https://docs.rs/bevy/latest/bevy/ecs/schedule/struct.Stepping.html) will still compile with the feature disabled, but will print a runtime error message to the console if the application attempts to enable stepping. --------- Co-authored-by: James Liu <contact@jamessliu.com> Co-authored-by: François Mockers <francois.mockers@vleue.com>
2024-04-03 19:16:02 +00:00
description = "An implementation of the classic game \"Breakout\"."
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
category = "Games"
wasm = true
Group stress test examples (#4289) # Objective - Several examples are useful for qualitative tests of Bevy's performance - By contrast, these are less useful for learning material: they are often relatively complex and have large amounts of setup and are performance optimized. ## Solution - Move bevymark, many_sprites and many_cubes into the new stress_tests example folder - Move contributors into the games folder: unlike the remaining examples in the 2d folder, it is not focused on demonstrating a clear feature.
2022-04-10 02:05:21 +00:00
[[example]]
name = "contributors"
path = "examples/games/contributors.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
add breakout example game
2020-06-27 04:40:09 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.contributors]
name = "Contributors"
description = "Displays each contributor as a bouncy bevy-ball!"
category = "Games"
wasm = true
We must have googly eyes (new Game example) (#12331) # Objective - We must have googly eyes. - Also it would be nice if there was an example of a desk toy application (like the old NEKO.EXE). ## Solution - Created an example with googly eyed Bevy logo under examples/games/desktoy.rs. --- ## Changelog - Added "Desk Toy" game example showcasing window transparency and hit test. --------- Co-authored-by: Rob Parrett <robparrett@gmail.com>
2024-03-06 22:21:41 +00:00
[[example]]
name = "desk_toy"
path = "examples/games/desk_toy.rs"
doc-scrape-examples = true
[package.metadata.example.desk_toy]
name = "Desk Toy"
description = "Bevy logo as a desk toy using transparent windows! Now with Googly Eyes!"
category = "Games"
wasm = false
add an example using UI & states to create a game menu (#2960) adds an example using UI for something more related to a game than the current UI examples. Example with a game menu: * new game - will display settings for 5 seconds before returning to menu * preferences - can modify the settings, with two sub menus * quit - will quit the game I wanted a more complex UI example before starting the UI rewrite to have ground for comparison Co-authored-by: François <8672791+mockersf@users.noreply.github.com>
2022-01-14 19:09:42 +00:00
[[example]]
name = "game_menu"
Group stress test examples (#4289) # Objective - Several examples are useful for qualitative tests of Bevy's performance - By contrast, these are less useful for learning material: they are often relatively complex and have large amounts of setup and are performance optimized. ## Solution - Move bevymark, many_sprites and many_cubes into the new stress_tests example folder - Move contributors into the games folder: unlike the remaining examples in the 2d folder, it is not focused on demonstrating a clear feature.
2022-04-10 02:05:21 +00:00
path = "examples/games/game_menu.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
add an example using UI & states to create a game menu (#2960) adds an example using UI for something more related to a game than the current UI examples. Example with a game menu: * new game - will display settings for 5 seconds before returning to menu * preferences - can modify the settings, with two sub menus * quit - will quit the game I wanted a more complex UI example before starting the UI rewrite to have ground for comparison Co-authored-by: François <8672791+mockersf@users.noreply.github.com>
2022-01-14 19:09:42 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.game_menu]
name = "Game Menu"
description = "A simple game menu"
category = "Games"
wasm = true
Created loading screen example (#12863) Allows the user to select a scene to load, then a loading screen is shown until all assets are loaded, and pipelines compiled. # Objective - Fixes #12654 ## Solution - Add desired assets to be monitored to a list. - While there are assets that are not fully loaded, show a loading screen. - Once all assets are loaded, and pipelines compiled, show the scene that was loaded.
2024-04-09 12:50:19 +00:00
[[example]]
name = "loading_screen"
path = "examples/games/loading_screen.rs"
doc-scrape-examples = true
[package.metadata.example.loading_screen]
name = "Loading Screen"
description = "Demonstrates how to create a loading screen that waits for all assets to be loaded and render pipelines to be compiled."
category = "Games"
wasm = true
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
# Input
organize examples and add ecs guide
2020-05-01 20:12:47 +00:00
[[example]]
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
name = "char_input_events"
path = "examples/input/char_input_events.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
organize examples and add ecs guide
2020-05-01 20:12:47 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.char_input_events]
name = "Char Input Events"
description = "Prints out all chars as they are inputted"
category = "Input"
wasm = false
organize examples and add ecs guide
2020-05-01 20:12:47 +00:00
[[example]]
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
name = "gamepad_input"
path = "examples/input/gamepad_input.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.gamepad_input]
name = "Gamepad Input"
description = "Shows handling of gamepad input, connections, and disconnections"
category = "Input"
wasm = false
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
[[example]]
name = "gamepad_input_events"
path = "examples/input/gamepad_input_events.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
break up input examples
2020-06-05 06:49:36 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.gamepad_input_events]
name = "Gamepad Input Events"
description = "Iterates and prints gamepad input and connection events"
category = "Input"
Add gamepad rumble support to bevy_input (#8398) # Objective Provide the ability to trigger controller rumbling (force-feedback) with a cross-platform API. ## Solution This adds the `GamepadRumbleRequest` event to `bevy_input` and adds a system in `bevy_gilrs` to read them and rumble controllers accordingly. It's a relatively primitive API with a `duration` in seconds and `GamepadRumbleIntensity` with values for the weak and strong gamepad motors. It's is an almost 1-to-1 mapping to platform APIs. Some platforms refer to these motors as left and right, and low frequency and high frequency, but by convention, they're usually the same. I used #3868 as a starting point, updated to main, removed the low-level gilrs effect API, and moved the requests to `bevy_input` and exposed the strong and weak intensities. I intend this to hopefully be a non-controversial cross-platform starting point we can build upon to eventually support more fine-grained control (closer to the gilrs effect API) --- ## Changelog ### Added - Gamepads can now be rumbled by sending the `GamepadRumbleRequest` event. --------- Co-authored-by: Nicola Papale <nico@nicopap.ch> Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Nicola Papale <nicopap@users.noreply.github.com> Co-authored-by: Bruce Reif (Buswolley) <bruce.reif@dynata.com>
2023-04-24 15:28:53 +00:00
wasm = false
[[example]]
name = "gamepad_rumble"
path = "examples/input/gamepad_rumble.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add gamepad rumble support to bevy_input (#8398) # Objective Provide the ability to trigger controller rumbling (force-feedback) with a cross-platform API. ## Solution This adds the `GamepadRumbleRequest` event to `bevy_input` and adds a system in `bevy_gilrs` to read them and rumble controllers accordingly. It's a relatively primitive API with a `duration` in seconds and `GamepadRumbleIntensity` with values for the weak and strong gamepad motors. It's is an almost 1-to-1 mapping to platform APIs. Some platforms refer to these motors as left and right, and low frequency and high frequency, but by convention, they're usually the same. I used #3868 as a starting point, updated to main, removed the low-level gilrs effect API, and moved the requests to `bevy_input` and exposed the strong and weak intensities. I intend this to hopefully be a non-controversial cross-platform starting point we can build upon to eventually support more fine-grained control (closer to the gilrs effect API) --- ## Changelog ### Added - Gamepads can now be rumbled by sending the `GamepadRumbleRequest` event. --------- Co-authored-by: Nicola Papale <nico@nicopap.ch> Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Nicola Papale <nicopap@users.noreply.github.com> Co-authored-by: Bruce Reif (Buswolley) <bruce.reif@dynata.com>
2023-04-24 15:28:53 +00:00
[package.metadata.example.gamepad_rumble]
name = "Gamepad Rumble"
description = "Shows how to rumble a gamepad using force feedback"
category = "Input"
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
wasm = false
break up input examples
2020-06-05 06:49:36 +00:00
[[example]]
name = "keyboard_input"
path = "examples/input/keyboard_input.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
break up input examples
2020-06-05 06:49:36 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.keyboard_input]
name = "Keyboard Input"
description = "Demonstrates handling a key press/release"
category = "Input"
wasm = false
Add keyboard modifier example (#1656) (#1657) This PR adds a small example that shows how to use Keyboard modifiers, as shown in [this](https://github.com/bevyengine/bevy/issues/1654#issuecomment-798966921) snippet. Fixes #1656. Co-authored-by: guimcaballero <guim.caballero@gmail.com>
2021-03-14 21:00:36 +00:00
[[example]]
name = "keyboard_modifiers"
path = "examples/input/keyboard_modifiers.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add keyboard modifier example (#1656) (#1657) This PR adds a small example that shows how to use Keyboard modifiers, as shown in [this](https://github.com/bevyengine/bevy/issues/1654#issuecomment-798966921) snippet. Fixes #1656. Co-authored-by: guimcaballero <guim.caballero@gmail.com>
2021-03-14 21:00:36 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.keyboard_modifiers]
name = "Keyboard Modifiers"
description = "Demonstrates using key modifiers (ctrl, shift)"
category = "Input"
wasm = false
break up input examples
2020-06-05 06:49:36 +00:00
[[example]]
name = "keyboard_input_events"
path = "examples/input/keyboard_input_events.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
organize examples and add ecs guide
2020-05-01 20:12:47 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.keyboard_input_events]
name = "Keyboard Input Events"
description = "Prints out all keyboard events"
category = "Input"
wasm = false
Add received character (#805) * Add ReceivedCharacter window event * Add ReceivedCharacter window event examples
2020-11-07 01:15:56 +00:00
[[example]]
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
name = "mouse_input"
path = "examples/input/mouse_input.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Added gamepad support using Gilrs (#280) Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2020-09-18 21:43:47 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.mouse_input]
name = "Mouse Input"
description = "Demonstrates handling a mouse button press/release"
category = "Input"
wasm = false
Separate gamepad state code from gamepad event code and other customizations (#700) Separated gamepad event and gamepad state code and made gamepad input more customizable
2020-10-21 17:27:00 +00:00
[[example]]
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
name = "mouse_input_events"
path = "examples/input/mouse_input_events.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Separate gamepad state code from gamepad event code and other customizations (#700) Separated gamepad event and gamepad state code and made gamepad input more customizable
2020-10-21 17:27:00 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.mouse_input_events]
name = "Mouse Input Events"
description = "Prints out all mouse events (buttons, movement, etc.)"
category = "Input"
wasm = false
Add mouse grab example (#4114) Fixes #4094
2022-03-08 17:14:08 +00:00
[[example]]
name = "mouse_grab"
path = "examples/input/mouse_grab.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add mouse grab example (#4114) Fixes #4094
2022-03-08 17:14:08 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.mouse_grab]
name = "Mouse Grab"
description = "Demonstrates how to grab the mouse, locking the cursor to the app's screen"
category = "Input"
wasm = false
Touch support implementation (#696) Adds a basic touch input system
2020-10-18 19:24:01 +00:00
[[example]]
name = "touch_input"
path = "examples/input/touch_input.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Touch support implementation (#696) Adds a basic touch input system
2020-10-18 19:24:01 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.touch_input]
name = "Touch Input"
description = "Displays touch presses, releases, and cancels"
category = "Input"
wasm = false
Touch support implementation (#696) Adds a basic touch input system
2020-10-18 19:24:01 +00:00
[[example]]
small input example improvements (#701)
2020-10-18 20:20:42 +00:00
name = "touch_input_events"
path = "examples/input/touch_input_events.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Touch support implementation (#696) Adds a basic touch input system
2020-10-18 19:24:01 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.touch_input_events]
name = "Touch Input Events"
description = "Prints out all touch inputs"
category = "Input"
wasm = false
add Input Method Editor support (#7325) # Objective - Fix #7315 - Add IME support ## Solution - Add two new fields to `Window`, to control if IME is enabled and the candidate box position This allows the use of dead keys which are needed in French, or the full IME experience to type using Pinyin I also added a basic general text input example that can handle IME input. https://user-images.githubusercontent.com/8672791/213941353-5ed73a73-5dd1-4e66-a7d6-a69b49694c52.mp4
2023-01-29 20:27:29 +00:00
[[example]]
name = "text_input"
path = "examples/input/text_input.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
add Input Method Editor support (#7325) # Objective - Fix #7315 - Add IME support ## Solution - Add two new fields to `Window`, to control if IME is enabled and the candidate box position This allows the use of dead keys which are needed in French, or the full IME experience to type using Pinyin I also added a basic general text input example that can handle IME input. https://user-images.githubusercontent.com/8672791/213941353-5ed73a73-5dd1-4e66-a7d6-a69b49694c52.mp4
2023-01-29 20:27:29 +00:00
[package.metadata.example.text_input]
name = "Text Input"
description = "Simple text input with IME support"
category = "Input"
wasm = false
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
# Reflection
organize examples and add ecs guide
2020-05-01 20:12:47 +00:00
[[example]]
Bevy Reflection (#926) Bevy Reflection
2020-11-28 00:39:59 +00:00
name = "reflection"
path = "examples/reflection/reflection.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Bevy Reflection (#926) Bevy Reflection
2020-11-28 00:39:59 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.reflection]
name = "Reflection"
description = "Demonstrates how reflection in Bevy provides a way to dynamically interact with Rust types"
category = "Reflection"
wasm = false
bevy_reflect: Custom attributes (#11659) # Objective As work on the editor starts to ramp up, it might be nice to start allowing types to specify custom attributes. These can be used to provide certain functionality to fields, such as ranges or controlling how data is displayed. A good example of this can be seen in [`bevy-inspector-egui`](https://github.com/jakobhellermann/bevy-inspector-egui) with its [`InspectorOptions`](https://docs.rs/bevy-inspector-egui/0.22.1/bevy_inspector_egui/struct.InspectorOptions.html): ```rust #[derive(Reflect, Default, InspectorOptions)] #[reflect(InspectorOptions)] struct Slider { #[inspector(min = 0.0, max = 1.0)] value: f32, } ``` Normally, as demonstrated in the example above, these attributes are handled by a derive macro and stored in a corresponding `TypeData` struct (i.e. `ReflectInspectorOptions`). Ideally, we would have a good way of defining this directly via reflection so that users don't need to create and manage a whole proc macro just to allow these sorts of attributes. And note that this doesn't have to just be for inspectors and editors. It can be used for things done purely on the code side of things. ## Solution Create a new method for storing attributes on fields via the `Reflect` derive. These custom attributes are stored in type info (e.g. `NamedField`, `StructInfo`, etc.). ```rust #[derive(Reflect)] struct Slider { #[reflect(@0.0..=1.0)] value: f64, } let TypeInfo::Struct(info) = Slider::type_info() else { panic!("expected struct info"); }; let field = info.field("value").unwrap(); let range = field.get_attribute::<RangeInclusive<f64>>().unwrap(); assert_eq!(*range, 0.0..=1.0); ``` ## TODO - [x] ~~Bikeshed syntax~~ Went with a type-based approach, prefixed by `@` for ease of parsing and flexibility - [x] Add support for custom struct/tuple struct field attributes - [x] Add support for custom enum variant field attributes - [x] ~~Add support for custom enum variant attributes (maybe?)~~ ~~Will require a larger refactor. Can be saved for a future PR if we really want it.~~ Actually, we apparently still have support for variant attributes despite not using them, so it was pretty easy to add lol. - [x] Add support for custom container attributes - [x] Allow custom attributes to store any reflectable value (not just `Lit`) - [x] ~~Store attributes in registry~~ This PR used to store these in attributes in the registry, however, it has since switched over to storing them in type info - [x] Add example ## Bikeshedding > [!note] > This section was made for the old method of handling custom attributes, which stored them by name (i.e. `some_attribute = 123`). The PR has shifted away from that, to a more type-safe approach. > > This section has been left for reference. There are a number of ways we can syntactically handle custom attributes. Feel free to leave a comment on your preferred one! Ideally we want one that is clear, readable, and concise since these will potentially see _a lot_ of use. Below is a small, non-exhaustive list of them. Note that the `skip_serializing` reflection attribute is added to demonstrate how each case plays with existing reflection attributes. <details> <summary>List</summary> ##### 1. `@(name = value)` > The `@` was chosen to make them stand out from other attributes and because the "at" symbol is a subtle pneumonic for "attribute". Of course, other symbols could be used (e.g. `$`, `#`, etc.). ```rust #[derive(Reflect)] struct Slider { #[reflect(@(min = 0.0, max = 1.0), skip_serializing)] #[[reflect(@(bevy_editor::hint = "Range: 0.0 to 1.0"))] value: f32, } ``` ##### 2. `@name = value` > This is my personal favorite. ```rust #[derive(Reflect)] struct Slider { #[reflect(@min = 0.0, @max = 1.0, skip_serializing)] #[[reflect(@bevy_editor::hint = "Range: 0.0 to 1.0")] value: f32, } ``` ##### 3. `custom_attr(name = value)` > `custom_attr` can be anything. Other possibilities include `with` or `tag`. ```rust #[derive(Reflect)] struct Slider { #[reflect(custom_attr(min = 0.0, max = 1.0), skip_serializing)] #[[reflect(custom_attr(bevy_editor::hint = "Range: 0.0 to 1.0"))] value: f32, } ``` ##### 4. `reflect_attr(name = value)` ```rust #[derive(Reflect)] struct Slider { #[reflect(skip_serializing)] #[reflect_attr(min = 0.0, max = 1.0)] #[[reflect_attr(bevy_editor::hint = "Range: 0.0 to 1.0")] value: f32, } ``` </details> --- ## Changelog - Added support for custom attributes on reflected types (i.e. `#[reflect(@Foo::new("bar")]`)
2024-05-20 19:30:21 +00:00
[[example]]
name = "custom_attributes"
path = "examples/reflection/custom_attributes.rs"
doc-scrape-examples = true
[package.metadata.example.custom_attributes]
name = "Custom Attributes"
description = "Registering and accessing custom attributes on reflected types"
category = "Reflection"
wasm = false
examples: Add `Dynamic Types` reflection example (#13220) # Objective Dynamic types can be tricky to understand and work with in bevy_reflect. There should be an example that shows what they are and how they're used. ## Solution Add a `Dynamic Types` reflection example. I'm planning to go through the reflection examples, adding new ones and updating old ones. And I think this walkthrough style tends to work best. Due to the amount of text and associated explanation, it might fit better in a dedicated reflection chapter of the WIP Bevy Book. However, I think it might be valuable to have some public-facing tutorials for these concepts. Let me know if there any thoughts or critiques with the example— both in content and this overall structure! ## Testing To test these changes, you can run the example locally: ``` cargo run --example dynamic_types ``` --- ## Changelog - Add `Dynamic Types` reflection example
2024-05-03 23:34:53 +00:00
[[example]]
name = "dynamic_types"
path = "examples/reflection/dynamic_types.rs"
doc-scrape-examples = true
[package.metadata.example.dynamic_types]
name = "Dynamic Types"
description = "How dynamic types are used with reflection"
category = "Reflection"
wasm = false
bevy_reflect: Function reflection (#13152) # Objective We're able to reflect types sooooooo... why not functions? The goal of this PR is to make functions callable within a dynamic context, where type information is not readily available at compile time. For example, if we have a function: ```rust fn add(left: i32, right: i32) -> i32 { left + right } ``` And two `Reflect` values we've already validated are `i32` types: ```rust let left: Box<dyn Reflect> = Box::new(2_i32); let right: Box<dyn Reflect> = Box::new(2_i32); ``` We should be able to call `add` with these values: ```rust // ????? let result: Box<dyn Reflect> = add.call_dynamic(left, right); ``` And ideally this wouldn't just work for functions, but methods and closures too! Right now, users have two options: 1. Manually parse the reflected data and call the function themselves 2. Rely on registered type data to handle the conversions for them For a small function like `add`, this isn't too bad. But what about for more complex functions? What about for many functions? At worst, this process is error-prone. At best, it's simply tedious. And this is assuming we know the function at compile time. What if we want to accept a function dynamically and call it with our own arguments? It would be much nicer if `bevy_reflect` could alleviate some of the problems here. ## Solution Added function reflection! This adds a `DynamicFunction` type to wrap a function dynamically. This can be called with an `ArgList`, which is a dynamic list of `Reflect`-containing `Arg` arguments. It returns a `FunctionResult` which indicates whether or not the function call succeeded, returning a `Reflect`-containing `Return` type if it did succeed. Many functions can be converted into this `DynamicFunction` type thanks to the `IntoFunction` trait. Taking our previous `add` example, this might look something like (explicit types added for readability): ```rust fn add(left: i32, right: i32) -> i32 { left + right } let mut function: DynamicFunction = add.into_function(); let args: ArgList = ArgList::new().push_owned(2_i32).push_owned(2_i32); let result: Return = function.call(args).unwrap(); let value: Box<dyn Reflect> = result.unwrap_owned(); assert_eq!(value.take::<i32>().unwrap(), 4); ``` And it also works on closures: ```rust let add = |left: i32, right: i32| left + right; let mut function: DynamicFunction = add.into_function(); let args: ArgList = ArgList::new().push_owned(2_i32).push_owned(2_i32); let result: Return = function.call(args).unwrap(); let value: Box<dyn Reflect> = result.unwrap_owned(); assert_eq!(value.take::<i32>().unwrap(), 4); ``` As well as methods: ```rust #[derive(Reflect)] struct Foo(i32); impl Foo { fn add(&mut self, value: i32) { self.0 += value; } } let mut foo = Foo(2); let mut function: DynamicFunction = Foo::add.into_function(); let args: ArgList = ArgList::new().push_mut(&mut foo).push_owned(2_i32); function.call(args).unwrap(); assert_eq!(foo.0, 4); ``` ### Limitations While this does cover many functions, it is far from a perfect system and has quite a few limitations. Here are a few of the limitations when using `IntoFunction`: 1. The lifetime of the return value is only tied to the lifetime of the first argument (useful for methods). This means you can't have a function like `(a: i32, b: &i32) -> &i32` without creating the `DynamicFunction` manually. 2. Only 15 arguments are currently supported. If the first argument is a (mutable) reference, this number increases to 16. 3. Manual implementations of `Reflect` will need to implement the new `FromArg`, `GetOwnership`, and `IntoReturn` traits in order to be used as arguments/return types. And some limitations of `DynamicFunction` itself: 1. All arguments share the same lifetime, or rather, they will shrink to the shortest lifetime. 2. Closures that capture their environment may need to have their `DynamicFunction` dropped before accessing those variables again (there is a `DynamicFunction::call_once` to make this a bit easier) 3. All arguments and return types must implement `Reflect`. While not a big surprise coming from `bevy_reflect`, this implementation could actually still work by swapping `Reflect` out with `Any`. Of course, that makes working with the arguments and return values a bit harder. 4. Generic functions are not supported (unless they have been manually monomorphized) And general, reflection gotchas: 1. `&str` does not implement `Reflect`. Rather, `&'static str` implements `Reflect` (the same is true for `&Path` and similar types). This means that `&'static str` is considered an "owned" value for the sake of generating arguments. Additionally, arguments and return types containing `&str` will assume it's `&'static str`, which is almost never the desired behavior. In these cases, the only solution (I believe) is to use `&String` instead. ### Followup Work This PR is the first of two PRs I intend to work on. The second PR will aim to integrate this new function reflection system into the existing reflection traits and `TypeInfo`. The goal would be to register and call a reflected type's methods dynamically. I chose not to do that in this PR since the diff is already quite large. I also want the discussion for both PRs to be focused on their own implementation. Another followup I'd like to do is investigate allowing common container types as a return type, such as `Option<&[mut] T>` and `Result<&[mut] T, E>`. This would allow even more functions to opt into this system. I chose to not include it in this one, though, for the same reasoning as previously mentioned. ### Alternatives One alternative I had considered was adding a macro to convert any function into a reflection-based counterpart. The idea would be that a struct that wraps the function would be created and users could specify which arguments and return values should be `Reflect`. It could then be called via a new `Function` trait. I think that could still work, but it will be a fair bit more involved, requiring some slightly more complex parsing. And it of course is a bit more work for the user, since they need to create the type via macro invocation. It also makes registering these functions onto a type a bit more complicated (depending on how it's implemented). For now, I think this is a fairly simple, yet powerful solution that provides the least amount of friction for users. --- ## Showcase Bevy now adds support for storing and calling functions dynamically using reflection! ```rust // 1. Take a standard Rust function fn add(left: i32, right: i32) -> i32 { left + right } // 2. Convert it into a type-erased `DynamicFunction` using the `IntoFunction` trait let mut function: DynamicFunction = add.into_function(); // 3. Define your arguments from reflected values let args: ArgList = ArgList::new().push_owned(2_i32).push_owned(2_i32); // 4. Call the function with your arguments let result: Return = function.call(args).unwrap(); // 5. Extract the return value let value: Box<dyn Reflect> = result.unwrap_owned(); assert_eq!(value.take::<i32>().unwrap(), 4); ``` ## Changelog #### TL;DR - Added support for function reflection - Added a new `Function Reflection` example: https://github.com/bevyengine/bevy/blob/ba727898f2adff817838fc4cdb49871bbce37356/examples/reflection/function_reflection.rs#L1-L157 #### Details Added the following items: - `ArgError` enum - `ArgId` enum - `ArgInfo` struct - `ArgList` struct - `Arg` enum - `DynamicFunction` struct - `FromArg` trait (derived with `derive(Reflect)`) - `FunctionError` enum - `FunctionInfo` struct - `FunctionResult` alias - `GetOwnership` trait (derived with `derive(Reflect)`) - `IntoFunction` trait (with blanket implementation) - `IntoReturn` trait (derived with `derive(Reflect)`) - `Ownership` enum - `ReturnInfo` struct - `Return` enum --------- Co-authored-by: Periwink <charlesbour@gmail.com>
2024-07-01 13:49:08 +00:00
[[example]]
name = "function_reflection"
path = "examples/reflection/function_reflection.rs"
doc-scrape-examples = true
bevy_reflect: Feature-gate function reflection (#14174) # Objective Function reflection requires a lot of macro code generation in the form of several `all_tuples!` invocations, as well as impls generated in the `Reflect` derive macro. Seeing as function reflection is currently a bit more niche, it makes sense to gate it all behind a feature. ## Solution Add a `functions` feature to `bevy_reflect`, which can be enabled in Bevy using the `reflect_functions` feature. ## Testing You can test locally by running: ``` cargo test --package bevy_reflect ``` That should ensure that everything still works with the feature disabled. To test with the feature on, you can run: ``` cargo test --package bevy_reflect --features functions ``` --- ## Changelog - Moved function reflection behind a Cargo feature (`bevy/reflect_functions` and `bevy_reflect/functions`) - Add `IntoFunction` export in `bevy_reflect::prelude` ## Internal Migration Guide > [!important] > Function reflection was introduced as part of the 0.15 dev cycle. This migration guide was written for developers relying on `main` during this cycle, and is not a breaking change coming from 0.14. Function reflection is now gated behind a feature. To use function reflection, enable the feature: - If using `bevy_reflect` directly, enable the `functions` feature - If using `bevy`, enable the `reflect_functions` feature
2024-07-14 15:55:31 +00:00
required-features = ["reflect_functions"]
bevy_reflect: Function reflection (#13152) # Objective We're able to reflect types sooooooo... why not functions? The goal of this PR is to make functions callable within a dynamic context, where type information is not readily available at compile time. For example, if we have a function: ```rust fn add(left: i32, right: i32) -> i32 { left + right } ``` And two `Reflect` values we've already validated are `i32` types: ```rust let left: Box<dyn Reflect> = Box::new(2_i32); let right: Box<dyn Reflect> = Box::new(2_i32); ``` We should be able to call `add` with these values: ```rust // ????? let result: Box<dyn Reflect> = add.call_dynamic(left, right); ``` And ideally this wouldn't just work for functions, but methods and closures too! Right now, users have two options: 1. Manually parse the reflected data and call the function themselves 2. Rely on registered type data to handle the conversions for them For a small function like `add`, this isn't too bad. But what about for more complex functions? What about for many functions? At worst, this process is error-prone. At best, it's simply tedious. And this is assuming we know the function at compile time. What if we want to accept a function dynamically and call it with our own arguments? It would be much nicer if `bevy_reflect` could alleviate some of the problems here. ## Solution Added function reflection! This adds a `DynamicFunction` type to wrap a function dynamically. This can be called with an `ArgList`, which is a dynamic list of `Reflect`-containing `Arg` arguments. It returns a `FunctionResult` which indicates whether or not the function call succeeded, returning a `Reflect`-containing `Return` type if it did succeed. Many functions can be converted into this `DynamicFunction` type thanks to the `IntoFunction` trait. Taking our previous `add` example, this might look something like (explicit types added for readability): ```rust fn add(left: i32, right: i32) -> i32 { left + right } let mut function: DynamicFunction = add.into_function(); let args: ArgList = ArgList::new().push_owned(2_i32).push_owned(2_i32); let result: Return = function.call(args).unwrap(); let value: Box<dyn Reflect> = result.unwrap_owned(); assert_eq!(value.take::<i32>().unwrap(), 4); ``` And it also works on closures: ```rust let add = |left: i32, right: i32| left + right; let mut function: DynamicFunction = add.into_function(); let args: ArgList = ArgList::new().push_owned(2_i32).push_owned(2_i32); let result: Return = function.call(args).unwrap(); let value: Box<dyn Reflect> = result.unwrap_owned(); assert_eq!(value.take::<i32>().unwrap(), 4); ``` As well as methods: ```rust #[derive(Reflect)] struct Foo(i32); impl Foo { fn add(&mut self, value: i32) { self.0 += value; } } let mut foo = Foo(2); let mut function: DynamicFunction = Foo::add.into_function(); let args: ArgList = ArgList::new().push_mut(&mut foo).push_owned(2_i32); function.call(args).unwrap(); assert_eq!(foo.0, 4); ``` ### Limitations While this does cover many functions, it is far from a perfect system and has quite a few limitations. Here are a few of the limitations when using `IntoFunction`: 1. The lifetime of the return value is only tied to the lifetime of the first argument (useful for methods). This means you can't have a function like `(a: i32, b: &i32) -> &i32` without creating the `DynamicFunction` manually. 2. Only 15 arguments are currently supported. If the first argument is a (mutable) reference, this number increases to 16. 3. Manual implementations of `Reflect` will need to implement the new `FromArg`, `GetOwnership`, and `IntoReturn` traits in order to be used as arguments/return types. And some limitations of `DynamicFunction` itself: 1. All arguments share the same lifetime, or rather, they will shrink to the shortest lifetime. 2. Closures that capture their environment may need to have their `DynamicFunction` dropped before accessing those variables again (there is a `DynamicFunction::call_once` to make this a bit easier) 3. All arguments and return types must implement `Reflect`. While not a big surprise coming from `bevy_reflect`, this implementation could actually still work by swapping `Reflect` out with `Any`. Of course, that makes working with the arguments and return values a bit harder. 4. Generic functions are not supported (unless they have been manually monomorphized) And general, reflection gotchas: 1. `&str` does not implement `Reflect`. Rather, `&'static str` implements `Reflect` (the same is true for `&Path` and similar types). This means that `&'static str` is considered an "owned" value for the sake of generating arguments. Additionally, arguments and return types containing `&str` will assume it's `&'static str`, which is almost never the desired behavior. In these cases, the only solution (I believe) is to use `&String` instead. ### Followup Work This PR is the first of two PRs I intend to work on. The second PR will aim to integrate this new function reflection system into the existing reflection traits and `TypeInfo`. The goal would be to register and call a reflected type's methods dynamically. I chose not to do that in this PR since the diff is already quite large. I also want the discussion for both PRs to be focused on their own implementation. Another followup I'd like to do is investigate allowing common container types as a return type, such as `Option<&[mut] T>` and `Result<&[mut] T, E>`. This would allow even more functions to opt into this system. I chose to not include it in this one, though, for the same reasoning as previously mentioned. ### Alternatives One alternative I had considered was adding a macro to convert any function into a reflection-based counterpart. The idea would be that a struct that wraps the function would be created and users could specify which arguments and return values should be `Reflect`. It could then be called via a new `Function` trait. I think that could still work, but it will be a fair bit more involved, requiring some slightly more complex parsing. And it of course is a bit more work for the user, since they need to create the type via macro invocation. It also makes registering these functions onto a type a bit more complicated (depending on how it's implemented). For now, I think this is a fairly simple, yet powerful solution that provides the least amount of friction for users. --- ## Showcase Bevy now adds support for storing and calling functions dynamically using reflection! ```rust // 1. Take a standard Rust function fn add(left: i32, right: i32) -> i32 { left + right } // 2. Convert it into a type-erased `DynamicFunction` using the `IntoFunction` trait let mut function: DynamicFunction = add.into_function(); // 3. Define your arguments from reflected values let args: ArgList = ArgList::new().push_owned(2_i32).push_owned(2_i32); // 4. Call the function with your arguments let result: Return = function.call(args).unwrap(); // 5. Extract the return value let value: Box<dyn Reflect> = result.unwrap_owned(); assert_eq!(value.take::<i32>().unwrap(), 4); ``` ## Changelog #### TL;DR - Added support for function reflection - Added a new `Function Reflection` example: https://github.com/bevyengine/bevy/blob/ba727898f2adff817838fc4cdb49871bbce37356/examples/reflection/function_reflection.rs#L1-L157 #### Details Added the following items: - `ArgError` enum - `ArgId` enum - `ArgInfo` struct - `ArgList` struct - `Arg` enum - `DynamicFunction` struct - `FromArg` trait (derived with `derive(Reflect)`) - `FunctionError` enum - `FunctionInfo` struct - `FunctionResult` alias - `GetOwnership` trait (derived with `derive(Reflect)`) - `IntoFunction` trait (with blanket implementation) - `IntoReturn` trait (derived with `derive(Reflect)`) - `Ownership` enum - `ReturnInfo` struct - `Return` enum --------- Co-authored-by: Periwink <charlesbour@gmail.com>
2024-07-01 13:49:08 +00:00
[package.metadata.example.function_reflection]
name = "Function Reflection"
description = "Demonstrates how functions can be called dynamically using reflection"
category = "Reflection"
wasm = false
Bevy Reflection (#926) Bevy Reflection
2020-11-28 00:39:59 +00:00
[[example]]
name = "generic_reflection"
path = "examples/reflection/generic_reflection.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Bevy Reflection (#926) Bevy Reflection
2020-11-28 00:39:59 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.generic_reflection]
name = "Generic Reflection"
description = "Registers concrete instances of generic types that may be used with reflection"
category = "Reflection"
wasm = false
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
[[example]]
name = "reflection_types"
path = "examples/reflection/reflection_types.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.reflection_types]
name = "Reflection Types"
description = "Illustrates the various reflection types available"
category = "Reflection"
wasm = false
Bevy Reflection (#926) Bevy Reflection
2020-11-28 00:39:59 +00:00
[[example]]
examples: Add `Type Data` reflection example (#13903) # Objective Type data is a **super** useful tool to know about when working with reflection. However, most users don't fully understand how it works or that you can use it for more than just object-safe traits. This is unfortunate because it can be surprisingly simple to manually create your own type data. We should have an example detailing how type works, how users can define their own, and how thy can be used. ## Solution Added a `type_data` example. This example goes through all the major points about type data: - Why we need them - How they can be defined - The two ways they can be registered - A list of common/important type data provided by Bevy I also thought it might be good to go over the `#[reflect_trait]` macro as part of this example since it has all the other context, including how to define type data in places where `#[reflect_trait]` won't work. Because of this, I removed the `trait_reflection` example. ## Testing You can run the example locally with the following command: ``` cargo run --example type_data ``` --- ## Changelog - Added the `type_data` example - Removed the `trait_reflection` example
2024-07-15 14:19:50 +00:00
name = "type_data"
path = "examples/reflection/type_data.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
organize examples and add ecs guide
2020-05-01 20:12:47 +00:00
examples: Add `Type Data` reflection example (#13903) # Objective Type data is a **super** useful tool to know about when working with reflection. However, most users don't fully understand how it works or that you can use it for more than just object-safe traits. This is unfortunate because it can be surprisingly simple to manually create your own type data. We should have an example detailing how type works, how users can define their own, and how thy can be used. ## Solution Added a `type_data` example. This example goes through all the major points about type data: - Why we need them - How they can be defined - The two ways they can be registered - A list of common/important type data provided by Bevy I also thought it might be good to go over the `#[reflect_trait]` macro as part of this example since it has all the other context, including how to define type data in places where `#[reflect_trait]` won't work. Because of this, I removed the `trait_reflection` example. ## Testing You can run the example locally with the following command: ``` cargo run --example type_data ``` --- ## Changelog - Added the `type_data` example - Removed the `trait_reflection` example
2024-07-15 14:19:50 +00:00
[package.metadata.example.type_data]
name = "Type Data"
description = "Demonstrates how to create and use type data"
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
category = "Reflection"
wasm = false
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
# Scene
props: derive, get/set, example
2020-05-22 06:58:11 +00:00
[[example]]
Bevy Reflection (#926) Bevy Reflection
2020-11-28 00:39:59 +00:00
name = "scene"
path = "examples/scene/scene.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
props: derive, get/set, example
2020-05-22 06:58:11 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.scene]
name = "Scene"
description = "Demonstrates loading from and saving scenes to files"
category = "Scene"
wasm = false
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
# Shaders
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
[[package.metadata.example_category]]
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
name = "Shaders"
description = """
These examples demonstrate how to implement different shaders in user code.
A shader in its most common usage is a small program that is run by the GPU per-vertex in a mesh (a vertex shader) or per-affected-screen-fragment (a fragment shader.) The GPU executes these programs in a highly parallel way.
There are also compute shaders which are used for more general processing leveraging the GPU's parallelism.
"""
Mesh vertex buffer layouts (#3959) This PR makes a number of changes to how meshes and vertex attributes are handled, which the goal of enabling easy and flexible custom vertex attributes: * Reworks the `Mesh` type to use the newly added `VertexAttribute` internally * `VertexAttribute` defines the name, a unique `VertexAttributeId`, and a `VertexFormat` * `VertexAttributeId` is used to produce consistent sort orders for vertex buffer generation, replacing the more expensive and often surprising "name based sorting" * Meshes can be used to generate a `MeshVertexBufferLayout`, which defines the layout of the gpu buffer produced by the mesh. `MeshVertexBufferLayouts` can then be used to generate actual `VertexBufferLayouts` according to the requirements of a specific pipeline. This decoupling of "mesh layout" vs "pipeline vertex buffer layout" is what enables custom attributes. We don't need to standardize _mesh layouts_ or contort meshes to meet the needs of a specific pipeline. As long as the mesh has what the pipeline needs, it will work transparently. * Mesh-based pipelines now specialize on `&MeshVertexBufferLayout` via the new `SpecializedMeshPipeline` trait (which behaves like `SpecializedPipeline`, but adds `&MeshVertexBufferLayout`). The integrity of the pipeline cache is maintained because the `MeshVertexBufferLayout` is treated as part of the key (which is fully abstracted from implementers of the trait ... no need to add any additional info to the specialization key). * Hashing `MeshVertexBufferLayout` is too expensive to do for every entity, every frame. To make this scalable, I added a generalized "pre-hashing" solution to `bevy_utils`: `Hashed<T>` keys and `PreHashMap<K, V>` (which uses `Hashed<T>` internally) . Why didn't I just do the quick and dirty in-place "pre-compute hash and use that u64 as a key in a hashmap" that we've done in the past? Because its wrong! Hashes by themselves aren't enough because two different values can produce the same hash. Re-hashing a hash is even worse! I decided to build a generalized solution because this pattern has come up in the past and we've chosen to do the wrong thing. Now we can do the right thing! This did unfortunately require pulling in `hashbrown` and using that in `bevy_utils`, because avoiding re-hashes requires the `raw_entry_mut` api, which isn't stabilized yet (and may never be ... `entry_ref` has favor now, but also isn't available yet). If std's HashMap ever provides the tools we need, we can move back to that. Note that adding `hashbrown` doesn't increase our dependency count because it was already in our tree. I will probably break these changes out into their own PR. * Specializing on `MeshVertexBufferLayout` has one non-obvious behavior: it can produce identical pipelines for two different MeshVertexBufferLayouts. To optimize the number of active pipelines / reduce re-binds while drawing, I de-duplicate pipelines post-specialization using the final `VertexBufferLayout` as the key. For example, consider a pipeline that needs the layout `(position, normal)` and is specialized using two meshes: `(position, normal, uv)` and `(position, normal, other_vec2)`. If both of these meshes result in `(position, normal)` specializations, we can use the same pipeline! Now we do. Cool! To briefly illustrate, this is what the relevant section of `MeshPipeline`'s specialization code looks like now: ```rust impl SpecializedMeshPipeline for MeshPipeline { type Key = MeshPipelineKey; fn specialize( &self, key: Self::Key, layout: &MeshVertexBufferLayout, ) -> RenderPipelineDescriptor { let mut vertex_attributes = vec![ Mesh::ATTRIBUTE_POSITION.at_shader_location(0), Mesh::ATTRIBUTE_NORMAL.at_shader_location(1), Mesh::ATTRIBUTE_UV_0.at_shader_location(2), ]; let mut shader_defs = Vec::new(); if layout.contains(Mesh::ATTRIBUTE_TANGENT) { shader_defs.push(String::from("VERTEX_TANGENTS")); vertex_attributes.push(Mesh::ATTRIBUTE_TANGENT.at_shader_location(3)); } let vertex_buffer_layout = layout .get_layout(&vertex_attributes) .expect("Mesh is missing a vertex attribute"); ``` Notice that this is _much_ simpler than it was before. And now any mesh with any layout can be used with this pipeline, provided it has vertex postions, normals, and uvs. We even got to remove `HAS_TANGENTS` from MeshPipelineKey and `has_tangents` from `GpuMesh`, because that information is redundant with `MeshVertexBufferLayout`. This is still a draft because I still need to: * Add more docs * Experiment with adding error handling to mesh pipeline specialization (which would print errors at runtime when a mesh is missing a vertex attribute required by a pipeline). If it doesn't tank perf, we'll keep it. * Consider breaking out the PreHash / hashbrown changes into a separate PR. * Add an example illustrating this change * Verify that the "mesh-specialized pipeline de-duplication code" works properly Please dont yell at me for not doing these things yet :) Just trying to get this in peoples' hands asap. Alternative to #3120 Fixes #3030 Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-02-23 23:21:13 +00:00
[[example]]
name = "custom_vertex_attribute"
path = "examples/shader/custom_vertex_attribute.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Mesh vertex buffer layouts (#3959) This PR makes a number of changes to how meshes and vertex attributes are handled, which the goal of enabling easy and flexible custom vertex attributes: * Reworks the `Mesh` type to use the newly added `VertexAttribute` internally * `VertexAttribute` defines the name, a unique `VertexAttributeId`, and a `VertexFormat` * `VertexAttributeId` is used to produce consistent sort orders for vertex buffer generation, replacing the more expensive and often surprising "name based sorting" * Meshes can be used to generate a `MeshVertexBufferLayout`, which defines the layout of the gpu buffer produced by the mesh. `MeshVertexBufferLayouts` can then be used to generate actual `VertexBufferLayouts` according to the requirements of a specific pipeline. This decoupling of "mesh layout" vs "pipeline vertex buffer layout" is what enables custom attributes. We don't need to standardize _mesh layouts_ or contort meshes to meet the needs of a specific pipeline. As long as the mesh has what the pipeline needs, it will work transparently. * Mesh-based pipelines now specialize on `&MeshVertexBufferLayout` via the new `SpecializedMeshPipeline` trait (which behaves like `SpecializedPipeline`, but adds `&MeshVertexBufferLayout`). The integrity of the pipeline cache is maintained because the `MeshVertexBufferLayout` is treated as part of the key (which is fully abstracted from implementers of the trait ... no need to add any additional info to the specialization key). * Hashing `MeshVertexBufferLayout` is too expensive to do for every entity, every frame. To make this scalable, I added a generalized "pre-hashing" solution to `bevy_utils`: `Hashed<T>` keys and `PreHashMap<K, V>` (which uses `Hashed<T>` internally) . Why didn't I just do the quick and dirty in-place "pre-compute hash and use that u64 as a key in a hashmap" that we've done in the past? Because its wrong! Hashes by themselves aren't enough because two different values can produce the same hash. Re-hashing a hash is even worse! I decided to build a generalized solution because this pattern has come up in the past and we've chosen to do the wrong thing. Now we can do the right thing! This did unfortunately require pulling in `hashbrown` and using that in `bevy_utils`, because avoiding re-hashes requires the `raw_entry_mut` api, which isn't stabilized yet (and may never be ... `entry_ref` has favor now, but also isn't available yet). If std's HashMap ever provides the tools we need, we can move back to that. Note that adding `hashbrown` doesn't increase our dependency count because it was already in our tree. I will probably break these changes out into their own PR. * Specializing on `MeshVertexBufferLayout` has one non-obvious behavior: it can produce identical pipelines for two different MeshVertexBufferLayouts. To optimize the number of active pipelines / reduce re-binds while drawing, I de-duplicate pipelines post-specialization using the final `VertexBufferLayout` as the key. For example, consider a pipeline that needs the layout `(position, normal)` and is specialized using two meshes: `(position, normal, uv)` and `(position, normal, other_vec2)`. If both of these meshes result in `(position, normal)` specializations, we can use the same pipeline! Now we do. Cool! To briefly illustrate, this is what the relevant section of `MeshPipeline`'s specialization code looks like now: ```rust impl SpecializedMeshPipeline for MeshPipeline { type Key = MeshPipelineKey; fn specialize( &self, key: Self::Key, layout: &MeshVertexBufferLayout, ) -> RenderPipelineDescriptor { let mut vertex_attributes = vec![ Mesh::ATTRIBUTE_POSITION.at_shader_location(0), Mesh::ATTRIBUTE_NORMAL.at_shader_location(1), Mesh::ATTRIBUTE_UV_0.at_shader_location(2), ]; let mut shader_defs = Vec::new(); if layout.contains(Mesh::ATTRIBUTE_TANGENT) { shader_defs.push(String::from("VERTEX_TANGENTS")); vertex_attributes.push(Mesh::ATTRIBUTE_TANGENT.at_shader_location(3)); } let vertex_buffer_layout = layout .get_layout(&vertex_attributes) .expect("Mesh is missing a vertex attribute"); ``` Notice that this is _much_ simpler than it was before. And now any mesh with any layout can be used with this pipeline, provided it has vertex postions, normals, and uvs. We even got to remove `HAS_TANGENTS` from MeshPipelineKey and `has_tangents` from `GpuMesh`, because that information is redundant with `MeshVertexBufferLayout`. This is still a draft because I still need to: * Add more docs * Experiment with adding error handling to mesh pipeline specialization (which would print errors at runtime when a mesh is missing a vertex attribute required by a pipeline). If it doesn't tank perf, we'll keep it. * Consider breaking out the PreHash / hashbrown changes into a separate PR. * Add an example illustrating this change * Verify that the "mesh-specialized pipeline de-duplication code" works properly Please dont yell at me for not doing these things yet :) Just trying to get this in peoples' hands asap. Alternative to #3120 Fixes #3030 Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-02-23 23:21:13 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.custom_vertex_attribute]
name = "Custom Vertex Attribute"
description = "A shader that reads a mesh's custom vertex attribute"
category = "Shaders"
wasm = true
add a post-processing example (#4797) # Objective - Add an example showing a custom post processing effect, done after the first rendering pass. ## Solution - A simple post processing "chromatic aberration" effect. I mixed together examples `3d/render_to_texture`, and `shader/shader_material_screenspace_texture` - Reading a bit how https://github.com/bevyengine/bevy/pull/3430 was done gave me pointers to apply the main pass to the 2d render rather than using a 3d quad. This work might be or not be relevant to https://github.com/bevyengine/bevy/issues/2724 <details> <summary> ⚠️ Click for a video of the render ⚠️ I’ve been told it might hurt the eyes 👀 , maybe we should choose another effect just in case ?</summary> https://user-images.githubusercontent.com/2290685/169138830-a6dc8a9f-8798-44b9-8d9e-449e60614916.mp4 </details> # Request for feedbacks - [ ] Is chromatic aberration effect ok ? (Correct term, not a danger for the eyes ?) I'm open to suggestion to make something different. - [ ] Is the code idiomatic ? I preferred a "main camera -> **new camera with post processing applied to a quad**" approach to emulate minimum modification to existing code wanting to add global post processing. --- ## Changelog - Add a full screen post processing shader example
2022-06-06 00:06:49 +00:00
[[example]]
Start a built-in postprocessing stack, and implement chromatic aberration in it. (#13695) This commit creates a new built-in postprocessing shader that's designed to hold miscellaneous postprocessing effects, and starts it off with chromatic aberration. Possible future effects include vignette, film grain, and lens distortion. [Chromatic aberration] is a common postprocessing effect that simulates lenses that fail to focus all colors of light to a single point. It's often used for impact effects and/or horror games. This patch uses the technique from *Inside* ([Gjøl & Svendsen 2016]), which allows the developer to customize the particular color pattern to achieve different effects. Unity HDRP uses the same technique, while Unreal has a hard-wired fixed color pattern. A new example, `post_processing`, has been added, in order to demonstrate the technique. The existing `post_processing` shader has been renamed to `custom_post_processing`, for clarity. [Chromatic aberration]: https://en.wikipedia.org/wiki/Chromatic_aberration [Gjøl & Svendsen 2016]: https://github.com/playdeadgames/publications/blob/master/INSIDE/rendering_inside_gdc2016.pdf ![Screenshot 2024-06-04 180304](https://github.com/bevyengine/bevy/assets/157897/3631c64f-a615-44fe-91ca-7f04df0a54b2) ![Screenshot 2024-06-04 180743](https://github.com/bevyengine/bevy/assets/157897/ee055cbf-4314-49c5-8bfa-8d8a17bd52bb) ## Changelog ### Added * Chromatic aberration is now available as a built-in postprocessing effect. To use it, add `ChromaticAberration` to your camera.
2024-07-15 13:59:02 +00:00
name = "custom_post_processing"
path = "examples/shader/custom_post_processing.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
add a post-processing example (#4797) # Objective - Add an example showing a custom post processing effect, done after the first rendering pass. ## Solution - A simple post processing "chromatic aberration" effect. I mixed together examples `3d/render_to_texture`, and `shader/shader_material_screenspace_texture` - Reading a bit how https://github.com/bevyengine/bevy/pull/3430 was done gave me pointers to apply the main pass to the 2d render rather than using a 3d quad. This work might be or not be relevant to https://github.com/bevyengine/bevy/issues/2724 <details> <summary> ⚠️ Click for a video of the render ⚠️ I’ve been told it might hurt the eyes 👀 , maybe we should choose another effect just in case ?</summary> https://user-images.githubusercontent.com/2290685/169138830-a6dc8a9f-8798-44b9-8d9e-449e60614916.mp4 </details> # Request for feedbacks - [ ] Is chromatic aberration effect ok ? (Correct term, not a danger for the eyes ?) I'm open to suggestion to make something different. - [ ] Is the code idiomatic ? I preferred a "main camera -> **new camera with post processing applied to a quad**" approach to emulate minimum modification to existing code wanting to add global post processing. --- ## Changelog - Add a full screen post processing shader example
2022-06-06 00:06:49 +00:00
Start a built-in postprocessing stack, and implement chromatic aberration in it. (#13695) This commit creates a new built-in postprocessing shader that's designed to hold miscellaneous postprocessing effects, and starts it off with chromatic aberration. Possible future effects include vignette, film grain, and lens distortion. [Chromatic aberration] is a common postprocessing effect that simulates lenses that fail to focus all colors of light to a single point. It's often used for impact effects and/or horror games. This patch uses the technique from *Inside* ([Gjøl & Svendsen 2016]), which allows the developer to customize the particular color pattern to achieve different effects. Unity HDRP uses the same technique, while Unreal has a hard-wired fixed color pattern. A new example, `post_processing`, has been added, in order to demonstrate the technique. The existing `post_processing` shader has been renamed to `custom_post_processing`, for clarity. [Chromatic aberration]: https://en.wikipedia.org/wiki/Chromatic_aberration [Gjøl & Svendsen 2016]: https://github.com/playdeadgames/publications/blob/master/INSIDE/rendering_inside_gdc2016.pdf ![Screenshot 2024-06-04 180304](https://github.com/bevyengine/bevy/assets/157897/3631c64f-a615-44fe-91ca-7f04df0a54b2) ![Screenshot 2024-06-04 180743](https://github.com/bevyengine/bevy/assets/157897/ee055cbf-4314-49c5-8bfa-8d8a17bd52bb) ## Changelog ### Added * Chromatic aberration is now available as a built-in postprocessing effect. To use it, add `ChromaticAberration` to your camera.
2024-07-15 13:59:02 +00:00
[package.metadata.example.custom_post_processing]
Add low level post process example using a custom render pass (#6909) Co-authored-by: JMS55 <47158642+JMS55@users.noreply.github.com> Co-authored-by: Robert Swain <robert.swain@gmail.com>
2023-03-16 03:22:17 +00:00
name = "Post Processing - Custom Render Pass"
description = "A custom post processing effect, using a custom render pass that runs after the main pass"
category = "Shaders"
wasm = true
organize examples and add ecs guide
2020-05-01 20:12:47 +00:00
[[example]]
name = "shader_defs"
path = "examples/shader/shader_defs.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
organize examples and add ecs guide
2020-05-01 20:12:47 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.shader_defs]
name = "Shader Defs"
description = "A shader that uses \"shaders defs\" (a bevy tool to selectively toggle parts of a shader)"
category = "Shaders"
wasm = true
Modular Rendering (#2831) This changes how render logic is composed to make it much more modular. Previously, all extraction logic was centralized for a given "type" of rendered thing. For example, we extracted meshes into a vector of ExtractedMesh, which contained the mesh and material asset handles, the transform, etc. We looked up bindings for "drawn things" using their index in the `Vec<ExtractedMesh>`. This worked fine for built in rendering, but made it hard to reuse logic for "custom" rendering. It also prevented us from reusing things like "extracted transforms" across contexts. To make rendering more modular, I made a number of changes: * Entities now drive rendering: * We extract "render components" from "app components" and store them _on_ entities. No more centralized uber lists! We now have true "ECS-driven rendering" * To make this perform well, I implemented #2673 in upstream Bevy for fast batch insertions into specific entities. This was merged into the `pipelined-rendering` branch here: #2815 * Reworked the `Draw` abstraction: * Generic `PhaseItems`: each draw phase can define its own type of "rendered thing", which can define its own "sort key" * Ported the 2d, 3d, and shadow phases to the new PhaseItem impl (currently Transparent2d, Transparent3d, and Shadow PhaseItems) * `Draw` trait and and `DrawFunctions` are now generic on PhaseItem * Modular / Ergonomic `DrawFunctions` via `RenderCommands` * RenderCommand is a trait that runs an ECS query and produces one or more RenderPass calls. Types implementing this trait can be composed to create a final DrawFunction. For example the DrawPbr DrawFunction is created from the following DrawCommand tuple. Const generics are used to set specific bind group locations: ```rust pub type DrawPbr = ( SetPbrPipeline, SetMeshViewBindGroup<0>, SetStandardMaterialBindGroup<1>, SetTransformBindGroup<2>, DrawMesh, ); ``` * The new `custom_shader_pipelined` example illustrates how the commands above can be reused to create a custom draw function: ```rust type DrawCustom = ( SetCustomMaterialPipeline, SetMeshViewBindGroup<0>, SetTransformBindGroup<2>, DrawMesh, ); ``` * ExtractComponentPlugin and UniformComponentPlugin: * Simple, standardized ways to easily extract individual components and write them to GPU buffers * Ported PBR and Sprite rendering to the new primitives above. * Removed staging buffer from UniformVec in favor of direct Queue usage * Makes UniformVec much easier to use and more ergonomic. Completely removes the need for custom render graph nodes in these contexts (see the PbrNode and view Node removals and the much simpler call patterns in the relevant Prepare systems). * Added a many_cubes_pipelined example to benchmark baseline 3d rendering performance and ensure there were no major regressions during this port. Avoiding regressions was challenging given that the old approach of extracting into centralized vectors is basically the "optimal" approach. However thanks to a various ECS optimizations and render logic rephrasing, we pretty much break even on this benchmark! * Lifetimeless SystemParams: this will be a bit divisive, but as we continue to embrace "trait driven systems" (ex: ExtractComponentPlugin, UniformComponentPlugin, DrawCommand), the ergonomics of `(Query<'static, 'static, (&'static A, &'static B, &'static)>, Res<'static, C>)` were getting very hard to bear. As a compromise, I added "static type aliases" for the relevant SystemParams. The previous example can now be expressed like this: `(SQuery<(Read<A>, Read<B>)>, SRes<C>)`. If anyone has better ideas / conflicting opinions, please let me know! * RunSystem trait: a way to define Systems via a trait with a SystemParam associated type. This is used to implement the various plugins mentioned above. I also added SystemParamItem and QueryItem type aliases to make "trait stye" ecs interactions nicer on the eyes (and fingers). * RenderAsset retrying: ensures that render assets are only created when they are "ready" and allows us to create bind groups directly inside render assets (which significantly simplified the StandardMaterial code). I think ultimately we should swap this out on "asset dependency" events to wait for dependencies to load, but this will require significant asset system changes. * Updated some built in shaders to account for missing MeshUniform fields
2021-09-23 06:16:11 +00:00
[[example]]
Replace old renderer with new renderer (#3312) This makes the [New Bevy Renderer](#2535) the default (and only) renderer. The new renderer isn't _quite_ ready for the final release yet, but I want as many people as possible to start testing it so we can identify bugs and address feedback prior to release. The examples are all ported over and operational with a few exceptions: * I removed a good portion of the examples in the `shader` folder. We still have some work to do in order to make these examples possible / ergonomic / worthwhile: #3120 and "high level shader material plugins" are the big ones. This is a temporary measure. * Temporarily removed the multiple_windows example: doing this properly in the new renderer will require the upcoming "render targets" changes. Same goes for the render_to_texture example. * Removed z_sort_debug: entity visibility sort info is no longer available in app logic. we could do this on the "render app" side, but i dont consider it a priority.
2021-12-14 03:58:23 +00:00
name = "shader_material"
path = "examples/shader/shader_material.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Pipeline Specialization, Shader Assets, and Shader Preprocessing (#3031) ## New Features This adds the following to the new renderer: * **Shader Assets** * Shaders are assets again! Users no longer need to call `include_str!` for their shaders * Shader hot-reloading * **Shader Defs / Shader Preprocessing** * Shaders now support `# ifdef NAME`, `# ifndef NAME`, and `# endif` preprocessor directives * **Bevy RenderPipelineDescriptor and RenderPipelineCache** * Bevy now provides its own `RenderPipelineDescriptor` and the wgpu version is now exported as `RawRenderPipelineDescriptor`. This allows users to define pipelines with `Handle<Shader>` instead of needing to manually compile and reference `ShaderModules`, enables passing in shader defs to configure the shader preprocessor, makes hot reloading possible (because the descriptor can be owned and used to create new pipelines when a shader changes), and opens the doors to pipeline specialization. * The `RenderPipelineCache` now handles compiling and re-compiling Bevy RenderPipelineDescriptors. It has internal PipelineLayout and ShaderModule caches. Users receive a `CachedPipelineId`, which can be used to look up the actual `&RenderPipeline` during rendering. * **Pipeline Specialization** * This enables defining per-entity-configurable pipelines that specialize on arbitrary custom keys. In practice this will involve specializing based on things like MSAA values, Shader Defs, Bind Group existence, and Vertex Layouts. * Adds a `SpecializedPipeline` trait and `SpecializedPipelines<MyPipeline>` resource. This is a simple layer that generates Bevy RenderPipelineDescriptors based on a custom key defined for the pipeline. * Specialized pipelines are also hot-reloadable. * This was the result of experimentation with two different approaches: 1. **"generic immediate mode multi-key hash pipeline specialization"** * breaks up the pipeline into multiple "identities" (the core pipeline definition, shader defs, mesh layout, bind group layout). each of these identities has its own key. looking up / compiling a specific version of a pipeline requires composing all of these keys together * the benefit of this approach is that it works for all pipelines / the pipeline is fully identified by the keys. the multiple keys allow pre-hashing parts of the pipeline identity where possible (ex: pre compute the mesh identity for all meshes) * the downside is that any per-entity data that informs the values of these keys could require expensive re-hashes. computing each key for each sprite tanked bevymark performance (sprites don't actually need this level of specialization yet ... but things like pbr and future sprite scenarios might). * this is the approach rafx used last time i checked 2. **"custom key specialization"** * Pipelines by default are not specialized * Pipelines that need specialization implement a SpecializedPipeline trait with a custom key associated type * This allows specialization keys to encode exactly the amount of information required (instead of needing to be a combined hash of the entire pipeline). Generally this should fit in a small number of bytes. Per-entity specialization barely registers anymore on things like bevymark. It also makes things like "shader defs" way cheaper to hash because we can use context specific bitflags instead of strings. * Despite the extra trait, it actually generally makes pipeline definitions + lookups simpler: managing multiple keys (and making the appropriate calls to manage these keys) was way more complicated. * I opted for custom key specialization. It performs better generally and in my opinion is better UX. Fortunately the way this is implemented also allows for custom caches as this all builds on a common abstraction: the RenderPipelineCache. The built in custom key trait is just a simple / pre-defined way to interact with the cache ## Callouts * The SpecializedPipeline trait makes it easy to inherit pipeline configuration in custom pipelines. The changes to `custom_shader_pipelined` and the new `shader_defs_pipelined` example illustrate how much simpler it is to define custom pipelines based on the PbrPipeline. * The shader preprocessor is currently pretty naive (it just uses regexes to process each line). Ultimately we might want to build a more custom parser for more performance + better error handling, but for now I'm happy to optimize for "easy to implement and understand". ## Next Steps * Port compute pipelines to the new system * Add more preprocessor directives (else, elif, import) * More flexible vertex attribute specialization / enable cheaply specializing on specific mesh vertex layouts
2021-10-28 19:07:47 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.shader_material]
name = "Material"
description = "A shader and a material that uses it"
category = "Shaders"
wasm = true
Add shader_material_2d example (#10542) # Objective - 2d materials have subtle differences with 3d materials that aren't obvious to beginners ## Solution - Add an example that shows how to make a 2d material
2023-11-14 02:18:25 +00:00
[[example]]
name = "shader_material_2d"
path = "examples/shader/shader_material_2d.rs"
doc-scrape-examples = true
[package.metadata.example.shader_material_2d]
name = "Material"
description = "A shader and a material that uses it on a 2d mesh"
category = "Shaders"
wasm = true
allow extensions to StandardMaterial (#7820) # Objective allow extending `Material`s (including the built in `StandardMaterial`) with custom vertex/fragment shaders and additional data, to easily get pbr lighting with custom modifications, or otherwise extend a base material. # Solution - added `ExtendedMaterial<B: Material, E: MaterialExtension>` which contains a base material and a user-defined extension. - added example `extended_material` showing how to use it - modified AsBindGroup to have "unprepared" functions that return raw resources / layout entries so that the extended material can combine them note: doesn't currently work with array resources, as i can't figure out how to make the OwnedBindingResource::get_binding() work, as wgpu requires a `&'a[&'a TextureView]` and i have a `Vec<TextureView>`. # Migration Guide manual implementations of `AsBindGroup` will need to be adjusted, the changes are pretty straightforward and can be seen in the diff for e.g. the `texture_binding_array` example. --------- Co-authored-by: Robert Swain <robert.swain@gmail.com>
2023-10-17 21:28:08 +00:00
[[example]]
name = "extended_material"
path = "examples/shader/extended_material.rs"
Fix some doc warnings (#12961) # Objective - Fix some doc warnings - Add doc-scrape-examples to all examples Moved from #12692 I run `cargo +nightly doc --workspace --all-features --no-deps -Zunstable-options -Zrustdoc-scrape-examples` <details> ``` warning: public documentation for `GzAssetLoaderError` links to private item `GzAssetLoader` --> examples/asset/asset_decompression.rs:24:47 | 24 | /// Possible errors that can be produced by [`GzAssetLoader`] | ^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: `bevy` (example "asset_decompression") generated 1 warning warning: unresolved link to `shape::Quad` --> examples/2d/mesh2d.rs:3:15 | 3 | //! [`Quad`]: shape::Quad | ^^^^^^^^^^^ no item named `shape` in scope | = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "mesh2d") generated 1 warning warning: unresolved link to `WorldQuery` --> examples/ecs/custom_query_param.rs:1:49 | 1 | //! This example illustrates the usage of the [`WorldQuery`] derive macro, which allows | ^^^^^^^^^^ no item named `WorldQuery` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "custom_query_param") generated 1 warning warning: unresolved link to `shape::Quad` --> examples/2d/mesh2d_vertex_color_texture.rs:4:15 | 4 | //! [`Quad`]: shape::Quad | ^^^^^^^^^^^ no item named `shape` in scope | = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "mesh2d_vertex_color_texture") generated 1 warning warning: public documentation for `TextPlugin` links to private item `CoolText` --> examples/asset/processing/asset_processing.rs:48:9 | 48 | /// * [`CoolText`]: a custom RON text format that supports dependencies and embedded dependencies | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: public documentation for `TextPlugin` links to private item `Text` --> examples/asset/processing/asset_processing.rs:49:9 | 49 | /// * [`Text`]: a "normal" plain text file | ^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: public documentation for `TextPlugin` links to private item `CoolText` --> examples/asset/processing/asset_processing.rs:51:57 | 51 | /// It also defines an asset processor that will load [`CoolText`], resolve embedded dependenc... | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: `bevy` (example "asset_processing") generated 3 warnings warning: public documentation for `CustomAssetLoaderError` links to private item `CustomAssetLoader` --> examples/asset/custom_asset.rs:20:47 | 20 | /// Possible errors that can be produced by [`CustomAssetLoader`] | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: public documentation for `BlobAssetLoaderError` links to private item `CustomAssetLoader` --> examples/asset/custom_asset.rs:61:47 | 61 | /// Possible errors that can be produced by [`CustomAssetLoader`] | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` ``` ``` warning: `bevy` (example "mesh2d") generated 1 warning warning: public documentation for `log_layers_ecs` links to private item `update_subscriber` --> examples/app/log_layers_ecs.rs:6:18 | 6 | //! Inside the [`update_subscriber`] function we will create a [`mpsc::Sender`] and a [`mpsc::R... | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: unresolved link to `AdvancedLayer` --> examples/app/log_layers_ecs.rs:7:72 | 7 | ... will go into the [`AdvancedLayer`] and the [`Receiver`](mpsc::Receiver) will | ^^^^^^^^^^^^^ no item named `AdvancedLayer` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: unresolved link to `LogEvents` --> examples/app/log_layers_ecs.rs:8:42 | 8 | //! go into a non-send resource called [`LogEvents`] (It has to be non-send because [`Receiver`... | ^^^^^^^^^ no item named `LogEvents` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` warning: public documentation for `log_layers_ecs` links to private item `transfer_log_events` --> examples/app/log_layers_ecs.rs:9:30 | 9 | //! From there we will use [`transfer_log_events`] to transfer log events from [`LogEvents`] to... | ^^^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: unresolved link to `LogEvents` --> examples/app/log_layers_ecs.rs:9:82 | 9 | ...nsfer log events from [`LogEvents`] to an ECS event called [`LogEvent`]. | ^^^^^^^^^ no item named `LogEvents` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` warning: public documentation for `log_layers_ecs` links to private item `LogEvent` --> examples/app/log_layers_ecs.rs:9:119 | 9 | ...nts`] to an ECS event called [`LogEvent`]. | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: public documentation for `log_layers_ecs` links to private item `LogEvent` --> examples/app/log_layers_ecs.rs:11:49 | 11 | //! Finally, after all that we can access the [`LogEvent`] event from our systems and use it. | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` ``` <details/>
2024-04-14 15:23:44 +00:00
doc-scrape-examples = true
allow extensions to StandardMaterial (#7820) # Objective allow extending `Material`s (including the built in `StandardMaterial`) with custom vertex/fragment shaders and additional data, to easily get pbr lighting with custom modifications, or otherwise extend a base material. # Solution - added `ExtendedMaterial<B: Material, E: MaterialExtension>` which contains a base material and a user-defined extension. - added example `extended_material` showing how to use it - modified AsBindGroup to have "unprepared" functions that return raw resources / layout entries so that the extended material can combine them note: doesn't currently work with array resources, as i can't figure out how to make the OwnedBindingResource::get_binding() work, as wgpu requires a `&'a[&'a TextureView]` and i have a `Vec<TextureView>`. # Migration Guide manual implementations of `AsBindGroup` will need to be adjusted, the changes are pretty straightforward and can be seen in the diff for e.g. the `texture_binding_array` example. --------- Co-authored-by: Robert Swain <robert.swain@gmail.com>
2023-10-17 21:28:08 +00:00
[package.metadata.example.extended_material]
name = "Extended Material"
description = "A custom shader that builds on the standard material"
category = "Shaders"
wasm = true
Add depth and normal prepass (#6284) # Objective - Add a configurable prepass - A depth prepass is useful for various shader effects and to reduce overdraw. It can be expansive depending on the scene so it's important to be able to disable it if you don't need any effects that uses it or don't suffer from excessive overdraw. - The goal is to eventually use it for things like TAA, Ambient Occlusion, SSR and various other techniques that can benefit from having a prepass. ## Solution The prepass node is inserted before the main pass. It runs for each `Camera3d` with a prepass component (`DepthPrepass`, `NormalPrepass`). The presence of one of those components is used to determine which textures are generated in the prepass. When any prepass is enabled, the depth buffer generated will be used by the main pass to reduce overdraw. The prepass runs for each `Material` created with the `MaterialPlugin::prepass_enabled` option set to `true`. You can overload the shader used by the prepass by using `Material::prepass_vertex_shader()` and/or `Material::prepass_fragment_shader()`. It will also use the `Material::specialize()` for more advanced use cases. It is enabled by default on all materials. The prepass works on opaque materials and materials using an alpha mask. Transparent materials are ignored. The `StandardMaterial` overloads the prepass fragment shader to support alpha mask and normal maps. --- ## Changelog - Add a new `PrepassNode` that runs before the main pass - Add a `PrepassPlugin` to extract/prepare/queue the necessary data - Add a `DepthPrepass` and `NormalPrepass` component to control which textures will be created by the prepass and available in later passes. - Add a new `prepass_enabled` flag to the `MaterialPlugin` that will control if a material uses the prepass or not. - Add a new `prepass_enabled` flag to the `PbrPlugin` to control if the StandardMaterial uses the prepass. Currently defaults to false. - Add `Material::prepass_vertex_shader()` and `Material::prepass_fragment_shader()` to control the prepass from the `Material` ## Notes In bevy's sample 3d scene, the performance is actually worse when enabling the prepass, but on more complex scenes the performance is generally better. I would like more testing on this, but @DGriffin91 has reported a very noticeable improvements in some scenes. The prepass is also used by @JMS55 for TAA and GTAO discord thread: <https://discord.com/channels/691052431525675048/1011624228627419187> This PR was built on top of the work of multiple people Co-Authored-By: @superdump Co-Authored-By: @robtfm Co-Authored-By: @JMS55 Co-authored-by: Charles <IceSentry@users.noreply.github.com> Co-authored-by: JMS55 <47158642+JMS55@users.noreply.github.com>
2023-01-19 22:11:13 +00:00
[[example]]
name = "shader_prepass"
path = "examples/shader/shader_prepass.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add depth and normal prepass (#6284) # Objective - Add a configurable prepass - A depth prepass is useful for various shader effects and to reduce overdraw. It can be expansive depending on the scene so it's important to be able to disable it if you don't need any effects that uses it or don't suffer from excessive overdraw. - The goal is to eventually use it for things like TAA, Ambient Occlusion, SSR and various other techniques that can benefit from having a prepass. ## Solution The prepass node is inserted before the main pass. It runs for each `Camera3d` with a prepass component (`DepthPrepass`, `NormalPrepass`). The presence of one of those components is used to determine which textures are generated in the prepass. When any prepass is enabled, the depth buffer generated will be used by the main pass to reduce overdraw. The prepass runs for each `Material` created with the `MaterialPlugin::prepass_enabled` option set to `true`. You can overload the shader used by the prepass by using `Material::prepass_vertex_shader()` and/or `Material::prepass_fragment_shader()`. It will also use the `Material::specialize()` for more advanced use cases. It is enabled by default on all materials. The prepass works on opaque materials and materials using an alpha mask. Transparent materials are ignored. The `StandardMaterial` overloads the prepass fragment shader to support alpha mask and normal maps. --- ## Changelog - Add a new `PrepassNode` that runs before the main pass - Add a `PrepassPlugin` to extract/prepare/queue the necessary data - Add a `DepthPrepass` and `NormalPrepass` component to control which textures will be created by the prepass and available in later passes. - Add a new `prepass_enabled` flag to the `MaterialPlugin` that will control if a material uses the prepass or not. - Add a new `prepass_enabled` flag to the `PbrPlugin` to control if the StandardMaterial uses the prepass. Currently defaults to false. - Add `Material::prepass_vertex_shader()` and `Material::prepass_fragment_shader()` to control the prepass from the `Material` ## Notes In bevy's sample 3d scene, the performance is actually worse when enabling the prepass, but on more complex scenes the performance is generally better. I would like more testing on this, but @DGriffin91 has reported a very noticeable improvements in some scenes. The prepass is also used by @JMS55 for TAA and GTAO discord thread: <https://discord.com/channels/691052431525675048/1011624228627419187> This PR was built on top of the work of multiple people Co-Authored-By: @superdump Co-Authored-By: @robtfm Co-Authored-By: @JMS55 Co-authored-by: Charles <IceSentry@users.noreply.github.com> Co-authored-by: JMS55 <47158642+JMS55@users.noreply.github.com>
2023-01-19 22:11:13 +00:00
[package.metadata.example.shader_prepass]
name = "Material Prepass"
Allow prepass in webgl (#7537) # Objective - Use the prepass textures in webgl ## Solution - Bind the prepass textures even when using webgl, but only if msaa is disabled - Also did some refactors to centralize how textures are bound, similar to the EnvironmentMapLight PR - ~~Also did some refactors of the example to make it work in webgl~~ - ~~To make the example work in webgl, I needed to use a sampler for the depth texture, the resulting code looks a bit weird, but it's simple enough and I think it's worth it to show how it works when using webgl~~
2023-03-02 02:23:06 +00:00
description = "A shader that uses the various textures generated by the prepass"
Add depth and normal prepass (#6284) # Objective - Add a configurable prepass - A depth prepass is useful for various shader effects and to reduce overdraw. It can be expansive depending on the scene so it's important to be able to disable it if you don't need any effects that uses it or don't suffer from excessive overdraw. - The goal is to eventually use it for things like TAA, Ambient Occlusion, SSR and various other techniques that can benefit from having a prepass. ## Solution The prepass node is inserted before the main pass. It runs for each `Camera3d` with a prepass component (`DepthPrepass`, `NormalPrepass`). The presence of one of those components is used to determine which textures are generated in the prepass. When any prepass is enabled, the depth buffer generated will be used by the main pass to reduce overdraw. The prepass runs for each `Material` created with the `MaterialPlugin::prepass_enabled` option set to `true`. You can overload the shader used by the prepass by using `Material::prepass_vertex_shader()` and/or `Material::prepass_fragment_shader()`. It will also use the `Material::specialize()` for more advanced use cases. It is enabled by default on all materials. The prepass works on opaque materials and materials using an alpha mask. Transparent materials are ignored. The `StandardMaterial` overloads the prepass fragment shader to support alpha mask and normal maps. --- ## Changelog - Add a new `PrepassNode` that runs before the main pass - Add a `PrepassPlugin` to extract/prepare/queue the necessary data - Add a `DepthPrepass` and `NormalPrepass` component to control which textures will be created by the prepass and available in later passes. - Add a new `prepass_enabled` flag to the `MaterialPlugin` that will control if a material uses the prepass or not. - Add a new `prepass_enabled` flag to the `PbrPlugin` to control if the StandardMaterial uses the prepass. Currently defaults to false. - Add `Material::prepass_vertex_shader()` and `Material::prepass_fragment_shader()` to control the prepass from the `Material` ## Notes In bevy's sample 3d scene, the performance is actually worse when enabling the prepass, but on more complex scenes the performance is generally better. I would like more testing on this, but @DGriffin91 has reported a very noticeable improvements in some scenes. The prepass is also used by @JMS55 for TAA and GTAO discord thread: <https://discord.com/channels/691052431525675048/1011624228627419187> This PR was built on top of the work of multiple people Co-Authored-By: @superdump Co-Authored-By: @robtfm Co-Authored-By: @JMS55 Co-authored-by: Charles <IceSentry@users.noreply.github.com> Co-authored-by: JMS55 <47158642+JMS55@users.noreply.github.com>
2023-01-19 22:11:13 +00:00
category = "Shaders"
wasm = false
examples: add screenspace texture shader example (#4063) Adds a new shader example showing how to sample a texture with screenspace coordinates, similar to the end [portal in minecraft](https://bugs.mojang.com/secure/attachment/163759/portal_frame_112.gif). https://user-images.githubusercontent.com/22177966/156031195-33d14ed8-733f-4d9e-b1da-0fc807c994a5.mp4 I just used the already existent `models/FlightHelmet/FlightHelmet_Materials_LensesMat_OcclusionRoughMetal.png` texture but maybe we should use a dedicated texture for the example. Suggestions welcome. Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-02-28 22:55:14 +00:00
[[example]]
name = "shader_material_screenspace_texture"
path = "examples/shader/shader_material_screenspace_texture.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
examples: add screenspace texture shader example (#4063) Adds a new shader example showing how to sample a texture with screenspace coordinates, similar to the end [portal in minecraft](https://bugs.mojang.com/secure/attachment/163759/portal_frame_112.gif). https://user-images.githubusercontent.com/22177966/156031195-33d14ed8-733f-4d9e-b1da-0fc807c994a5.mp4 I just used the already existent `models/FlightHelmet/FlightHelmet_Materials_LensesMat_OcclusionRoughMetal.png` texture but maybe we should use a dedicated texture for the example. Suggestions welcome. Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-02-28 22:55:14 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.shader_material_screenspace_texture]
name = "Material - Screenspace Texture"
description = "A shader that samples a texture with view-independent UV coordinates"
category = "Shaders"
wasm = true
add some more pipelined-rendering shader examples (#3041) based on #3031 Adds some examples showing of how to use the new pipelined rendering for custom shaders. - a minimal shader example which doesn't use render assets - the same but using glsl - an example showing how to render instanced data - a shader which uses the seconds since startup to animate some textures Instancing shader: ![grafik](https://user-images.githubusercontent.com/22177966/139299294-e176b62a-53d1-4287-9a66-02fb55affc02.png) Animated shader: ![animate_shader](https://user-images.githubusercontent.com/22177966/139299718-2940c0f3-8480-4ee0-98d7-b6ba40dc1472.gif) (the gif makes it look a bit ugly) Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-01-05 19:43:11 +00:00
[[example]]
name = "shader_material_glsl"
path = "examples/shader/shader_material_glsl.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
add a required feature for shader_material_glsl (#11440) # Objective - Since https://github.com/bevyengine/bevy/pull/11366, feature `glsl` of `naga_oil` is not enabled by default - It is needed for example `shader_material_glsl` ``` thread 'Compute Task Pool (0)' panicked at crates\bevy_render\src\render_resource\shader.rs:238:35: GLSL is not supported in this configuration; use the feature `shader_format_glsl` note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace Encountered a panic in system `bevy_render::render_resource::pipeline_cache::PipelineCache::process_pipeline_queue_system`! thread 'main' panicked at crates\bevy_render\src\pipelined_rendering.rs:145:45: called `Result::unwrap()` on an `Err` value: RecvError ``` ## Solution - Add feature `shader_format_glsl` as a required feature for example `shader_material_glsl`
2024-01-20 19:55:19 +00:00
required-features = ["shader_format_glsl"]
add some more pipelined-rendering shader examples (#3041) based on #3031 Adds some examples showing of how to use the new pipelined rendering for custom shaders. - a minimal shader example which doesn't use render assets - the same but using glsl - an example showing how to render instanced data - a shader which uses the seconds since startup to animate some textures Instancing shader: ![grafik](https://user-images.githubusercontent.com/22177966/139299294-e176b62a-53d1-4287-9a66-02fb55affc02.png) Animated shader: ![animate_shader](https://user-images.githubusercontent.com/22177966/139299718-2940c0f3-8480-4ee0-98d7-b6ba40dc1472.gif) (the gif makes it look a bit ugly) Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-01-05 19:43:11 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.shader_material_glsl]
name = "Material - GLSL"
description = "A shader that uses the GLSL shading language"
category = "Shaders"
wasm = true
add some more pipelined-rendering shader examples (#3041) based on #3031 Adds some examples showing of how to use the new pipelined rendering for custom shaders. - a minimal shader example which doesn't use render assets - the same but using glsl - an example showing how to render instanced data - a shader which uses the seconds since startup to animate some textures Instancing shader: ![grafik](https://user-images.githubusercontent.com/22177966/139299294-e176b62a-53d1-4287-9a66-02fb55affc02.png) Animated shader: ![animate_shader](https://user-images.githubusercontent.com/22177966/139299718-2940c0f3-8480-4ee0-98d7-b6ba40dc1472.gif) (the gif makes it look a bit ugly) Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-01-05 19:43:11 +00:00
[[example]]
Clarify purpose of shader_instancing example (#15456) # Objective - The shader_instancing example can be misleading since it doesn't explain that bevy has built in automatic instancing. ## Solution - Explain that bevy has built in instancing and that this example is for advanced users. - Add a new automatic_instancing example that shows how to use the built in automatic instancing - Rename the shader_instancing example to custom_shader_instancing to highlight that this is a more advanced implementation --------- Co-authored-by: JMS55 <47158642+JMS55@users.noreply.github.com>
2024-09-30 17:39:58 +00:00
name = "custom_shader_instancing"
path = "examples/shader/custom_shader_instancing.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
add some more pipelined-rendering shader examples (#3041) based on #3031 Adds some examples showing of how to use the new pipelined rendering for custom shaders. - a minimal shader example which doesn't use render assets - the same but using glsl - an example showing how to render instanced data - a shader which uses the seconds since startup to animate some textures Instancing shader: ![grafik](https://user-images.githubusercontent.com/22177966/139299294-e176b62a-53d1-4287-9a66-02fb55affc02.png) Animated shader: ![animate_shader](https://user-images.githubusercontent.com/22177966/139299718-2940c0f3-8480-4ee0-98d7-b6ba40dc1472.gif) (the gif makes it look a bit ugly) Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-01-05 19:43:11 +00:00
Clarify purpose of shader_instancing example (#15456) # Objective - The shader_instancing example can be misleading since it doesn't explain that bevy has built in automatic instancing. ## Solution - Explain that bevy has built in instancing and that this example is for advanced users. - Add a new automatic_instancing example that shows how to use the built in automatic instancing - Rename the shader_instancing example to custom_shader_instancing to highlight that this is a more advanced implementation --------- Co-authored-by: JMS55 <47158642+JMS55@users.noreply.github.com>
2024-09-30 17:39:58 +00:00
[package.metadata.example.custom_shader_instancing]
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
name = "Instancing"
Clarify purpose of shader_instancing example (#15456) # Objective - The shader_instancing example can be misleading since it doesn't explain that bevy has built in automatic instancing. ## Solution - Explain that bevy has built in instancing and that this example is for advanced users. - Add a new automatic_instancing example that shows how to use the built in automatic instancing - Rename the shader_instancing example to custom_shader_instancing to highlight that this is a more advanced implementation --------- Co-authored-by: JMS55 <47158642+JMS55@users.noreply.github.com>
2024-09-30 17:39:58 +00:00
description = "A shader that renders a mesh multiple times in one draw call using low level rendering api"
category = "Shaders"
wasm = true
[[example]]
name = "automatic_instancing"
path = "examples/shader/automatic_instancing.rs"
doc-scrape-examples = true
[package.metadata.example.automatic_instancing]
name = "Instancing"
description = "Shows that multiple instances of a cube are automatically instanced in one draw call"
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
category = "Shaders"
wasm = true
add some more pipelined-rendering shader examples (#3041) based on #3031 Adds some examples showing of how to use the new pipelined rendering for custom shaders. - a minimal shader example which doesn't use render assets - the same but using glsl - an example showing how to render instanced data - a shader which uses the seconds since startup to animate some textures Instancing shader: ![grafik](https://user-images.githubusercontent.com/22177966/139299294-e176b62a-53d1-4287-9a66-02fb55affc02.png) Animated shader: ![animate_shader](https://user-images.githubusercontent.com/22177966/139299718-2940c0f3-8480-4ee0-98d7-b6ba40dc1472.gif) (the gif makes it look a bit ugly) Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-01-05 19:43:11 +00:00
[[example]]
name = "animate_shader"
path = "examples/shader/animate_shader.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
add some more pipelined-rendering shader examples (#3041) based on #3031 Adds some examples showing of how to use the new pipelined rendering for custom shaders. - a minimal shader example which doesn't use render assets - the same but using glsl - an example showing how to render instanced data - a shader which uses the seconds since startup to animate some textures Instancing shader: ![grafik](https://user-images.githubusercontent.com/22177966/139299294-e176b62a-53d1-4287-9a66-02fb55affc02.png) Animated shader: ![animate_shader](https://user-images.githubusercontent.com/22177966/139299718-2940c0f3-8480-4ee0-98d7-b6ba40dc1472.gif) (the gif makes it look a bit ugly) Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-01-05 19:43:11 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.animate_shader]
name = "Animated"
description = "A shader that uses dynamic data like the time since startup"
category = "Shaders"
wasm = true
add some more pipelined-rendering shader examples (#3041) based on #3031 Adds some examples showing of how to use the new pipelined rendering for custom shaders. - a minimal shader example which doesn't use render assets - the same but using glsl - an example showing how to render instanced data - a shader which uses the seconds since startup to animate some textures Instancing shader: ![grafik](https://user-images.githubusercontent.com/22177966/139299294-e176b62a-53d1-4287-9a66-02fb55affc02.png) Animated shader: ![animate_shader](https://user-images.githubusercontent.com/22177966/139299718-2940c0f3-8480-4ee0-98d7-b6ba40dc1472.gif) (the gif makes it look a bit ugly) Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-01-05 19:43:11 +00:00
[[example]]
name = "compute_shader_game_of_life"
path = "examples/shader/compute_shader_game_of_life.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
add some more pipelined-rendering shader examples (#3041) based on #3031 Adds some examples showing of how to use the new pipelined rendering for custom shaders. - a minimal shader example which doesn't use render assets - the same but using glsl - an example showing how to render instanced data - a shader which uses the seconds since startup to animate some textures Instancing shader: ![grafik](https://user-images.githubusercontent.com/22177966/139299294-e176b62a-53d1-4287-9a66-02fb55affc02.png) Animated shader: ![animate_shader](https://user-images.githubusercontent.com/22177966/139299718-2940c0f3-8480-4ee0-98d7-b6ba40dc1472.gif) (the gif makes it look a bit ugly) Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-01-05 19:43:11 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.compute_shader_game_of_life]
name = "Compute - Game of Life"
description = "A compute shader that simulates Conway's Game of Life"
category = "Shaders"
wasm = false
Add gpu readback example (#12877) # Objective - It's pretty common for users to want to read data back from the gpu and into the main world ## Solution - Add a simple example that shows how to read data back from the gpu and send it to the main world using a channel. - The example is largely based on this wgpu example but adapted to bevy - https://github.com/gfx-rs/wgpu/blob/fb305b85f692f3fbbd9509b648dfbc97072f7465/examples/src/repeated_compute/mod.rs --------- Co-authored-by: stormy <120167078+stowmyy@users.noreply.github.com> Co-authored-by: Torstein Grindvik <52322338+torsteingrindvik@users.noreply.github.com>
2024-04-08 17:08:20 +00:00
[[example]]
name = "gpu_readback"
path = "examples/shader/gpu_readback.rs"
doc-scrape-examples = true
[package.metadata.example.gpu_readback]
name = "GPU readback"
description = "A very simple compute shader that writes to a buffer that is read by the cpu"
category = "Shaders"
wasm = false
Array texture example (#5077) # Objective - Make the reusable PBR shading functionality a little more reusable - Add constructor functions for `StandardMaterial` and `PbrInput` structs to populate them with default values - Document unclear `PbrInput` members - Demonstrate how to reuse the bevy PBR shading functionality - The final important piece from #3969 as the initial shot at making the PBR shader code reusable in custom materials ## Solution - Add back and rework the 'old' `array_texture` example from pre-0.6. - Create a custom shader material - Use a single array texture binding and sampler for the material bind group - Use a shader that calls `pbr()` from the `bevy_pbr::pbr_functions` import - Spawn a row of cubes using the custom material - In the shader, select the array texture layer to sample by using the world position x coordinate modulo the number of array texture layers <img width="1392" alt="Screenshot 2022-06-23 at 12 28 05" src="https://user-images.githubusercontent.com/302146/175278593-2296f519-f577-4ece-81c0-d842283784a1.png"> Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-06-28 00:58:50 +00:00
[[example]]
name = "array_texture"
path = "examples/shader/array_texture.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Array texture example (#5077) # Objective - Make the reusable PBR shading functionality a little more reusable - Add constructor functions for `StandardMaterial` and `PbrInput` structs to populate them with default values - Document unclear `PbrInput` members - Demonstrate how to reuse the bevy PBR shading functionality - The final important piece from #3969 as the initial shot at making the PBR shader code reusable in custom materials ## Solution - Add back and rework the 'old' `array_texture` example from pre-0.6. - Create a custom shader material - Use a single array texture binding and sampler for the material bind group - Use a shader that calls `pbr()` from the `bevy_pbr::pbr_functions` import - Spawn a row of cubes using the custom material - In the shader, select the array texture layer to sample by using the world position x coordinate modulo the number of array texture layers <img width="1392" alt="Screenshot 2022-06-23 at 12 28 05" src="https://user-images.githubusercontent.com/302146/175278593-2296f519-f577-4ece-81c0-d842283784a1.png"> Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-06-28 00:58:50 +00:00
[package.metadata.example.array_texture]
name = "Array Texture"
description = "A shader that shows how to reuse the core bevy PBR shading functionality in a custom material that obtains the base color from an array texture."
category = "Shaders"
wasm = true
Request WGPU Capabilities for Non-uniform Indexing (#6995) # Objective Fixes #6952 ## Solution - Request WGPU capabilities `SAMPLED_TEXTURE_AND_STORAGE_BUFFER_ARRAY_NON_UNIFORM_INDEXING`, `SAMPLER_NON_UNIFORM_INDEXING` and `UNIFORM_BUFFER_AND_STORAGE_TEXTURE_ARRAY_NON_UNIFORM_INDEXING` when corresponding features are enabled. - Add an example (`shaders/texture_binding_array`) illustrating (and testing) the use of non-uniform indexed textures and samplers. ![image](https://user-images.githubusercontent.com/16053640/209448310-defa4eae-6bcb-460d-9b3d-a3d2fad4316c.png) ## Changelog - Added new capabilities for shader validation. - Added example `shaders/texture_binding_array`.
2023-01-26 13:18:15 +00:00
[[example]]
name = "texture_binding_array"
path = "examples/shader/texture_binding_array.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Request WGPU Capabilities for Non-uniform Indexing (#6995) # Objective Fixes #6952 ## Solution - Request WGPU capabilities `SAMPLED_TEXTURE_AND_STORAGE_BUFFER_ARRAY_NON_UNIFORM_INDEXING`, `SAMPLER_NON_UNIFORM_INDEXING` and `UNIFORM_BUFFER_AND_STORAGE_TEXTURE_ARRAY_NON_UNIFORM_INDEXING` when corresponding features are enabled. - Add an example (`shaders/texture_binding_array`) illustrating (and testing) the use of non-uniform indexed textures and samplers. ![image](https://user-images.githubusercontent.com/16053640/209448310-defa4eae-6bcb-460d-9b3d-a3d2fad4316c.png) ## Changelog - Added new capabilities for shader validation. - Added example `shaders/texture_binding_array`.
2023-01-26 13:18:15 +00:00
[package.metadata.example.texture_binding_array]
name = "Texture Binding Array (Bindless Textures)"
description = "A shader that shows how to bind and sample multiple textures as a binding array (a.k.a. bindless textures)."
category = "Shaders"
wasm = false
Adds `ShaderStorageBuffer` asset (#14663) Adds a new `Handle<Storage>` asset type that can be used as a render asset, particularly for use with `AsBindGroup`. Closes: #13658 # Objective Allow users to create storage buffers in the main world without having to access the `RenderDevice`. While this resource is technically available, it's bad form to use in the main world and requires mixing rendering details with main world code. Additionally, this makes storage buffers easier to use with `AsBindGroup`, particularly in the following scenarios: - Sharing the same buffers between a compute stage and material shader. We already have examples of this for storage textures (see game of life example) and these changes allow a similar pattern to be used with storage buffers. - Preventing repeated gpu upload (see the previous easier to use `Vec` `AsBindGroup` option). - Allow initializing custom materials using `Default`. Previously, the lack of a `Default` implement for the raw `wgpu::Buffer` type made implementing a `AsBindGroup + Default` bound difficult in the presence of buffers. ## Solution Adds a new `Handle<Storage>` asset type that is prepared into a `GpuStorageBuffer` render asset. This asset can either be initialized with a `Vec<u8>` of properly aligned data or with a size hint. Users can modify the underlying `wgpu::BufferDescriptor` to provide additional usage flags. ## Migration Guide The `AsBindGroup` `storage` attribute has been modified to reference the new `Handle<Storage>` asset instead. Usages of Vec` should be converted into assets instead. --------- Co-authored-by: IceSentry <IceSentry@users.noreply.github.com>
2024-09-02 16:46:34 +00:00
[[example]]
name = "storage_buffer"
path = "examples/shader/storage_buffer.rs"
doc-scrape-examples = true
[package.metadata.example.storage_buffer]
name = "Storage Buffer"
description = "A shader that shows how to bind a storage buffer using a custom material."
category = "Shaders"
wasm = true
Add example showing how to use SpecializedMeshPipeline (#14370) # Objective - A lot of mid-level rendering apis are hard to figure out because they don't have any examples - SpecializedMeshPipeline can be really useful in some cases when you want more flexibility than a Material without having to go to low level apis. ## Solution - Add an example showing how to make a custom `SpecializedMeshPipeline`. ## Testing - Did you test these changes? If so, how? - Are there any parts that need more testing? - How can other people (reviewers) test your changes? Is there anything specific they need to know? - If relevant, what platforms did you test these changes on, and are there any important ones you can't test? --- ## Showcase The examples just spawns 3 triangles in a triangle pattern. ![image](https://github.com/user-attachments/assets/c3098758-94c4-4775-95e5-1d7c7fb9eb86) --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2024-07-31 18:24:58 +00:00
[[example]]
name = "specialized_mesh_pipeline"
path = "examples/shader/specialized_mesh_pipeline.rs"
doc-scrape-examples = true
[package.metadata.example.specialized_mesh_pipeline]
name = "Specialized Mesh Pipeline"
description = "Demonstrates how to write a specialized mesh pipeline"
category = "Shaders"
wasm = true
Group stress test examples (#4289) # Objective - Several examples are useful for qualitative tests of Bevy's performance - By contrast, these are less useful for learning material: they are often relatively complex and have large amounts of setup and are performance optimized. ## Solution - Move bevymark, many_sprites and many_cubes into the new stress_tests example folder - Move contributors into the games folder: unlike the remaining examples in the 2d folder, it is not focused on demonstrating a clear feature.
2022-04-10 02:05:21 +00:00
# Stress tests
Feature documentation (#7814) # Objective - Fixes #1800, fixes #6984 - Alternative to #7196 - Ensure feature list is always up to date and that all are documented - Help discovery of features ## Solution - Use a template to update the cargo feature list - Use the comment just above the feature declaration as the description - Add the checks to CI - Add the features to the base crate doc
2023-02-28 14:24:47 +00:00
[[package.metadata.example_category]]
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
name = "Stress Tests"
description = """
These examples are used to test the performance and stability of various parts of the engine in an isolated way.
Due to the focus on performance it's recommended to run the stress tests in release mode:
```sh
cargo run --release --example <example name>
```
"""
Group stress test examples (#4289) # Objective - Several examples are useful for qualitative tests of Bevy's performance - By contrast, these are less useful for learning material: they are often relatively complex and have large amounts of setup and are performance optimized. ## Solution - Move bevymark, many_sprites and many_cubes into the new stress_tests example folder - Move contributors into the games folder: unlike the remaining examples in the 2d folder, it is not focused on demonstrating a clear feature.
2022-04-10 02:05:21 +00:00
add bevymark benchmark example (#273) add bevymark example
2020-11-13 02:03:57 +00:00
[[example]]
name = "bevymark"
Group stress test examples (#4289) # Objective - Several examples are useful for qualitative tests of Bevy's performance - By contrast, these are less useful for learning material: they are often relatively complex and have large amounts of setup and are performance optimized. ## Solution - Move bevymark, many_sprites and many_cubes into the new stress_tests example folder - Move contributors into the games folder: unlike the remaining examples in the 2d folder, it is not focused on demonstrating a clear feature.
2022-04-10 02:05:21 +00:00
path = "examples/stress_tests/bevymark.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Group stress test examples (#4289) # Objective - Several examples are useful for qualitative tests of Bevy's performance - By contrast, these are less useful for learning material: they are often relatively complex and have large amounts of setup and are performance optimized. ## Solution - Move bevymark, many_sprites and many_cubes into the new stress_tests example folder - Move contributors into the games folder: unlike the remaining examples in the 2d folder, it is not focused on demonstrating a clear feature.
2022-04-10 02:05:21 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.bevymark]
name = "Bevymark"
description = "A heavy sprite rendering workload to benchmark your system with Bevy"
category = "Stress Tests"
wasm = true
Add TextureAtlas stress test based on many_sprites and sprite_sheet examples (#5087) # Objective Intended to close #5073 ## Solution Adds a stress test that use TextureAtlas based on the existing many_sprites test using the animated sprite implementation from the sprite_sheet example. In order to satisfy the goals described in #5073 the animations are all slightly offset. Of note is that the original stress test was designed to test fullstrum culling. I kept this test similar as to facilitate easy comparisons between the use of TextureAtlas and without.
2022-07-04 13:04:15 +00:00
[[example]]
name = "many_animated_sprites"
path = "examples/stress_tests/many_animated_sprites.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add TextureAtlas stress test based on many_sprites and sprite_sheet examples (#5087) # Objective Intended to close #5073 ## Solution Adds a stress test that use TextureAtlas based on the existing many_sprites test using the animated sprite implementation from the sprite_sheet example. In order to satisfy the goals described in #5073 the animations are all slightly offset. Of note is that the original stress test was designed to test fullstrum culling. I kept this test similar as to facilitate easy comparisons between the use of TextureAtlas and without.
2022-07-04 13:04:15 +00:00
[package.metadata.example.many_animated_sprites]
name = "Many Animated Sprites"
Added colors to sprite stress test (#5317) # Objective Allow better performance testing for https://github.com/bevyengine/bevy/pull/5247 ## Solution I added color tints to the `many_sprites` example stress test.
2022-07-14 11:03:13 +00:00
description = "Displays many animated sprites in a grid arrangement with slight offsets to their animation timers. Used for performance testing."
Add TextureAtlas stress test based on many_sprites and sprite_sheet examples (#5087) # Objective Intended to close #5073 ## Solution Adds a stress test that use TextureAtlas based on the existing many_sprites test using the animated sprite implementation from the sprite_sheet example. In order to satisfy the goals described in #5073 the animations are all slightly offset. Of note is that the original stress test was designed to test fullstrum culling. I kept this test similar as to facilitate easy comparisons between the use of TextureAtlas and without.
2022-07-04 13:04:15 +00:00
category = "Stress Tests"
wasm = true
Add stress test for many ui elements (#5253) # Objective Bevy need a way to benchmark UI rendering code, this PR adds a stress test that spawns a lot of buttons. ## Solution - Add the `many_buttons` stress test. --- ## Changelog - Add the `many_buttons` stress test.
2022-07-21 14:39:03 +00:00
[[example]]
name = "many_buttons"
path = "examples/stress_tests/many_buttons.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add stress test for many ui elements (#5253) # Objective Bevy need a way to benchmark UI rendering code, this PR adds a stress test that spawns a lot of buttons. ## Solution - Add the `many_buttons` stress test. --- ## Changelog - Add the `many_buttons` stress test.
2022-07-21 14:39:03 +00:00
[package.metadata.example.many_buttons]
name = "Many Buttons"
description = "Test rendering of many UI elements"
category = "Stress Tests"
wasm = true
Do not re-check visibility or re-render shadow maps for point and spot lights for each view (#15156) # Objective _If I understand it correctly_, we were checking mesh visibility, as well as re-rendering point and spot light shadow maps for each view. This makes it so that M views and N lights produce M x N complexity. This PR aims to fix that, as well as introduce a stress test for this specific scenario. ## Solution - Keep track of what lights have already had mesh visibility calculated and do not calculate it again; - Reuse shadow depth textures and attachments across all views, and only render shadow maps for the _first_ time a light is encountered on a view; - Directional lights remain unaltered, since their shadow map cascades are view-dependent; - Add a new `many_cameras_lights` stress test example to verify the solution ## Showcase 110% speed up on the stress test 83% reduction of memory usage in stress test ### Before (5.35 FPS on stress test) <img width="1392" alt="Screenshot 2024-09-11 at 12 25 57" src="https://github.com/user-attachments/assets/136b0785-e9a4-44df-9a22-f99cc465e126"> ### After (11.34 FPS on stress test) <img width="1392" alt="Screenshot 2024-09-11 at 12 24 35" src="https://github.com/user-attachments/assets/b8dd858f-5e19-467f-8344-2b46ca039630"> ## Testing - Did you test these changes? If so, how? - On my game project where I have two cameras, and many shadow casting lights I managed to get pretty much double the FPS. - Also included a stress test, see the comparison above - Are there any parts that need more testing? - Yes, I would like help verifying that this fix is indeed correct, and that we were really re-rendering the shadow maps by mistake and it's indeed okay to not do that - How can other people (reviewers) test your changes? Is there anything specific they need to know? - Run the `many_cameras_lights` example - On the `main` branch, cherry pick the commit with the example (`git cherry-pick --no-commit 1ed4ace01`) and run it - If relevant, what platforms did you test these changes on, and are there any important ones you can't test? - macOS --------- Co-authored-by: François Mockers <francois.mockers@vleue.com>
2024-11-11 18:49:09 +00:00
[[example]]
name = "many_cameras_lights"
path = "examples/stress_tests/many_cameras_lights.rs"
doc-scrape-examples = true
[package.metadata.example.many_cameras_lights]
name = "Many Cameras & Lights"
description = "Test rendering of many cameras and lights"
category = "Stress Tests"
wasm = true
Group stress test examples (#4289) # Objective - Several examples are useful for qualitative tests of Bevy's performance - By contrast, these are less useful for learning material: they are often relatively complex and have large amounts of setup and are performance optimized. ## Solution - Move bevymark, many_sprites and many_cubes into the new stress_tests example folder - Move contributors into the games folder: unlike the remaining examples in the 2d folder, it is not focused on demonstrating a clear feature.
2022-04-10 02:05:21 +00:00
[[example]]
name = "many_cubes"
path = "examples/stress_tests/many_cubes.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Group stress test examples (#4289) # Objective - Several examples are useful for qualitative tests of Bevy's performance - By contrast, these are less useful for learning material: they are often relatively complex and have large amounts of setup and are performance optimized. ## Solution - Move bevymark, many_sprites and many_cubes into the new stress_tests example folder - Move contributors into the games folder: unlike the remaining examples in the 2d folder, it is not focused on demonstrating a clear feature.
2022-04-10 02:05:21 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.many_cubes]
name = "Many Cubes"
description = "Simple benchmark to test per-entity draw overhead. Run with the `sphere` argument to test frustum culling"
category = "Stress Tests"
wasm = true
Immediate Mode Line/Gizmo Drawing (#6529) # Objective Add a convenient immediate mode drawing API for visual debugging. Fixes #5619 Alternative to #1625 Partial alternative to #5734 Based off https://github.com/Toqozz/bevy_debug_lines with some changes: * Simultaneous support for 2D and 3D. * Methods for basic shapes; circles, spheres, rectangles, boxes, etc. * 2D methods. * Removed durations. Seemed niche, and can be handled by users. <details> <summary>Performance</summary> Stress tested using Bevy's recommended optimization settings for the dev profile with the following command. ```bash cargo run --example many_debug_lines \ --config "profile.dev.package.\"*\".opt-level=3" \ --config "profile.dev.opt-level=1" ``` I dipped to 65-70 FPS at 300,000 lines CPU: 3700x RAM Speed: 3200 Mhz GPU: 2070 super - probably not very relevant, mostly cpu/memory bound </details> <details> <summary>Fancy bloom screenshot</summary> ![Screenshot_20230207_155033](https://user-images.githubusercontent.com/29694403/217291980-f1e0500e-7a14-4131-8c96-eaaaf52596ae.png) </details> ## Changelog * Added `GizmoPlugin` * Added `Gizmos` system parameter for drawing lines and wireshapes. ### TODO - [ ] Update changelog - [x] Update performance numbers - [x] Add credit to PR description ### Future work - Cache rendering primitives instead of constructing them out of line segments each frame. - Support for drawing solid meshes - Interactions. (See [bevy_mod_gizmos](https://github.com/LiamGallagher737/bevy_mod_gizmos)) - Fancier line drawing. (See [bevy_polyline](https://github.com/ForesightMiningSoftwareCorporation/bevy_polyline)) - Support for `RenderLayers` - Display gizmos for a certain duration. Currently everything displays for one frame (ie. immediate mode) - Changing settings per drawn item like drawing on top or drawing to different `RenderLayers` Co-Authored By: @lassade <felipe.jorge.pereira@gmail.com> Co-Authored By: @The5-1 <agaku@hotmail.de> Co-Authored By: @Toqozz <toqoz@hotmail.com> Co-Authored By: @nicopap <nico@nicopap.ch> --------- Co-authored-by: Robert Swain <robert.swain@gmail.com> Co-authored-by: IceSentry <c.giguere42@gmail.com> Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-03-20 20:57:54 +00:00
[[example]]
name = "many_gizmos"
path = "examples/stress_tests/many_gizmos.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Immediate Mode Line/Gizmo Drawing (#6529) # Objective Add a convenient immediate mode drawing API for visual debugging. Fixes #5619 Alternative to #1625 Partial alternative to #5734 Based off https://github.com/Toqozz/bevy_debug_lines with some changes: * Simultaneous support for 2D and 3D. * Methods for basic shapes; circles, spheres, rectangles, boxes, etc. * 2D methods. * Removed durations. Seemed niche, and can be handled by users. <details> <summary>Performance</summary> Stress tested using Bevy's recommended optimization settings for the dev profile with the following command. ```bash cargo run --example many_debug_lines \ --config "profile.dev.package.\"*\".opt-level=3" \ --config "profile.dev.opt-level=1" ``` I dipped to 65-70 FPS at 300,000 lines CPU: 3700x RAM Speed: 3200 Mhz GPU: 2070 super - probably not very relevant, mostly cpu/memory bound </details> <details> <summary>Fancy bloom screenshot</summary> ![Screenshot_20230207_155033](https://user-images.githubusercontent.com/29694403/217291980-f1e0500e-7a14-4131-8c96-eaaaf52596ae.png) </details> ## Changelog * Added `GizmoPlugin` * Added `Gizmos` system parameter for drawing lines and wireshapes. ### TODO - [ ] Update changelog - [x] Update performance numbers - [x] Add credit to PR description ### Future work - Cache rendering primitives instead of constructing them out of line segments each frame. - Support for drawing solid meshes - Interactions. (See [bevy_mod_gizmos](https://github.com/LiamGallagher737/bevy_mod_gizmos)) - Fancier line drawing. (See [bevy_polyline](https://github.com/ForesightMiningSoftwareCorporation/bevy_polyline)) - Support for `RenderLayers` - Display gizmos for a certain duration. Currently everything displays for one frame (ie. immediate mode) - Changing settings per drawn item like drawing on top or drawing to different `RenderLayers` Co-Authored By: @lassade <felipe.jorge.pereira@gmail.com> Co-Authored By: @The5-1 <agaku@hotmail.de> Co-Authored By: @Toqozz <toqoz@hotmail.com> Co-Authored By: @nicopap <nico@nicopap.ch> --------- Co-authored-by: Robert Swain <robert.swain@gmail.com> Co-authored-by: IceSentry <c.giguere42@gmail.com> Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-03-20 20:57:54 +00:00
[package.metadata.example.many_gizmos]
name = "Many Gizmos"
description = "Test rendering of many gizmos"
category = "Stress Tests"
wasm = true
Add a fun skinned mesh stress test based on the animated_fox example (#4674) # Objective - Add a stress test for skinned meshes https://user-images.githubusercontent.com/302146/167111578-55a7d58a-0ec8-4735-a043-f084f0ff3939.mp4
2022-05-08 02:57:00 +00:00
[[example]]
name = "many_foxes"
path = "examples/stress_tests/many_foxes.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add a fun skinned mesh stress test based on the animated_fox example (#4674) # Objective - Add a stress test for skinned meshes https://user-images.githubusercontent.com/302146/167111578-55a7d58a-0ec8-4735-a043-f084f0ff3939.mp4
2022-05-08 02:57:00 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.many_foxes]
name = "Many Foxes"
description = "Loads an animated fox model and spawns lots of them. Good for testing skinned mesh performance. Takes an unsigned integer argument for the number of foxes to spawn. Defaults to 1000"
category = "Stress Tests"
Perform text scaling calculations per text, not per glyph (#7819)
2023-03-14 00:01:27 +00:00
wasm = true
[[example]]
name = "many_glyphs"
path = "examples/stress_tests/many_glyphs.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Perform text scaling calculations per text, not per glyph (#7819)
2023-03-14 00:01:27 +00:00
[package.metadata.example.many_glyphs]
name = "Many Glyphs"
description = "Simple benchmark to test text rendering."
category = "Stress Tests"
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
wasm = true
Group stress test examples (#4289) # Objective - Several examples are useful for qualitative tests of Bevy's performance - By contrast, these are less useful for learning material: they are often relatively complex and have large amounts of setup and are performance optimized. ## Solution - Move bevymark, many_sprites and many_cubes into the new stress_tests example folder - Move contributors into the games folder: unlike the remaining examples in the 2d folder, it is not focused on demonstrating a clear feature.
2022-04-10 02:05:21 +00:00
[[example]]
name = "many_lights"
path = "examples/stress_tests/many_lights.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Group stress test examples (#4289) # Objective - Several examples are useful for qualitative tests of Bevy's performance - By contrast, these are less useful for learning material: they are often relatively complex and have large amounts of setup and are performance optimized. ## Solution - Move bevymark, many_sprites and many_cubes into the new stress_tests example folder - Move contributors into the games folder: unlike the remaining examples in the 2d folder, it is not focused on demonstrating a clear feature.
2022-04-10 02:05:21 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.many_lights]
name = "Many Lights"
description = "Simple benchmark to test rendering many point lights. Run with `WGPU_SETTINGS_PRIO=webgl2` to restrict to uniform buffers and max 256 lights"
category = "Stress Tests"
wasm = true
Group stress test examples (#4289) # Objective - Several examples are useful for qualitative tests of Bevy's performance - By contrast, these are less useful for learning material: they are often relatively complex and have large amounts of setup and are performance optimized. ## Solution - Move bevymark, many_sprites and many_cubes into the new stress_tests example folder - Move contributors into the games folder: unlike the remaining examples in the 2d folder, it is not focused on demonstrating a clear feature.
2022-04-10 02:05:21 +00:00
[[example]]
name = "many_sprites"
path = "examples/stress_tests/many_sprites.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Group stress test examples (#4289) # Objective - Several examples are useful for qualitative tests of Bevy's performance - By contrast, these are less useful for learning material: they are often relatively complex and have large amounts of setup and are performance optimized. ## Solution - Move bevymark, many_sprites and many_cubes into the new stress_tests example folder - Move contributors into the games folder: unlike the remaining examples in the 2d folder, it is not focused on demonstrating a clear feature.
2022-04-10 02:05:21 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.many_sprites]
name = "Many Sprites"
Added colors to sprite stress test (#5317) # Objective Allow better performance testing for https://github.com/bevyengine/bevy/pull/5247 ## Solution I added color tints to the `many_sprites` example stress test.
2022-07-14 11:03:13 +00:00
description = "Displays many sprites in a grid arrangement! Used for performance testing. Use `--colored` to enable color tinted sprites."
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
category = "Stress Tests"
wasm = true
Group stress test examples (#4289) # Objective - Several examples are useful for qualitative tests of Bevy's performance - By contrast, these are less useful for learning material: they are often relatively complex and have large amounts of setup and are performance optimized. ## Solution - Move bevymark, many_sprites and many_cubes into the new stress_tests example folder - Move contributors into the games folder: unlike the remaining examples in the 2d folder, it is not focused on demonstrating a clear feature.
2022-04-10 02:05:21 +00:00
[[example]]
name = "transform_hierarchy"
path = "examples/stress_tests/transform_hierarchy.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Group stress test examples (#4289) # Objective - Several examples are useful for qualitative tests of Bevy's performance - By contrast, these are less useful for learning material: they are often relatively complex and have large amounts of setup and are performance optimized. ## Solution - Move bevymark, many_sprites and many_cubes into the new stress_tests example folder - Move contributors into the games folder: unlike the remaining examples in the 2d folder, it is not focused on demonstrating a clear feature.
2022-04-10 02:05:21 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.transform_hierarchy]
name = "Transform Hierarchy"
description = "Various test cases for hierarchy and transform propagation performance"
category = "Stress Tests"
new example showcase tool (#8561) # Objective - Replace the `example_showcase.sh` script - Helper tool to prepare the example page on the website ## Solution - Have a command to run all the examples: `cargo run -p example-showcase -- run` - Have a command to take screenshots of all examples: `cargo run -p example-showcase -- run --screenshot` - Have a command to build the markdown files for the website: `cargo run -p example-showcase -- build-website-list --content-folder content` - Have a command to build all the examples in wasm/WebGPU: `cargo run -p example-showcase -- build-web-gpu-examples --content-folder webgpus` (with `--website-hacks` to enable the hacks for the Bevy website: canvas id, resizing and loading bar) This is the first step to an improved example page (all examples marked as wasm, uses the card layout, has screenshots, reuse name, category and description from the metadata). As one of the goal is to have a page with WebGPU examples before the official release, this is not touching the example page for now but targeting a new one. <img width="1912" alt="Screenshot 2023-05-06 at 17 16 25" src="https://user-images.githubusercontent.com/8672791/236632744-4372c95f-c50a-4168-973f-349412548f33.png">
2023-05-08 19:02:06 +00:00
wasm = false
add bevymark benchmark example (#273) add bevymark example
2020-11-13 02:03:57 +00:00
Text pipeline benchmark (#7845) # Objective Simple text pipeline benchmark. It's quite expensive but current examples don't capture the performance of `queue_text` as it only runs on changes to the text.
2023-03-04 12:29:08 +00:00
[[example]]
name = "text_pipeline"
path = "examples/stress_tests/text_pipeline.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Text pipeline benchmark (#7845) # Objective Simple text pipeline benchmark. It's quite expensive but current examples don't capture the performance of `queue_text` as it only runs on changes to the text.
2023-03-04 12:29:08 +00:00
[package.metadata.example.text_pipeline]
name = "Text Pipeline"
description = "Text Pipeline benchmark"
category = "Stress Tests"
wasm = false
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
# Tools
Add a scene viewer tool (#4183) # Objective - Allow quick and easy testing of scenes ## Solution - Add a `scene-viewer` tool based on `load_gltf`. - Run it with e.g. `cargo run --release --example scene_viewer --features jpeg -- ../some/path/assets/models/Sponza/glTF/Sponza.gltf#Scene0` - Configure the asset path as pointing to the repo root for convenience (paths specified relative to current working directory) - Copy over the camera controller from the `shadow_biases` example - Support toggling the light animation - Support toggling shadows - Support adjusting the directional light shadow projection (cascaded shadow maps will remove the need for this later) I don't want to do too much on it up-front. Rather we can add features over time as we need them.
2022-03-19 19:14:13 +00:00
[[example]]
name = "scene_viewer"
Organized scene_viewer into plugins for reuse and organization (#6936) # Objective This PR reorganizes majority of the scene viewer example into a module of plugins which then allows reuse of functionality among new or existing examples. In addition, this enables the scene viewer to be more succinct and showcase the distinct cases of camera control and scene control. This work is to support future work in organization and future examples. A more complicated 3D scene example has been requested by the community (#6551) which requests functionality currently included in scene_viewer, but previously inaccessible. The future example can now just utilize the two plugins created here. The existing example [animated_fox example] can utilize the scene creation and animation control functionality of `SceneViewerPlugin`. ## Solution - Created a `scene_viewer` module inside the `tools` example folder. - Created two plugins: `SceneViewerPlugin` (gltf scene loading, animation control, camera tracking control, light control) and `CameraControllerPlugin` (controllable camera). - Original `scene_viewer.rs` moved to `scene_viewer/main.rs` and now utilizes the two plugins.
2022-12-25 00:23:13 +00:00
path = "examples/tools/scene_viewer/main.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add a scene viewer tool (#4183) # Objective - Allow quick and easy testing of scenes ## Solution - Add a `scene-viewer` tool based on `load_gltf`. - Run it with e.g. `cargo run --release --example scene_viewer --features jpeg -- ../some/path/assets/models/Sponza/glTF/Sponza.gltf#Scene0` - Configure the asset path as pointing to the repo root for convenience (paths specified relative to current working directory) - Copy over the camera controller from the `shadow_biases` example - Support toggling the light animation - Support toggling shadows - Support adjusting the directional light shadow projection (cascaded shadow maps will remove the need for this later) I don't want to do too much on it up-front. Rather we can add features over time as we need them.
2022-03-19 19:14:13 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.scene_viewer]
name = "Scene Viewer"
description = "A simple way to view glTF models with Bevy. Just run `cargo run --release --example scene_viewer /path/to/model.gltf#Scene0`, replacing the path as appropriate. With no arguments it will load the FieldHelmet glTF model from the repository assets subdirectory"
category = "Tools"
wasm = true
Add a Gamepad Viewer tool to examples (#6074) # Objective Give folks an easy way to test their gamepad with bevy. ~~This is a lot of very boring code for an example. Maybe it belongs in the "tools" directory?~~ ## Solution https://user-images.githubusercontent.com/200550/191884342-ace213c0-b423-449a-9295-530cbceaa19e.mp4 ## Notes This has brought to light (to me, anyway) some fairly major issues with gamepads on the web. See: [WASM mappings (gilrs issue 107)](https://gitlab.com/gilrs-project/gilrs/-/issues/107) [Inaccurate value for trigger button of Xbox gamepad with WASM (gilrs issue 121)](https://gitlab.com/gilrs-project/gilrs/-/issues/121)
2022-09-24 13:21:01 +00:00
[[example]]
name = "gamepad_viewer"
path = "examples/tools/gamepad_viewer.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add a Gamepad Viewer tool to examples (#6074) # Objective Give folks an easy way to test their gamepad with bevy. ~~This is a lot of very boring code for an example. Maybe it belongs in the "tools" directory?~~ ## Solution https://user-images.githubusercontent.com/200550/191884342-ace213c0-b423-449a-9295-530cbceaa19e.mp4 ## Notes This has brought to light (to me, anyway) some fairly major issues with gamepads on the web. See: [WASM mappings (gilrs issue 107)](https://gitlab.com/gilrs-project/gilrs/-/issues/107) [Inaccurate value for trigger button of Xbox gamepad with WASM (gilrs issue 121)](https://gitlab.com/gilrs-project/gilrs/-/issues/121)
2022-09-24 13:21:01 +00:00
[package.metadata.example.gamepad_viewer]
name = "Gamepad Viewer"
description = "Shows a visualization of gamepad buttons, sticks, and triggers"
category = "Tools"
Fix gamepad viewer being marked as a non-wasm example (#9399) # Objective This example stopped being built for the website after the example-building was reworked in (https://github.com/bevyengine/bevy-website/issues/720 + #9168). This seems to have just been a mistake when defining this particular example's metadata. See https://github.com/bevyengine/bevy-website/issues/726 ## Solution Update its metadata to indicate that it works with wasm.
2023-08-09 21:06:16 +00:00
wasm = true
Add a Gamepad Viewer tool to examples (#6074) # Objective Give folks an easy way to test their gamepad with bevy. ~~This is a lot of very boring code for an example. Maybe it belongs in the "tools" directory?~~ ## Solution https://user-images.githubusercontent.com/200550/191884342-ace213c0-b423-449a-9295-530cbceaa19e.mp4 ## Notes This has brought to light (to me, anyway) some fairly major issues with gamepads on the web. See: [WASM mappings (gilrs issue 107)](https://gitlab.com/gilrs-project/gilrs/-/issues/107) [Inaccurate value for trigger button of Xbox gamepad with WASM (gilrs issue 121)](https://gitlab.com/gilrs-project/gilrs/-/issues/121)
2022-09-24 13:21:01 +00:00
Reduce internal system order ambiguities, and add an example explaining them (#7383) # Objective - Bevy should not have any "internal" execution order ambiguities. These clutter the output of user-facing error reporting, and can result in nasty, nondetermistic, very difficult to solve bugs. - Verifying this currently involves repeated non-trivial manual work. ## Solution - [x] add an example to quickly check this - ~~[ ] ensure that this example panics if there are any unresolved ambiguities~~ - ~~[ ] run the example in CI :smiling_imp:~~ There's one tricky ambiguity left, between UI and animation. I don't have the tools to fix this without system set configuration, so the remaining work is going to be left to #7267 or another PR after that. ``` 2023-01-27T18:38:42.989405Z INFO bevy_ecs::schedule::ambiguity_detection: Execution order ambiguities detected, you might want to add an explicit dependency relation between some of these systems: * Parallel systems: -- "bevy_animation::animation_player" and "bevy_ui::flex::flex_node_system" conflicts: ["bevy_transform::components::transform::Transform"] ``` ## Changelog Resolved internal execution order ambiguities for: 1. Transform propagation (ignored, we need smarter filter checking). 2. Gamepad processing (fixed). 3. bevy_winit's window handling (fixed). 4. Cascaded shadow maps and perspectives (fixed). Also fixed a desynchronized state bug that could occur when the `Window` component is removed and then added to the same entity in a single frame.
2023-01-31 01:47:00 +00:00
[[example]]
name = "nondeterministic_system_order"
path = "examples/ecs/nondeterministic_system_order.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Reduce internal system order ambiguities, and add an example explaining them (#7383) # Objective - Bevy should not have any "internal" execution order ambiguities. These clutter the output of user-facing error reporting, and can result in nasty, nondetermistic, very difficult to solve bugs. - Verifying this currently involves repeated non-trivial manual work. ## Solution - [x] add an example to quickly check this - ~~[ ] ensure that this example panics if there are any unresolved ambiguities~~ - ~~[ ] run the example in CI :smiling_imp:~~ There's one tricky ambiguity left, between UI and animation. I don't have the tools to fix this without system set configuration, so the remaining work is going to be left to #7267 or another PR after that. ``` 2023-01-27T18:38:42.989405Z INFO bevy_ecs::schedule::ambiguity_detection: Execution order ambiguities detected, you might want to add an explicit dependency relation between some of these systems: * Parallel systems: -- "bevy_animation::animation_player" and "bevy_ui::flex::flex_node_system" conflicts: ["bevy_transform::components::transform::Transform"] ``` ## Changelog Resolved internal execution order ambiguities for: 1. Transform propagation (ignored, we need smarter filter checking). 2. Gamepad processing (fixed). 3. bevy_winit's window handling (fixed). 4. Cascaded shadow maps and perspectives (fixed). Also fixed a desynchronized state bug that could occur when the `Window` component is removed and then added to the same entity in a single frame.
2023-01-31 01:47:00 +00:00
[package.metadata.example.nondeterministic_system_order]
name = "Nondeterministic System Order"
Minor typo fixup (#8405) # Objective Fix two small typos in example description
2023-04-16 16:55:47 +00:00
description = "Systems run in parallel, but their order isn't always deterministic. Here's how to detect and fix this."
Reduce internal system order ambiguities, and add an example explaining them (#7383) # Objective - Bevy should not have any "internal" execution order ambiguities. These clutter the output of user-facing error reporting, and can result in nasty, nondetermistic, very difficult to solve bugs. - Verifying this currently involves repeated non-trivial manual work. ## Solution - [x] add an example to quickly check this - ~~[ ] ensure that this example panics if there are any unresolved ambiguities~~ - ~~[ ] run the example in CI :smiling_imp:~~ There's one tricky ambiguity left, between UI and animation. I don't have the tools to fix this without system set configuration, so the remaining work is going to be left to #7267 or another PR after that. ``` 2023-01-27T18:38:42.989405Z INFO bevy_ecs::schedule::ambiguity_detection: Execution order ambiguities detected, you might want to add an explicit dependency relation between some of these systems: * Parallel systems: -- "bevy_animation::animation_player" and "bevy_ui::flex::flex_node_system" conflicts: ["bevy_transform::components::transform::Transform"] ``` ## Changelog Resolved internal execution order ambiguities for: 1. Transform propagation (ignored, we need smarter filter checking). 2. Gamepad processing (fixed). 3. bevy_winit's window handling (fixed). 4. Cascaded shadow maps and perspectives (fixed). Also fixed a desynchronized state bug that could occur when the `Window` component is removed and then added to the same entity in a single frame.
2023-01-31 01:47:00 +00:00
category = "ECS (Entity Component System)"
wasm = false
Generalised ECS reactivity with Observers (#10839) # Objective - Provide an expressive way to register dynamic behavior in response to ECS changes that is consistent with existing bevy types and traits as to provide a smooth user experience. - Provide a mechanism for immediate changes in response to events during command application in order to facilitate improved query caching on the path to relations. ## Solution - A new fundamental ECS construct, the `Observer`; inspired by flec's observers but adapted to better fit bevy's access patterns and rust's type system. --- ## Examples There are 3 main ways to register observers. The first is a "component observer" that looks like this: ```rust world.observe(|trigger: Trigger<OnAdd, Transform>, query: Query<&Transform>| { let transform = query.get(trigger.entity()).unwrap(); }); ``` The above code will spawn a new entity representing the observer that will run it's callback whenever the `Transform` component is added to an entity. This is a system-like function that supports dependency injection for all the standard bevy types: `Query`, `Res`, `Commands` etc. It also has a `Trigger` parameter that provides information about the trigger such as the target entity, and the event being triggered. Importantly these systems run during command application which is key for their future use to keep ECS internals up to date. There are similar events for `OnInsert` and `OnRemove`, and this will be expanded with things such as `ArchetypeCreated`, `TableEmpty` etc. in follow up PRs. Another way to register an observer is an "entity observer" that looks like this: ```rust world.entity_mut(entity).observe(|trigger: Trigger<Resize>| { // ... }); ``` Entity observers run whenever an event of their type is triggered targeting that specific entity. This type of observer will de-spawn itself if the entity (or entities) it is observing is ever de-spawned so as to not leave dangling observers. Entity observers can also be spawned from deferred contexts such as other observers, systems, or hooks using commands: ```rust commands.entity(entity).observe(|trigger: Trigger<Resize>| { // ... }); ``` Observers are not limited to in built event types, they can be used with any type that implements `Event` (which has been extended to implement Component). This means events can also carry data: ```rust #[derive(Event)] struct Resize { x: u32, y: u32 } commands.entity(entity).observe(|trigger: Trigger<Resize>, query: Query<&mut Size>| { let event = trigger.event(); // ... }); // Will trigger the observer when commands are applied. commands.trigger_targets(Resize { x: 10, y: 10 }, entity); ``` You can also trigger events that target more than one entity at a time: ```rust commands.trigger_targets(Resize { x: 10, y: 10 }, [e1, e2]); ``` Additionally, Observers don't _need_ entity targets: ```rust app.observe(|trigger: Trigger<Quit>| { }) commands.trigger(Quit); ``` In these cases, `trigger.entity()` will be a placeholder. Observers are actually just normal entities with an `ObserverState` and `Observer` component! The `observe()` functions above are just shorthand for: ```rust world.spawn(Observer::new(|trigger: Trigger<Resize>| {}); ``` This will spawn the `Observer` system and use an `on_add` hook to add the `ObserverState` component. Dynamic components and trigger types are also fully supported allowing for runtime defined trigger types. ## Possible Follow-ups 1. Deprecate `RemovedComponents`, observers should fulfill all use cases while being more flexible and performant. 2. Queries as entities: Swap queries to entities and begin using observers listening to archetype creation triggers to keep their caches in sync, this allows unification of `ObserverState` and `QueryState` as well as unlocking several API improvements for `Query` and the management of `QueryState`. 3. Trigger bubbling: For some UI use cases in particular users are likely to want some form of bubbling for entity observers, this is trivial to implement naively but ideally this includes an acceleration structure to cache hierarchy traversals. 4. All kinds of other in-built trigger types. 5. Optimization; in order to not bloat the complexity of the PR I have kept the implementation straightforward, there are several areas where performance can be improved. The focus for this PR is to get the behavior implemented and not incur a performance cost for users who don't use observers. I am leaving each of these to follow up PR's in order to keep each of them reviewable as this already includes significant changes. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: MiniaczQ <xnetroidpl@gmail.com> Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2024-06-15 01:33:26 +00:00
[[example]]
name = "observers"
path = "examples/ecs/observers.rs"
doc-scrape-examples = true
[package.metadata.example.observers]
name = "Observers"
description = "Demonstrates observers that react to events (both built-in life-cycle events and custom events)"
category = "ECS (Entity Component System)"
wasm = true
Minimal Bubbling Observers (#13991) # Objective Add basic bubbling to observers, modeled off `bevy_eventlistener`. ## Solution - Introduce a new `Traversal` trait for components which point to other entities. - Provide a default `TraverseNone: Traversal` component which cannot be constructed. - Implement `Traversal` for `Parent`. - The `Event` trait now has an associated `Traversal` which defaults to `TraverseNone`. - Added a field `bubbling: &mut bool` to `Trigger` which can be used to instruct the runner to bubble the event to the entity specified by the event's traversal type. - Added an associated constant `SHOULD_BUBBLE` to `Event` which configures the default bubbling state. - Added logic to wire this all up correctly. Introducing the new associated information directly on `Event` (instead of a new `BubblingEvent` trait) lets us dispatch both bubbling and non-bubbling events through the same api. ## Testing I have added several unit tests to cover the common bugs I identified during development. Running the unit tests should be enough to validate correctness. The changes effect unsafe portions of the code, but should not change any of the safety assertions. ## Changelog Observers can now bubble up the entity hierarchy! To create a bubbling event, change your `Derive(Event)` to something like the following: ```rust #[derive(Component)] struct MyEvent; impl Event for MyEvent { type Traverse = Parent; // This event will propagate up from child to parent. const AUTO_PROPAGATE: bool = true; // This event will propagate by default. } ``` You can dispatch a bubbling event using the normal `world.trigger_targets(MyEvent, entity)`. Halting an event mid-bubble can be done using `trigger.propagate(false)`. Events with `AUTO_PROPAGATE = false` will not propagate by default, but you can enable it using `trigger.propagate(true)`. If there are multiple observers attached to a target, they will all be triggered by bubbling. They all share a bubbling state, which can be accessed mutably using `trigger.propagation_mut()` (`trigger.propagate` is just sugar for this). You can choose to implement `Traversal` for your own types, if you want to bubble along a different structure than provided by `bevy_hierarchy`. Implementers must be careful never to produce loops, because this will cause bevy to hang. ## Migration Guide + Manual implementations of `Event` should add associated type `Traverse = TraverseNone` and associated constant `AUTO_PROPAGATE = false`; + `Trigger::new` has new field `propagation: &mut Propagation` which provides the bubbling state. + `ObserverRunner` now takes the same `&mut Propagation` as a final parameter. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Torstein Grindvik <52322338+torsteingrindvik@users.noreply.github.com> Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2024-07-15 13:39:41 +00:00
[[example]]
name = "observer_propagation"
path = "examples/ecs/observer_propagation.rs"
doc-scrape-examples = true
[package.metadata.example.observer_propagation]
name = "Observer Propagation"
description = "Demonstrates event propagation with observers"
category = "ECS (Entity Component System)"
wasm = true
Add examples for Transforms (#2441) # Add Transform Examples - Adding examples for moving/rotating entities (with its own section) to resolve #2400 I've stumbled upon this project and been fiddling around a little. Saw the issue and thought I might just add some examples for the proposed transformations. Mind to check if I got the gist correctly and suggest anything I can improve?
2022-03-15 05:49:49 +00:00
[[example]]
name = "3d_rotation"
path = "examples/transforms/3d_rotation.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add examples for Transforms (#2441) # Add Transform Examples - Adding examples for moving/rotating entities (with its own section) to resolve #2400 I've stumbled upon this project and been fiddling around a little. Saw the issue and thought I might just add some examples for the proposed transformations. Mind to check if I got the gist correctly and suggest anything I can improve?
2022-03-15 05:49:49 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.3d_rotation]
name = "3D Rotation"
description = "Illustrates how to (constantly) rotate an object around an axis"
Alignment API for Transforms (#12187) # Objective - Closes #11793 - Introduces a general API for aligning local coordinates of Transforms with given vectors. ## Solution - We introduce `Transform::align`, which allows a rotation to be specified by four pieces of alignment data, as explained by the documentation: ````rust /// Rotates this [`Transform`] so that the `main_axis` vector, reinterpreted in local coordinates, points /// in the given `main_direction`, while `secondary_axis` points towards `secondary_direction`. /// /// For example, if a spaceship model has its nose pointing in the X-direction in its own local coordinates /// and its dorsal fin pointing in the Y-direction, then `align(Vec3::X, v, Vec3::Y, w)` will make the spaceship's /// nose point in the direction of `v`, while the dorsal fin does its best to point in the direction `w`. /// /// More precisely, the [`Transform::rotation`] produced will be such that: /// * applying it to `main_axis` results in `main_direction` /// * applying it to `secondary_axis` produces a vector that lies in the half-plane generated by `main_direction` and /// `secondary_direction` (with positive contribution by `secondary_direction`) /// /// [`Transform::look_to`] is recovered, for instance, when `main_axis` is `Vec3::NEG_Z` (the [`Transform::forward`] /// direction in the default orientation) and `secondary_axis` is `Vec3::Y` (the [`Transform::up`] direction in the default /// orientation). (Failure cases may differ somewhat.) /// /// In some cases a rotation cannot be constructed. Another axis will be picked in those cases: /// * if `main_axis` or `main_direction` is zero, `Vec3::X` takes its place /// * if `secondary_axis` or `secondary_direction` is zero, `Vec3::Y` takes its place /// * if `main_axis` is parallel with `secondary_axis` or `main_direction` is parallel with `secondary_direction`, /// a rotation is constructed which takes `main_axis` to `main_direction` along a great circle, ignoring the secondary /// counterparts /// /// Example /// ``` /// # use bevy_math::{Vec3, Quat}; /// # use bevy_transform::components::Transform; /// let mut t1 = Transform::IDENTITY; /// let mut t2 = Transform::IDENTITY; /// t1.align(Vec3::ZERO, Vec3::Z, Vec3::ZERO, Vec3::X); /// t2.align(Vec3::X, Vec3::Z, Vec3::Y, Vec3::X); /// assert_eq!(t1.rotation, t2.rotation); /// /// t1.align(Vec3::X, Vec3::Z, Vec3::X, Vec3::Y); /// assert_eq!(t1.rotation, Quat::from_rotation_arc(Vec3::X, Vec3::Z)); /// ``` pub fn align( &mut self, main_axis: Vec3, main_direction: Vec3, secondary_axis: Vec3, secondary_direction: Vec3, ) { //... } ```` - We introduce `Transform::aligned_by`, the returning-Self version of `align`: ````rust pub fn aligned_by( mut self, main_axis: Vec3, main_direction: Vec3, secondary_axis: Vec3, secondary_direction: Vec3, ) -> Self { //... } ```` - We introduce an example (examples/transforms/align.rs) that shows the usage of this API. It is likely to be mathier than most other `Transform` APIs, so when run, the example demonstrates what the API does in space: <img width="1440" alt="Screenshot 2024-03-12 at 11 01 19 AM" src="https://github.com/bevyengine/bevy/assets/2975848/884b3cc3-cbd9-48ae-8f8c-49a677c59dfe"> --- ## Changelog - Added methods `align`, `aligned_by` to `Transform`. - Added transforms/align.rs to examples. --- ## Discussion ### On the form of `align` The original issue linked above suggests an API similar to that of the existing `Transform::look_to` method: ````rust pub fn align_to(&mut self, direction: Vec3, up: Vec3) { //... } ```` Not allowing an input axis of some sort that is to be aligned with `direction` would not really solve the problem in the issue, since the user could easily be in a scenario where they have to compose with another rotation on their own (undesirable). This leads to something like: ````rust pub fn align_to(&mut self, axis: Vec3, direction: Vec3, up: Vec3) { //... } ```` However, this still has two problems: - If the vector that the user wants to align is parallel to the Y-axis, then the API basically does not work (we cannot fully specify a rotation) - More generally, it does not give the user the freedom to specify which direction is to be treated as the local "up" direction, so it fails as a general alignment API Specifying both leads us to the present situation, with two local axis inputs (`main_axis` and `secondary_axis`) and two target directions (`main_direction` and `secondary_direction`). This might seem a little cumbersome for general use, but for the time being I stand by the decision not to expand further without prompting from users. I'll expand on this below. ### Additional APIs? Presently, this PR introduces only `align` and `aligned_by`. Other potentially useful bundles of API surface arrange into a few different categories: 1. Inferring direction from position, a la `Transform::look_at`, which might look something like this: ````rust pub fn align_at(&mut self, axis: Vec3, target: Vec3, up: Vec3) { self.align(axis, target - self.translation, Vec3::Y, up); } ```` (This is simple but still runs into issues when the user wants to point the local Y-axis somewhere.) 2. Filling in some data for the user for common use-cases; e.g.: ````rust pub fn align_x(&mut self, direction: Vec3, up: Vec3) { self.align(Vec3::X, direction, Vec3::Y, up); } ```` (Here, use of the `up` vector doesn't lose any generality, but it might be less convenient to specify than something else. This does naturally leave open the question of what `align_y` would look like if we provided it.) Morally speaking, I do think that the `up` business is more pertinent when the intention is to work with cameras, which the `look_at` and `look_to` APIs seem to cover pretty well. If that's the case, then I'm not sure what the ideal shape for these API functions would be, since it seems like a lot of input would have to be baked into the function definitions. For some cases, this might not be the end of the world: ````rust pub fn align_x_z(&mut self, direction: Vec3, weak_direction: Vec3) { self.align(Vec3::X, direction, Vec3::Z, weak_direction); } ```` (However, this is not symmetrical in x and z, so you'd still need six API functions just to support the standard positive coordinate axes, and if you support negative axes then things really start to balloon.) The reasons that these are not actually produced in this PR are as follows: 1. Without prompting from actual users in the wild, it is unknown to me whether these additional APIs would actually see a lot of use. Extending these to our users in the future would be trivial if we see there is a demand for something specific from the above-mentioned categories. 2. As discussed above, there are so many permutations of these that could be provided that trying to do so looks like it risks unduly ballooning the API surface for this feature. 3. Finally, and most importantly, creating these helper functions in user-space is trivial, since they all just involve specializing `align` to particular inputs; e.g.: ````rust fn align_ship(ship_transform: &mut Transform, nose_direction: Vec3, dorsal_direction: Vec3) { ship_transform.align(Ship::NOSE, nose_direction, Ship::DORSAL, dorsal_direction); } ```` With that in mind, I would prefer instead to focus on making the documentation and examples for a thin API as clear as possible, so that users can get a grip on the tool and specialize it for their own needs when they feel the desire to do so. ### `Dir3`? As in the case of `Transform::look_to` and `Transform::look_at`, the inputs to this function are, morally speaking, *directions* rather than vectors (actually, if we're being pedantic, the input is *really really* a pair of orthonormal frames), so it's worth asking whether we should really be using `Dir3` as inputs instead of `Vec3`. I opted for `Vec3` for the following reasons: 1. Specifying a `Dir3` in user-space is just more annoying than providing a `Vec3`. Even in the most basic cases (e.g. providing a vector literal), you still have to do error handling or call an unsafe unwrap in your function invocations. 2. The existing API mentioned above uses `Vec3`, so we are just adhering to the same thing. Of course, the use of `Vec3` has its own downsides; it can be argued that the replacement of zero-vectors with fixed ones (which we do in `Transform::align` as well as `Transform::look_to`) more-or-less amounts to failing silently. ### Future steps The question of additional APIs was addressed above. For me, the main thing here to handle more immediately is actually just upstreaming this API (or something similar and slightly mathier) to `glam::Quat`. The reason that this would be desirable for users is that this API currently only works with `Transform`s even though all it's actually doing is specifying a rotation. Upstreaming to `glam::Quat`, properly done, could buy a lot basically for free, since a number of `Transform` methods take a rotation as an input. Using these together would require a little bit of mathematical savvy, but it opens up some good things (e.g. `Transform::rotate_around`).
2024-03-14 14:55:55 +00:00
category = "Transforms"
wasm = true
[[example]]
name = "align"
path = "examples/transforms/align.rs"
doc-scrape-examples = true
[package.metadata.example.align]
name = "Alignment"
description = "A demonstration of Transform's axis-alignment feature"
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
category = "Transforms"
wasm = true
Add examples for Transforms (#2441) # Add Transform Examples - Adding examples for moving/rotating entities (with its own section) to resolve #2400 I've stumbled upon this project and been fiddling around a little. Saw the issue and thought I might just add some examples for the proposed transformations. Mind to check if I got the gist correctly and suggest anything I can improve?
2022-03-15 05:49:49 +00:00
[[example]]
name = "scale"
path = "examples/transforms/scale.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add examples for Transforms (#2441) # Add Transform Examples - Adding examples for moving/rotating entities (with its own section) to resolve #2400 I've stumbled upon this project and been fiddling around a little. Saw the issue and thought I might just add some examples for the proposed transformations. Mind to check if I got the gist correctly and suggest anything I can improve?
2022-03-15 05:49:49 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.scale]
name = "Scale"
description = "Illustrates how to scale an object in each direction"
category = "Transforms"
wasm = true
Add examples for Transforms (#2441) # Add Transform Examples - Adding examples for moving/rotating entities (with its own section) to resolve #2400 I've stumbled upon this project and been fiddling around a little. Saw the issue and thought I might just add some examples for the proposed transformations. Mind to check if I got the gist correctly and suggest anything I can improve?
2022-03-15 05:49:49 +00:00
[[example]]
name = "transform"
path = "examples/transforms/transform.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add examples for Transforms (#2441) # Add Transform Examples - Adding examples for moving/rotating entities (with its own section) to resolve #2400 I've stumbled upon this project and been fiddling around a little. Saw the issue and thought I might just add some examples for the proposed transformations. Mind to check if I got the gist correctly and suggest anything I can improve?
2022-03-15 05:49:49 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.transform]
name = "Transform"
description = "Shows multiple transformations of objects"
category = "Transforms"
wasm = true
Add examples for Transforms (#2441) # Add Transform Examples - Adding examples for moving/rotating entities (with its own section) to resolve #2400 I've stumbled upon this project and been fiddling around a little. Saw the issue and thought I might just add some examples for the proposed transformations. Mind to check if I got the gist correctly and suggest anything I can improve?
2022-03-15 05:49:49 +00:00
[[example]]
name = "translation"
path = "examples/transforms/translation.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add examples for Transforms (#2441) # Add Transform Examples - Adding examples for moving/rotating entities (with its own section) to resolve #2400 I've stumbled upon this project and been fiddling around a little. Saw the issue and thought I might just add some examples for the proposed transformations. Mind to check if I got the gist correctly and suggest anything I can improve?
2022-03-15 05:49:49 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.translation]
name = "Translation"
description = "Illustrates how to move an object along an axis"
category = "Transforms"
wasm = true
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
# UI (User Interface)
Ui Node Borders (#7795) # Objective Implement borders for UI nodes. Relevant discussion: #7785 Related: #5924, #3991 <img width="283" alt="borders" src="https://user-images.githubusercontent.com/27962798/220968899-7661d5ec-6f5b-4b0f-af29-bf9af02259b5.PNG"> ## Solution Add an extraction function to draw the borders. --- Can only do one colour rectangular borders due to the limitations of the Bevy UI renderer. Maybe it can be combined with #3991 eventually to add curved border support. ## Changelog * Added a component `BorderColor`. * Added the `extract_uinode_borders` system to the UI Render App. * Added the UI example `borders` --------- Co-authored-by: Nico Burns <nico@nicoburns.com>
2023-06-14 22:43:38 +00:00
[[example]]
name = "borders"
path = "examples/ui/borders.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Ui Node Borders (#7795) # Objective Implement borders for UI nodes. Relevant discussion: #7785 Related: #5924, #3991 <img width="283" alt="borders" src="https://user-images.githubusercontent.com/27962798/220968899-7661d5ec-6f5b-4b0f-af29-bf9af02259b5.PNG"> ## Solution Add an extraction function to draw the borders. --- Can only do one colour rectangular borders due to the limitations of the Bevy UI renderer. Maybe it can be combined with #3991 eventually to add curved border support. ## Changelog * Added a component `BorderColor`. * Added the `extract_uinode_borders` system to the UI Render App. * Added the UI example `borders` --------- Co-authored-by: Nico Burns <nico@nicoburns.com>
2023-06-14 22:43:38 +00:00
[package.metadata.example.borders]
name = "Borders"
description = "Demonstrates how to create a node with a border"
Add border radius to UI nodes (adopted) (#12500) # Objective Implements border radius for UI nodes. Adopted from #8973, but excludes shadows. ## Solution - Add a component `BorderRadius` which contains a radius value for each corner of the UI node. - Use a fragment shader to generate the rounded corners using a signed distance function. <img width="50%" src="https://github.com/bevyengine/bevy/assets/26204416/16b2ba95-e274-4ce7-adb2-34cc41a776a5"></img> ## Changelog - `BorderRadius`: New component that holds the border radius values. - `NodeBundle` & `ButtonBundle`: Added a `border_radius: BorderRadius` field. - `extract_uinode_borders`: Stripped down, most of the work is done in the shader now. Borders are no longer assembled from multiple rects, instead the shader uses a signed distance function to draw the border. - `UiVertex`: Added size, border and radius fields. - `UiPipeline`: Added three vertex attributes to the vertex buffer layout, to accept the UI node's size, border thickness and border radius. - Examples: Added rounded corners to the UI element in the `button` example, and a `rounded_borders` example. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Zachary Harrold <zac@harrold.com.au> Co-authored-by: Pablo Reinhardt <126117294+pablo-lua@users.noreply.github.com>
2024-03-19 22:44:00 +00:00
category = "UI (User Interface)"
wasm = true
box shadow (#15204) # Objective UI box shadow support Adds a new component `BoxShadow`: ```rust pub struct BoxShadow { /// The shadow's color pub color: Color, /// Horizontal offset pub x_offset: Val, /// Vertical offset pub y_offset: Val, /// Horizontal difference in size from the occluding uninode pub spread_radius: Val, /// Blurriness of the shadow pub blur_radius: Val, } ``` To use `BoxShadow`, add the component to any Bevy UI node and a shadow will be drawn beneath that node. Also adds a resource `BoxShadowSamples` that can be used to adjust the shadow quality. #### Notes * I'm not super happy with the field names. Maybe we need a `struct Size { width: Val, height: Val }` type or something. * The shader isn't very optimised but I don't see that it's too important for now as the number of shadows being rendered is not going to be massive most of the time. I think it's more important to get the API and geometry correct with this PR. * I didn't implement an inset property, it's not essential and can easily be added in a follow up. * Shadows are only rendered for uinodes, not for images or text. * Batching isn't supported, it would need out-of-the-scope-of-this-pr changes to the way the UI handles z-ordering for it to be effective. # Showcase ```cargo run --example box_shadow -- --samples 4``` <img width="391" alt="br" src="https://github.com/user-attachments/assets/4e8add96-dc93-46e0-9e35-d995eb0943ad"> ```cargo run --example box_shadow -- --samples 10``` <img width="391" alt="s10" src="https://github.com/user-attachments/assets/ecb384c9-4012-4cd6-9dea-5180904bf28e">
2024-10-08 16:26:17 +00:00
[[example]]
name = "box_shadow"
path = "examples/ui/box_shadow.rs"
doc-scrape-examples = true
[package.metadata.example.box_shadow]
name = "Box Shadow"
description = "Demonstrates how to create a node with a shadow"
category = "UI (User Interface)"
wasm = true
ui: focus/click/hover system. initial buttons
2020-07-18 21:08:46 +00:00
[[example]]
name = "button"
path = "examples/ui/button.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
ui: focus/click/hover system. initial buttons
2020-07-18 21:08:46 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.button]
name = "Button"
description = "Illustrates creating and updating a button"
category = "UI (User Interface)"
wasm = true
UI Display and Visibility Example (#7629) # Objective An example demonstrating how Display and Visibility work in Bevy UI. fixes #5380 related #5368 ![Bevy App 15_02_2023 20_40_46](https://user-images.githubusercontent.com/27962798/219150865-419ade53-250b-4030-8197-907cac7aa5da.png) ## Changelog * Added the example `flex_display.rs`.
2023-06-19 23:19:34 +00:00
[[example]]
name = "display_and_visibility"
path = "examples/ui/display_and_visibility.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
UI Display and Visibility Example (#7629) # Objective An example demonstrating how Display and Visibility work in Bevy UI. fixes #5380 related #5368 ![Bevy App 15_02_2023 20_40_46](https://user-images.githubusercontent.com/27962798/219150865-419ade53-250b-4030-8197-907cac7aa5da.png) ## Changelog * Added the example `flex_display.rs`.
2023-06-19 23:19:34 +00:00
[package.metadata.example.display_and_visibility]
name = "Display and Visibility"
description = "Demonstrates how Display and Visibility work in the UI."
category = "UI (User Interface)"
wasm = true
Expose set_cursor_hittest() from winit (#6664) # Objective - Bevy should be usable to create 'overlay' type apps, where the input is not captured by Bevy, but passed down/into a target app, or to allow passive displays/widgets etc. ## Solution - the `winit::window::Window` already has a `set_cursor_hittest()` which basically does this for mouse input events, so I've exposed it (trying to copy the style laid out in the existing wrappings, and added a simple demo. --- ## Changelog - Added `hittest` to `WindowAttributes` - Added the `hittest`'s setters/getters - Modified the `WindowBuilder` - Modifed the `WindowDescriptor`'s `Default` impl. - Added an example `cargo run --example fallthrough`
2022-11-21 12:59:10 +00:00
[[example]]
name = "window_fallthrough"
path = "examples/ui/window_fallthrough.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Expose set_cursor_hittest() from winit (#6664) # Objective - Bevy should be usable to create 'overlay' type apps, where the input is not captured by Bevy, but passed down/into a target app, or to allow passive displays/widgets etc. ## Solution - the `winit::window::Window` already has a `set_cursor_hittest()` which basically does this for mouse input events, so I've exposed it (trying to copy the style laid out in the existing wrappings, and added a simple demo. --- ## Changelog - Added `hittest` to `WindowAttributes` - Added the `hittest`'s setters/getters - Modified the `WindowBuilder` - Modifed the `WindowDescriptor`'s `Default` impl. - Added an example `cargo run --example fallthrough`
2022-11-21 12:59:10 +00:00
[package.metadata.example.window_fallthrough]
name = "Window Fallthrough"
description = "Illustrates how to access `winit::window::Window`'s `hittest` functionality."
category = "UI (User Interface)"
wasm = false
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
[[example]]
name = "font_atlas_debug"
path = "examples/ui/font_atlas_debug.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.font_atlas_debug]
name = "Font Atlas Debug"
description = "Illustrates how FontAtlases are populated (used to optimize text rendering internally)"
category = "UI (User Interface)"
wasm = true
Split UI `Overflow` by axis (#8095) # Objective Split the UI overflow enum so that overflow can be set for each axis separately. ## Solution Change `Overflow` from an enum to a struct with `x` and `y` `OverflowAxis` fields, where `OverflowAxis` is an enum with `Clip` and `Visible` variants. Modify `update_clipping` to calculate clipping for each axis separately. If only one axis is clipped, the other axis is given infinite bounds. <img width="642" alt="overflow" src="https://user-images.githubusercontent.com/27962798/227592983-568cf76f-7e40-48c4-a511-43c886f5e431.PNG"> --- ## Changelog * Split the UI overflow implementation so overflow can be set for each axis separately. * Added the enum `OverflowAxis` with `Clip` and `Visible` variants. * Changed `Overflow` to a struct with `x` and `y` fields of type `OverflowAxis`. * `Overflow` has new methods `visible()` and `hidden()` that replace its previous `Clip` and `Visible` variants. * Added `Overflow` helper methods `clip_x()` and `clip_y()` that return a new `Overflow` value with the given axis clipped. * Modified `update_clipping` so it calculates clipping for each axis separately. If a node is only clipped on a single axis, the other axis is given `-f32::INFINITY` to `f32::INFINITY` clipping bounds. ## Migration Guide The `Style` property `Overflow` is now a struct with `x` and `y` fields, that allow for per-axis overflow control. Use these helper functions to replace the variants of `Overflow`: * Replace `Overflow::Visible` with `Overflow::visible()` * Replace `Overflow::Hidden` with `Overflow::clip()`
2023-04-17 22:23:52 +00:00
[[example]]
name = "overflow"
path = "examples/ui/overflow.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Split UI `Overflow` by axis (#8095) # Objective Split the UI overflow enum so that overflow can be set for each axis separately. ## Solution Change `Overflow` from an enum to a struct with `x` and `y` `OverflowAxis` fields, where `OverflowAxis` is an enum with `Clip` and `Visible` variants. Modify `update_clipping` to calculate clipping for each axis separately. If only one axis is clipped, the other axis is given infinite bounds. <img width="642" alt="overflow" src="https://user-images.githubusercontent.com/27962798/227592983-568cf76f-7e40-48c4-a511-43c886f5e431.PNG"> --- ## Changelog * Split the UI overflow implementation so overflow can be set for each axis separately. * Added the enum `OverflowAxis` with `Clip` and `Visible` variants. * Changed `Overflow` to a struct with `x` and `y` fields of type `OverflowAxis`. * `Overflow` has new methods `visible()` and `hidden()` that replace its previous `Clip` and `Visible` variants. * Added `Overflow` helper methods `clip_x()` and `clip_y()` that return a new `Overflow` value with the given axis clipped. * Modified `update_clipping` so it calculates clipping for each axis separately. If a node is only clipped on a single axis, the other axis is given `-f32::INFINITY` to `f32::INFINITY` clipping bounds. ## Migration Guide The `Style` property `Overflow` is now a struct with `x` and `y` fields, that allow for per-axis overflow control. Use these helper functions to replace the variants of `Overflow`: * Replace `Overflow::Visible` with `Overflow::visible()` * Replace `Overflow::Hidden` with `Overflow::clip()`
2023-04-17 22:23:52 +00:00
[package.metadata.example.overflow]
name = "Overflow"
description = "Simple example demonstrating overflow behavior"
category = "UI (User Interface)"
wasm = true
Overflow clip margin (#15561) # Objective Limited implementation of the CSS property `overflow-clip-margin` https://developer.mozilla.org/en-US/docs/Web/CSS/overflow-clip-margin Allows you to control the visible area for clipped content when using overfllow-clip, -hidden, or -scroll and expand it with a margin. Based on #15442 Fixes #15468 ## Solution Adds a new field to Style: `overflow_clip_margin: OverflowClipMargin`. The field is ignored unless overflow-clip, -hidden or -scroll is set on at least one axis. `OverflowClipMargin` has these associated constructor functions: ``` pub const fn content_box() -> Self; pub const fn padding_box() -> Self; pub const fn border_box() -> Self; ``` You can also use the method `with_margin` to increases the size of the visible area: ``` commands .spawn(NodeBundle { style: Style { width: Val::Px(100.), height: Val::Px(100.), padding: UiRect::all(Val::Px(20.)), border: UiRect::all(Val::Px(5.)), overflow: Overflow::clip(), overflow_clip_margin: OverflowClipMargin::border_box().with_margin(25.), ..Default::default() }, border_color: Color::BLACK.into(), background_color: GRAY.into(), ..Default::default() }) ``` `with_margin` expects a length in logical pixels, negative values are clamped to zero. ## Notes * To keep this PR as simple as possible I omitted responsive margin values support. This could be added in a follow up if we want it. * CSS also supports a `margin-box` option but we don't have access to the margin values in `Node` so it's probably not feasible to implement atm. ## Testing ```cargo run --example overflow_clip_margin``` <img width="396" alt="overflow-clip-margin" src="https://github.com/user-attachments/assets/07b51cd6-a565-4451-87a0-fa079429b04b"> ## Migration Guide Style has a new field `OverflowClipMargin`. It allows users to set the visible area for clipped content when using overflow-clip, -hidden, or -scroll and expand it with a margin. There are three associated constructor functions `content_box`, `padding_box` and `border_box`: * `content_box`: elements painted outside of the content box area (the innermost part of the node excluding the padding and border) of the node are clipped. This is the new default behaviour. * `padding_box`: elements painted outside outside of the padding area of the node are clipped. * `border_box`: elements painted outside of the bounds of the node are clipped. This matches the behaviour from Bevy 0.14. There is also a `with_margin` method that increases the size of the visible area by the given number in logical pixels, negative margin values are clamped to zero. `OverflowClipMargin` is ignored unless overflow-clip, -hidden or -scroll is also set on at least one axis of the UI node. --------- Co-authored-by: UkoeHB <37489173+UkoeHB@users.noreply.github.com>
2024-10-16 13:17:49 +00:00
[[example]]
name = "overflow_clip_margin"
path = "examples/ui/overflow_clip_margin.rs"
doc-scrape-examples = true
[package.metadata.example.overflow_clip_margin]
name = "Overflow Clip Margin"
description = "Simple example demonstrating the OverflowClipMargin style property"
category = "UI (User Interface)"
wasm = true
Add `overflow_debug` example (#8198) # Objective - Add a new example that helps debug different UI overflow scenarios - This example tests the clipping behavior for images and text when the node is moved, scaled or rotated. ## Solution - Add a new `overflow_debug` example # Preview **Note:** Only top-left is working properly right now. https://user-images.githubusercontent.com/188612/227629093-26c94c67-1781-437d-8410-e854b6f1adc1.mp4 --- Related #8095, #8167 --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com> Co-authored-by: ickshonpe <david.curthoys@googlemail.com>
2023-04-05 23:07:41 +00:00
[[example]]
name = "overflow_debug"
path = "examples/ui/overflow_debug.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add `overflow_debug` example (#8198) # Objective - Add a new example that helps debug different UI overflow scenarios - This example tests the clipping behavior for images and text when the node is moved, scaled or rotated. ## Solution - Add a new `overflow_debug` example # Preview **Note:** Only top-left is working properly right now. https://user-images.githubusercontent.com/188612/227629093-26c94c67-1781-437d-8410-e854b6f1adc1.mp4 --- Related #8095, #8167 --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com> Co-authored-by: ickshonpe <david.curthoys@googlemail.com>
2023-04-05 23:07:41 +00:00
[package.metadata.example.overflow_debug]
name = "Overflow and Clipping Debug"
description = "An example to debug overflow and clipping behavior"
category = "UI (User Interface)"
wasm = true
Relative cursor position (#7199) # Objective Add useful information about cursor position relative to a UI node. Fixes #7079. ## Solution - Added a new `RelativeCursorPosition` component --- ## Changelog - Added - `RelativeCursorPosition` - an example showcasing the new component Co-authored-by: Dawid Piotrowski <41804418+Pietrek14@users.noreply.github.com>
2023-01-16 17:17:45 +00:00
[[example]]
name = "relative_cursor_position"
path = "examples/ui/relative_cursor_position.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Relative cursor position (#7199) # Objective Add useful information about cursor position relative to a UI node. Fixes #7079. ## Solution - Added a new `RelativeCursorPosition` component --- ## Changelog - Added - `RelativeCursorPosition` - an example showcasing the new component Co-authored-by: Dawid Piotrowski <41804418+Pietrek14@users.noreply.github.com>
2023-01-16 17:17:45 +00:00
[package.metadata.example.relative_cursor_position]
name = "Relative Cursor Position"
description = "Showcases the RelativeCursorPosition component"
category = "UI (User Interface)"
wasm = true
Camera-driven UI (#10559) # Objective Add support for presenting each UI tree on a specific window and viewport, while making as few breaking changes as possible. This PR is meant to resolve the following issues at once, since they're all related. - Fixes #5622 - Fixes #5570 - Fixes #5621 Adopted #5892 , but started over since the current codebase diverged significantly from the original PR branch. Also, I made a decision to propagate component to children instead of recursively iterating over nodes in search for the root. ## Solution Add a new optional component that can be inserted to UI root nodes and propagate to children to specify which camera it should render onto. This is then used to get the render target and the viewport for that UI tree. Since this component is optional, the default behavior should be to render onto the single camera (if only one exist) and warn of ambiguity if multiple cameras exist. This reduces the complexity for users with just one camera, while giving control in contexts where it matters. ## Changelog - Adds `TargetCamera(Entity)` component to specify which camera should a node tree be rendered into. If only one camera exists, this component is optional. - Adds an example of rendering UI to a texture and using it as a material in a 3D world. - Fixes recalculation of physical viewport size when target scale factor changes. This can happen when the window is moved between displays with different DPI. - Changes examples to demonstrate assigning UI to different viewports and windows and make interactions in an offset viewport testable. - Removes `UiCameraConfig`. UI visibility now can be controlled via combination of explicit `TargetCamera` and `Visibility` on the root nodes. --------- Co-authored-by: davier <bricedavier@gmail.com> Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Alice Cecile <alice.i.cecil@gmail.com>
2024-01-16 00:39:10 +00:00
[[example]]
name = "render_ui_to_texture"
path = "examples/ui/render_ui_to_texture.rs"
doc-scrape-examples = true
[package.metadata.example.render_ui_to_texture]
name = "Render UI to Texture"
description = "An example of rendering UI as a part of a 3D world"
category = "UI (User Interface)"
wasm = true
Size Constraints Example (#7956) # Objective Add a simple example demonstrating how to use size constraints. Related to #7946 # Solution <img width="827" alt="Capture" src="https://user-images.githubusercontent.com/27962798/223741566-4b8eca99-c450-42b5-a40e-a414858c8310.PNG"> # Changelog * Added the example `size_constraints`
2023-04-24 14:28:00 +00:00
[[example]]
name = "size_constraints"
path = "examples/ui/size_constraints.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Size Constraints Example (#7956) # Objective Add a simple example demonstrating how to use size constraints. Related to #7946 # Solution <img width="827" alt="Capture" src="https://user-images.githubusercontent.com/27962798/223741566-4b8eca99-c450-42b5-a40e-a414858c8310.PNG"> # Changelog * Added the example `size_constraints`
2023-04-24 14:28:00 +00:00
[package.metadata.example.size_constraints]
name = "Size Constraints"
description = "Demonstrates how the to use the size constraints to control the size of a UI node."
category = "UI (User Interface)"
wasm = true
initial text rendering
2020-05-13 20:09:32 +00:00
[[example]]
name = "text"
path = "examples/ui/text.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
initial text rendering
2020-05-13 20:09:32 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.text]
name = "Text"
description = "Illustrates creating and updating text"
category = "UI (User Interface)"
wasm = true
Use glyph_brush_layout and add text alignment support (#765) Use glyph_brush_layout and add text alignment support Co-authored-by: Olivier Pinon <op@impero.com> Co-authored-by: tigregalis <anak.harimau@gmail.com> Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2020-11-13 00:21:48 +00:00
[[example]]
name = "text_debug"
path = "examples/ui/text_debug.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Use glyph_brush_layout and add text alignment support (#765) Use glyph_brush_layout and add text alignment support Co-authored-by: Olivier Pinon <op@impero.com> Co-authored-by: tigregalis <anak.harimau@gmail.com> Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2020-11-13 00:21:48 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.text_debug]
name = "Text Debug"
description = "An example for debugging text layout"
category = "UI (User Interface)"
wasm = true
UI text layout example (#7359) ## Objective An example that demonstrates how the `AlignItems` and `JustifyContent` properties can be composed to layout text. <img width="654" alt="text_layout_example" src="https://user-images.githubusercontent.com/27962798/215116345-daa8ef60-634b-40c6-9b6d-356de3af620c.png">
2023-01-27 19:07:48 +00:00
[[example]]
Rename `text_layout` example to `flex_layout` (#7943) # Objective - Rename `text_layout` example to `flex_layout` to better reflect the example purpose - `AlignItems`/`JustifyContent` is not related to text layout, it's about child nodes positioning ## Solution - Rename the example --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2023-03-22 08:22:56 +00:00
name = "flex_layout"
path = "examples/ui/flex_layout.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
UI text layout example (#7359) ## Objective An example that demonstrates how the `AlignItems` and `JustifyContent` properties can be composed to layout text. <img width="654" alt="text_layout_example" src="https://user-images.githubusercontent.com/27962798/215116345-daa8ef60-634b-40c6-9b6d-356de3af620c.png">
2023-01-27 19:07:48 +00:00
Rename `text_layout` example to `flex_layout` (#7943) # Objective - Rename `text_layout` example to `flex_layout` to better reflect the example purpose - `AlignItems`/`JustifyContent` is not related to text layout, it's about child nodes positioning ## Solution - Rename the example --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2023-03-22 08:22:56 +00:00
[package.metadata.example.flex_layout]
name = "Flex Layout"
description = "Demonstrates how the AlignItems and JustifyContent properties can be composed to layout nodes and position text"
UI text layout example (#7359) ## Objective An example that demonstrates how the `AlignItems` and `JustifyContent` properties can be composed to layout text. <img width="654" alt="text_layout_example" src="https://user-images.githubusercontent.com/27962798/215116345-daa8ef60-634b-40c6-9b6d-356de3af620c.png">
2023-01-27 19:07:48 +00:00
category = "UI (User Interface)"
Add CSS Grid support to `bevy_ui` (#8026) # Objective An easy way to create 2D grid layouts ## Solution Enable the `grid` feature in Taffy and add new style types for defining grids. ## Notes - ~I'm having a bit of trouble getting `#[derive(Reflect)]` to work properly. Help with that would be appreciated (EDIT: got it to compile by ignoring the problematic fields, but this presumably can't be merged).~ This is now fixed - ~The alignment types now have a `Normal` variant because I couldn't get reflect to work with `Option`.~ I've decided to stick with the flattened variant, as it saves a level of wrapping when authoring styles. But I've renamed the variants from `Normal` to `Default`. - ~This currently exposes a simplified API on top of grid. In particular the following is not currently supported:~ - ~Negative grid indices~ Now supported. - ~Custom `end` values for grid placement (you can only use `start` and `span`)~ Now supported - ~`minmax()` track sizing functions~ minmax is now support through a `GridTrack::minmax()` constructor - ~`repeat()`~ repeat is now implemented as `RepeatedGridTrack` - ~Documentation still needs to be improved.~ An initial pass over the documentation has been completed. ## Screenshot <img width="846" alt="Screenshot 2023-03-10 at 17 56 21" src="https://user-images.githubusercontent.com/1007307/224435332-69aa9eac-123d-4856-b75d-5449d3f1d426.png"> --- ## Changelog - Support for CSS Grid layout added to `bevy_ui` --------- Co-authored-by: Rob Parrett <robparrett@gmail.com> Co-authored-by: Andreas Weibye <13300393+Weibye@users.noreply.github.com>
2023-04-17 16:21:38 +00:00
wasm = true
UI text wrapping and `LineBreakOn` example (#7761) # Objective An example demonstrating more text layout options, text wrapping and `LineBreakOn`. <img width="961" alt="text_wrap" src="https://user-images.githubusercontent.com/27962798/220125391-48163d28-51d9-4df5-b34a-f95ca3661b7d.PNG"> Won't look exactly like this on main because of the remaining bugs in text. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2023-04-24 14:22:31 +00:00
[[example]]
name = "text_wrap_debug"
path = "examples/ui/text_wrap_debug.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
UI text wrapping and `LineBreakOn` example (#7761) # Objective An example demonstrating more text layout options, text wrapping and `LineBreakOn`. <img width="961" alt="text_wrap" src="https://user-images.githubusercontent.com/27962798/220125391-48163d28-51d9-4df5-b34a-f95ca3661b7d.PNG"> Won't look exactly like this on main because of the remaining bugs in text. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2023-04-24 14:22:31 +00:00
[package.metadata.example.text_wrap_debug]
name = "Text Wrap Debug"
description = "Demonstrates text wrapping"
category = "UI (User Interface)"
wasm = true
Add UI `GhostNode` (#15341) # Objective - Fixes #14826 - For context, see #15238 ## Solution Add a `GhostNode` component to `bevy_ui` and update all the relevant systems to use it to traverse for UI children. - [x] `ghost_hierarchy` module - [x] Add `GhostNode` - [x] Add `UiRootNodes` system param for iterating (ghost-aware) UI root nodes - [x] Add `UiChildren` system param for iterating (ghost-aware) UI children - [x] Update `layout::ui_layout_system` - [x] Use ghost-aware root nodes for camera updates - [x] Update and remove children in taffy - [x] Initial spawn - [x] Detect changes on nested UI children - [x] Use ghost-aware children traversal in `update_uinode_geometry_recursive` - [x] Update the rest of the UI systems to use the ghost hierarchy - [x] `stack::ui_stack_system` - [x] `update::` - [x] `update_clipping_system` - [x] `update_target_camera_system` - [x] `accessibility::calc_name` ## Testing - [x] Added a new example `ghost_nodes` that can be used as a testbed. - [x] Added unit tests for _some_ of the traversal utilities in `ghost_hierarchy` - [x] Ensure this fulfills the needs for currently known use cases - [x] Reactivity libraries (test with `bevy_reactor`) - [ ] Text spans (mentioned by koe [on discord](https://discord.com/channels/691052431525675048/1285371432460881991/1285377442998915246)) --- ## Performance [See comment below](https://github.com/bevyengine/bevy/pull/15341#issuecomment-2385456820) ## Migration guide Any code that previously relied on `Parent`/`Children` to iterate UI children may now want to use `bevy_ui::UiChildren` to ensure ghost nodes are skipped, and their first descendant Nodes included. UI root nodes may now be children of ghost nodes, which means `Without<Parent>` might not query all root nodes. Use `bevy_ui::UiRootNodes` where needed to iterate root nodes instead. ## Potential future work - Benchmarking/optimizations of hierarchies containing lots of ghost nodes - Further exploration of UI hierarchies and markers for root nodes/leaf nodes to create better ergonomics for things like `UiLayer` (world-space ui) --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: UkoeHB <37489173+UkoeHB@users.noreply.github.com>
2024-10-02 00:24:28 +00:00
[[example]]
name = "ghost_nodes"
path = "examples/ui/ghost_nodes.rs"
doc-scrape-examples = true
Mark ghost nodes as experimental and partially feature flag them (#15961) # Objective As discussed in #15341, ghost nodes are a contentious and experimental feature. In the interest of enabling ecosystem experimentation, we've decided to keep them in Bevy 0.15. That said, we don't use them internally, and don't expect third-party crates to support them. If the experimentation returns a negative result (they aren't very useful, an alternative design is preferred etc) they will be removed. We should clearly communicate this status to users, and make sure that users don't use ghost nodes in their projects without a very clear understanding of what they're getting themselves into. ## Solution To make life easy for users (and Bevy), `GhostNode` and all associated helpers remain public and are always available. However, actually constructing these requires enabling a feature flag that's clearly marked as experimental. To do so, I've added a meaningless private field. When the feature flag is enabled, our constructs (`new` and `default`) can be used. I've added a `new` constructor, which should be preferred over `Default::default` as that can be readily deprecated, allowing us to prompt users to swap over to the much nicer `GhostNode` syntax once this is a unit struct again. Full credit: this was mostly @cart's design: I'm just implementing it! ## Testing I've run the ghost_nodes example and it fails to compile without the feature flag. With the feature flag, it works fine :) --------- Co-authored-by: Zachary Harrold <zac@harrold.com.au>
2024-10-16 22:20:48 +00:00
required-features = ["ghost_nodes"]
Add UI `GhostNode` (#15341) # Objective - Fixes #14826 - For context, see #15238 ## Solution Add a `GhostNode` component to `bevy_ui` and update all the relevant systems to use it to traverse for UI children. - [x] `ghost_hierarchy` module - [x] Add `GhostNode` - [x] Add `UiRootNodes` system param for iterating (ghost-aware) UI root nodes - [x] Add `UiChildren` system param for iterating (ghost-aware) UI children - [x] Update `layout::ui_layout_system` - [x] Use ghost-aware root nodes for camera updates - [x] Update and remove children in taffy - [x] Initial spawn - [x] Detect changes on nested UI children - [x] Use ghost-aware children traversal in `update_uinode_geometry_recursive` - [x] Update the rest of the UI systems to use the ghost hierarchy - [x] `stack::ui_stack_system` - [x] `update::` - [x] `update_clipping_system` - [x] `update_target_camera_system` - [x] `accessibility::calc_name` ## Testing - [x] Added a new example `ghost_nodes` that can be used as a testbed. - [x] Added unit tests for _some_ of the traversal utilities in `ghost_hierarchy` - [x] Ensure this fulfills the needs for currently known use cases - [x] Reactivity libraries (test with `bevy_reactor`) - [ ] Text spans (mentioned by koe [on discord](https://discord.com/channels/691052431525675048/1285371432460881991/1285377442998915246)) --- ## Performance [See comment below](https://github.com/bevyengine/bevy/pull/15341#issuecomment-2385456820) ## Migration guide Any code that previously relied on `Parent`/`Children` to iterate UI children may now want to use `bevy_ui::UiChildren` to ensure ghost nodes are skipped, and their first descendant Nodes included. UI root nodes may now be children of ghost nodes, which means `Without<Parent>` might not query all root nodes. Use `bevy_ui::UiRootNodes` where needed to iterate root nodes instead. ## Potential future work - Benchmarking/optimizations of hierarchies containing lots of ghost nodes - Further exploration of UI hierarchies and markers for root nodes/leaf nodes to create better ergonomics for things like `UiLayer` (world-space ui) --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: UkoeHB <37489173+UkoeHB@users.noreply.github.com>
2024-10-02 00:24:28 +00:00
[package.metadata.example.ghost_nodes]
name = "Ghost Nodes"
description = "Demonstrates the use of Ghost Nodes to skip entities in the UI layout hierarchy"
category = "UI (User Interface)"
wasm = true
Add CSS Grid support to `bevy_ui` (#8026) # Objective An easy way to create 2D grid layouts ## Solution Enable the `grid` feature in Taffy and add new style types for defining grids. ## Notes - ~I'm having a bit of trouble getting `#[derive(Reflect)]` to work properly. Help with that would be appreciated (EDIT: got it to compile by ignoring the problematic fields, but this presumably can't be merged).~ This is now fixed - ~The alignment types now have a `Normal` variant because I couldn't get reflect to work with `Option`.~ I've decided to stick with the flattened variant, as it saves a level of wrapping when authoring styles. But I've renamed the variants from `Normal` to `Default`. - ~This currently exposes a simplified API on top of grid. In particular the following is not currently supported:~ - ~Negative grid indices~ Now supported. - ~Custom `end` values for grid placement (you can only use `start` and `span`)~ Now supported - ~`minmax()` track sizing functions~ minmax is now support through a `GridTrack::minmax()` constructor - ~`repeat()`~ repeat is now implemented as `RepeatedGridTrack` - ~Documentation still needs to be improved.~ An initial pass over the documentation has been completed. ## Screenshot <img width="846" alt="Screenshot 2023-03-10 at 17 56 21" src="https://user-images.githubusercontent.com/1007307/224435332-69aa9eac-123d-4856-b75d-5449d3f1d426.png"> --- ## Changelog - Support for CSS Grid layout added to `bevy_ui` --------- Co-authored-by: Rob Parrett <robparrett@gmail.com> Co-authored-by: Andreas Weibye <13300393+Weibye@users.noreply.github.com>
2023-04-17 16:21:38 +00:00
[[example]]
name = "grid"
path = "examples/ui/grid.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add CSS Grid support to `bevy_ui` (#8026) # Objective An easy way to create 2D grid layouts ## Solution Enable the `grid` feature in Taffy and add new style types for defining grids. ## Notes - ~I'm having a bit of trouble getting `#[derive(Reflect)]` to work properly. Help with that would be appreciated (EDIT: got it to compile by ignoring the problematic fields, but this presumably can't be merged).~ This is now fixed - ~The alignment types now have a `Normal` variant because I couldn't get reflect to work with `Option`.~ I've decided to stick with the flattened variant, as it saves a level of wrapping when authoring styles. But I've renamed the variants from `Normal` to `Default`. - ~This currently exposes a simplified API on top of grid. In particular the following is not currently supported:~ - ~Negative grid indices~ Now supported. - ~Custom `end` values for grid placement (you can only use `start` and `span`)~ Now supported - ~`minmax()` track sizing functions~ minmax is now support through a `GridTrack::minmax()` constructor - ~`repeat()`~ repeat is now implemented as `RepeatedGridTrack` - ~Documentation still needs to be improved.~ An initial pass over the documentation has been completed. ## Screenshot <img width="846" alt="Screenshot 2023-03-10 at 17 56 21" src="https://user-images.githubusercontent.com/1007307/224435332-69aa9eac-123d-4856-b75d-5449d3f1d426.png"> --- ## Changelog - Support for CSS Grid layout added to `bevy_ui` --------- Co-authored-by: Rob Parrett <robparrett@gmail.com> Co-authored-by: Andreas Weibye <13300393+Weibye@users.noreply.github.com>
2023-04-17 16:21:38 +00:00
[package.metadata.example.grid]
name = "CSS Grid"
description = "An example for CSS Grid layout"
UI Scrolling (#15291) # Objective - Fixes #8074 - Adopts / Supersedes #8104 ## Solution Adapted from #8104 and affords the same benefits. **Additions** - [x] Update scrolling on relayout (height of node or contents may have changed) - [x] Make ScrollPosition component optional for ui nodes to avoid checking every node on scroll - [x] Nested scrollviews **Omissions** - Removed input handling for scrolling from `bevy_ui`. Users should update `ScrollPosition` directly. ### Implementation Adds a new `ScrollPosition` component. Updating this component on a `Node` with an overflow axis set to `OverflowAxis::Scroll` will reposition its children by that amount when calculating node transforms. As before, no impact on the underlying Taffy layout. Calculating this correctly is trickier than it was in #8104 due to `"Update scrolling on relayout"`. **Background** When `ScrollPosition` is updated directly by the user, it can be trivially handled in-engine by adding the parent's scroll position to the final location of each child node. However, _other layout actions_ may result in a situation where `ScrollPosition` needs to be updated. Consider a 1000 pixel tall vertically scrolling list of 100 elements, each 100 pixels tall. Scrolled to the bottom, the `ScrollPosition.offset_y` is 9000, just enough to display the last element in the list. When removing an element from that list, the new desired `ScrollPosition.offset_y` is 8900, but, critically, that is not known until after the sizes and positions of the children of the scrollable node are resolved. All user scrolling code today handles this by delaying the resolution by one frame. One notable disadvantage of this is the inability to support `WinitSettings::desktop_app()`, since there would need to be an input AFTER the layout change that caused the scroll position to update for the results of the scroll position update to render visually. I propose the alternative in this PR, which allows for same-frame resolution of scrolling layout. **Resolution** _Edit: Below resolution is outdated, and replaced with the simpler usage of taffy's `Layout::content_size`._ When recursively iterating the children of a node, each child now returns a `Vec2` representing the location of their own bottom right corner. Then, `[[0,0, [x,y]]` represents a bounding box containing the scrollable area filled by that child. Scrollable parents aggregate those areas into the bounding box of _all_ children, then consider that result against `ScrollPosition` to ensure its validity. In the event that resolution of the layout of the children invalidates the `ScrollPosition` (e.g. scrolled further than there were children to scroll to), _all_ children of that node must be recursively repositioned. The position of each child must change as a result of the change in scroll position. Therefore, this implementation takes care to only spend the cost of the "second layout pass" when a specific node actually had a `ScrollPosition` forcibly updated by the layout of its children. ## Testing Examples in `ui/scroll.rs`. There may be more complex node/style interactions that were unconsidered. --- ## Showcase ![scroll](https://github.com/user-attachments/assets/1331138f-93aa-4a8f-959c-6be18a04ff03) ## Alternatives - `bevy_ui` doesn't support scrolling. - `bevy_ui` implements scrolling with a one-frame delay on reactions to layout changes.
2024-09-23 17:17:58 +00:00
category = "UI (User Interface)"
wasm = true
[[example]]
name = "scroll"
path = "examples/ui/scroll.rs"
doc-scrape-examples = true
UI text wrapping and `LineBreakOn` example (#7761) # Objective An example demonstrating more text layout options, text wrapping and `LineBreakOn`. <img width="961" alt="text_wrap" src="https://user-images.githubusercontent.com/27962798/220125391-48163d28-51d9-4df5-b34a-f95ca3661b7d.PNG"> Won't look exactly like this on main because of the remaining bugs in text. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2023-04-24 14:22:31 +00:00
UI Scrolling (#15291) # Objective - Fixes #8074 - Adopts / Supersedes #8104 ## Solution Adapted from #8104 and affords the same benefits. **Additions** - [x] Update scrolling on relayout (height of node or contents may have changed) - [x] Make ScrollPosition component optional for ui nodes to avoid checking every node on scroll - [x] Nested scrollviews **Omissions** - Removed input handling for scrolling from `bevy_ui`. Users should update `ScrollPosition` directly. ### Implementation Adds a new `ScrollPosition` component. Updating this component on a `Node` with an overflow axis set to `OverflowAxis::Scroll` will reposition its children by that amount when calculating node transforms. As before, no impact on the underlying Taffy layout. Calculating this correctly is trickier than it was in #8104 due to `"Update scrolling on relayout"`. **Background** When `ScrollPosition` is updated directly by the user, it can be trivially handled in-engine by adding the parent's scroll position to the final location of each child node. However, _other layout actions_ may result in a situation where `ScrollPosition` needs to be updated. Consider a 1000 pixel tall vertically scrolling list of 100 elements, each 100 pixels tall. Scrolled to the bottom, the `ScrollPosition.offset_y` is 9000, just enough to display the last element in the list. When removing an element from that list, the new desired `ScrollPosition.offset_y` is 8900, but, critically, that is not known until after the sizes and positions of the children of the scrollable node are resolved. All user scrolling code today handles this by delaying the resolution by one frame. One notable disadvantage of this is the inability to support `WinitSettings::desktop_app()`, since there would need to be an input AFTER the layout change that caused the scroll position to update for the results of the scroll position update to render visually. I propose the alternative in this PR, which allows for same-frame resolution of scrolling layout. **Resolution** _Edit: Below resolution is outdated, and replaced with the simpler usage of taffy's `Layout::content_size`._ When recursively iterating the children of a node, each child now returns a `Vec2` representing the location of their own bottom right corner. Then, `[[0,0, [x,y]]` represents a bounding box containing the scrollable area filled by that child. Scrollable parents aggregate those areas into the bounding box of _all_ children, then consider that result against `ScrollPosition` to ensure its validity. In the event that resolution of the layout of the children invalidates the `ScrollPosition` (e.g. scrolled further than there were children to scroll to), _all_ children of that node must be recursively repositioned. The position of each child must change as a result of the change in scroll position. Therefore, this implementation takes care to only spend the cost of the "second layout pass" when a specific node actually had a `ScrollPosition` forcibly updated by the layout of its children. ## Testing Examples in `ui/scroll.rs`. There may be more complex node/style interactions that were unconsidered. --- ## Showcase ![scroll](https://github.com/user-attachments/assets/1331138f-93aa-4a8f-959c-6be18a04ff03) ## Alternatives - `bevy_ui` doesn't support scrolling. - `bevy_ui` implements scrolling with a one-frame delay on reactions to layout changes.
2024-09-23 17:17:58 +00:00
[package.metadata.example.scroll]
name = "Scroll"
description = "Demonstrates scrolling UI containers"
Add CSS Grid support to `bevy_ui` (#8026) # Objective An easy way to create 2D grid layouts ## Solution Enable the `grid` feature in Taffy and add new style types for defining grids. ## Notes - ~I'm having a bit of trouble getting `#[derive(Reflect)]` to work properly. Help with that would be appreciated (EDIT: got it to compile by ignoring the problematic fields, but this presumably can't be merged).~ This is now fixed - ~The alignment types now have a `Normal` variant because I couldn't get reflect to work with `Option`.~ I've decided to stick with the flattened variant, as it saves a level of wrapping when authoring styles. But I've renamed the variants from `Normal` to `Default`. - ~This currently exposes a simplified API on top of grid. In particular the following is not currently supported:~ - ~Negative grid indices~ Now supported. - ~Custom `end` values for grid placement (you can only use `start` and `span`)~ Now supported - ~`minmax()` track sizing functions~ minmax is now support through a `GridTrack::minmax()` constructor - ~`repeat()`~ repeat is now implemented as `RepeatedGridTrack` - ~Documentation still needs to be improved.~ An initial pass over the documentation has been completed. ## Screenshot <img width="846" alt="Screenshot 2023-03-10 at 17 56 21" src="https://user-images.githubusercontent.com/1007307/224435332-69aa9eac-123d-4856-b75d-5449d3f1d426.png"> --- ## Changelog - Support for CSS Grid layout added to `bevy_ui` --------- Co-authored-by: Rob Parrett <robparrett@gmail.com> Co-authored-by: Andreas Weibye <13300393+Weibye@users.noreply.github.com>
2023-04-17 16:21:38 +00:00
category = "UI (User Interface)"
wasm = true
UI text layout example (#7359) ## Objective An example that demonstrates how the `AlignItems` and `JustifyContent` properties can be composed to layout text. <img width="654" alt="text_layout_example" src="https://user-images.githubusercontent.com/27962798/215116345-daa8ef60-634b-40c6-9b6d-356de3af620c.png">
2023-01-27 19:07:48 +00:00
organize examples and add ecs guide
2020-05-01 20:12:47 +00:00
[[example]]
Add transparency examples (#3695) Adds examples demonstrating transparency for 2d, 3d and UI. Fixes #3215.
2022-06-06 17:52:09 +00:00
name = "transparency_ui"
path = "examples/ui/transparency_ui.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add transparency examples (#3695) Adds examples demonstrating transparency for 2d, 3d and UI. Fixes #3215.
2022-06-06 17:52:09 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.transparency_ui]
name = "Transparency UI"
description = "Demonstrates transparency for UI"
category = "UI (User Interface)"
wasm = true
Add z-index support with a predictable UI stack (#5877) # Objective Add consistent UI rendering and interaction where deep nodes inside two different hierarchies will never render on top of one-another by default and offer an escape hatch (z-index) for nodes to change their depth. ## The problem with current implementation The current implementation of UI rendering is broken in that regard, mainly because [it sets the Z value of the `Transform` component based on a "global Z" space](https://github.com/bevyengine/bevy/blob/main/crates/bevy_ui/src/update.rs#L43) shared by all nodes in the UI. This doesn't account for the fact that each node's final `GlobalTransform` value will be relative to its parent. This effectively makes the depth unpredictable when two deep trees are rendered on top of one-another. At the moment, it's also up to each part of the UI code to sort all of the UI nodes. The solution that's offered here does the full sorting of UI node entities once and offers the result through a resource so that all systems can use it. ## Solution ### New ZIndex component This adds a new optional `ZIndex` enum component for nodes which offers two mechanism: - `ZIndex::Local(i32)`: Overrides the depth of the node relative to its siblings. - `ZIndex::Global(i32)`: Overrides the depth of the node relative to the UI root. This basically allows any node in the tree to "escape" the parent and be ordered relative to the entire UI. Note that in the current implementation, omitting `ZIndex` on a node has the same result as adding `ZIndex::Local(0)`. Additionally, the "global" stacking context is essentially a way to add your node to the root stacking context, so using `ZIndex::Local(n)` on a root node (one without parent) will share that space with all nodes using `Index::Global(n)`. ### New UiStack resource This adds a new `UiStack` resource which is calculated from both hierarchy and `ZIndex` during UI update and contains a vector of all node entities in the UI, ordered by depth (from farthest from camera to closest). This is exposed publicly by the bevy_ui crate with the hope that it can be used for consistent ordering and to reduce the amount of sorting that needs to be done by UI systems (i.e. instead of sorting everything by `global_transform.z` in every system, this array can be iterated over). ### New z_index example This also adds a new z_index example that showcases the new `ZIndex` component. It's also a good general demo of the new UI stack system, because making this kind of UI was very broken with the old system (e.g. nodes would render on top of each other, not respecting hierarchy or insert order at all). ![image](https://user-images.githubusercontent.com/1060971/189015985-8ea8f989-0e9d-4601-a7e0-4a27a43a53f9.png) --- ## Changelog - Added the `ZIndex` component to bevy_ui. - Added the `UiStack` resource to bevy_ui, and added implementation in a new `stack.rs` module. - Removed the previous Z updating system from bevy_ui, because it was replaced with the above. - Changed bevy_ui rendering to use UiStack instead of z ordering. - Changed bevy_ui focus/interaction system to use UiStack instead of z ordering. - Added a new z_index example. ## ZIndex demo Here's a demo I wrote to test these features https://user-images.githubusercontent.com/1060971/188329295-d7beebd6-9aee-43ab-821e-d437df5dbe8a.mp4 Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-11-02 22:06:04 +00:00
[[example]]
name = "z_index"
path = "examples/ui/z_index.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add z-index support with a predictable UI stack (#5877) # Objective Add consistent UI rendering and interaction where deep nodes inside two different hierarchies will never render on top of one-another by default and offer an escape hatch (z-index) for nodes to change their depth. ## The problem with current implementation The current implementation of UI rendering is broken in that regard, mainly because [it sets the Z value of the `Transform` component based on a "global Z" space](https://github.com/bevyengine/bevy/blob/main/crates/bevy_ui/src/update.rs#L43) shared by all nodes in the UI. This doesn't account for the fact that each node's final `GlobalTransform` value will be relative to its parent. This effectively makes the depth unpredictable when two deep trees are rendered on top of one-another. At the moment, it's also up to each part of the UI code to sort all of the UI nodes. The solution that's offered here does the full sorting of UI node entities once and offers the result through a resource so that all systems can use it. ## Solution ### New ZIndex component This adds a new optional `ZIndex` enum component for nodes which offers two mechanism: - `ZIndex::Local(i32)`: Overrides the depth of the node relative to its siblings. - `ZIndex::Global(i32)`: Overrides the depth of the node relative to the UI root. This basically allows any node in the tree to "escape" the parent and be ordered relative to the entire UI. Note that in the current implementation, omitting `ZIndex` on a node has the same result as adding `ZIndex::Local(0)`. Additionally, the "global" stacking context is essentially a way to add your node to the root stacking context, so using `ZIndex::Local(n)` on a root node (one without parent) will share that space with all nodes using `Index::Global(n)`. ### New UiStack resource This adds a new `UiStack` resource which is calculated from both hierarchy and `ZIndex` during UI update and contains a vector of all node entities in the UI, ordered by depth (from farthest from camera to closest). This is exposed publicly by the bevy_ui crate with the hope that it can be used for consistent ordering and to reduce the amount of sorting that needs to be done by UI systems (i.e. instead of sorting everything by `global_transform.z` in every system, this array can be iterated over). ### New z_index example This also adds a new z_index example that showcases the new `ZIndex` component. It's also a good general demo of the new UI stack system, because making this kind of UI was very broken with the old system (e.g. nodes would render on top of each other, not respecting hierarchy or insert order at all). ![image](https://user-images.githubusercontent.com/1060971/189015985-8ea8f989-0e9d-4601-a7e0-4a27a43a53f9.png) --- ## Changelog - Added the `ZIndex` component to bevy_ui. - Added the `UiStack` resource to bevy_ui, and added implementation in a new `stack.rs` module. - Removed the previous Z updating system from bevy_ui, because it was replaced with the above. - Changed bevy_ui rendering to use UiStack instead of z ordering. - Changed bevy_ui focus/interaction system to use UiStack instead of z ordering. - Added a new z_index example. ## ZIndex demo Here's a demo I wrote to test these features https://user-images.githubusercontent.com/1060971/188329295-d7beebd6-9aee-43ab-821e-d437df5dbe8a.mp4 Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-11-02 22:06:04 +00:00
[package.metadata.example.z_index]
name = "UI Z-Index"
description = "Demonstrates how to control the relative depth (z-position) of UI elements"
category = "UI (User Interface)"
wasm = true
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
Add UI scaling (#5814) # Objective - Allow users to change the scaling of the UI - Adopted from #2808 ## Solution - This is an accessibility feature for fixed-size UI elements, allowing the developer to expose a range of UI scales for the player to set a scale that works for their needs. > - The user can modify the UiScale struct to change the scaling at runtime. This multiplies the Px values by the scale given, while not touching any others. > - The example showcases how this even allows for fluid transitions > Here's how the example looks like: https://user-images.githubusercontent.com/1631166/132979069-044161a9-8e85-45ab-9e93-fcf8e3852c2b.mp4 --- ## Changelog - Added a `UiScale` which can be used to scale all of UI Co-authored-by: Andreas Weibye <13300393+Weibye@users.noreply.github.com> Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-08-29 23:35:53 +00:00
[[example]]
name = "ui_scaling"
Rename example file scaling.rs to ui_scaling.rs (#6296) # Objective To be consistent like other examples, it's better to keep file name and example name same, so we don't need to find correct example name in Cargo.toml. ## Solution Rename example file scaling.rs to ui_scaling.rs.
2022-10-19 11:36:26 +00:00
path = "examples/ui/ui_scaling.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add UI scaling (#5814) # Objective - Allow users to change the scaling of the UI - Adopted from #2808 ## Solution - This is an accessibility feature for fixed-size UI elements, allowing the developer to expose a range of UI scales for the player to set a scale that works for their needs. > - The user can modify the UiScale struct to change the scaling at runtime. This multiplies the Px values by the scale given, while not touching any others. > - The example showcases how this even allows for fluid transitions > Here's how the example looks like: https://user-images.githubusercontent.com/1631166/132979069-044161a9-8e85-45ab-9e93-fcf8e3852c2b.mp4 --- ## Changelog - Added a `UiScale` which can be used to scale all of UI Co-authored-by: Andreas Weibye <13300393+Weibye@users.noreply.github.com> Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-08-29 23:35:53 +00:00
[package.metadata.example.ui_scaling]
name = "UI Scaling"
description = "Illustrates how to scale the UI"
category = "UI (User Interface)"
wasm = true
UI texture atlas support (#8822) # Objective This adds support for using texture atlas sprites in UI. From discussions today in the ui-dev discord it seems this is a much wanted feature. This was previously attempted in #5070 by @ManevilleF however that was blocked #5103. This work can be easily modified to support #5103 changes after that merges. ## Solution I created a new UI bundle that reuses the existing texture atlas infrastructure. I create a new atlas image component to prevent it from being drawn by the existing non-UI systems and to remove unused parameters. In extract I added new system to calculate the required values for the texture atlas image, this extracts into the same resource as the existing UI Image and Text components. This should have minimal performance impact because if texture atlas is not present then the exact same code path is followed. Also there should be no unintended behavior changes because without the new components the existing systems write the extract same resulting data. I also added an example showing the sprite working and a system to advance the animation on space bar presses. Naming is hard and I would accept any feedback on the bundle name! --- ## Changelog > Added TextureAtlasImageBundle --------- Co-authored-by: ickshonpe <david.curthoys@googlemail.com>
2023-06-19 21:52:02 +00:00
[[example]]
name = "ui_texture_atlas"
path = "examples/ui/ui_texture_atlas.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
UI texture atlas support (#8822) # Objective This adds support for using texture atlas sprites in UI. From discussions today in the ui-dev discord it seems this is a much wanted feature. This was previously attempted in #5070 by @ManevilleF however that was blocked #5103. This work can be easily modified to support #5103 changes after that merges. ## Solution I created a new UI bundle that reuses the existing texture atlas infrastructure. I create a new atlas image component to prevent it from being drawn by the existing non-UI systems and to remove unused parameters. In extract I added new system to calculate the required values for the texture atlas image, this extracts into the same resource as the existing UI Image and Text components. This should have minimal performance impact because if texture atlas is not present then the exact same code path is followed. Also there should be no unintended behavior changes because without the new components the existing systems write the extract same resulting data. I also added an example showing the sprite working and a system to advance the animation on space bar presses. Naming is hard and I would accept any feedback on the bundle name! --- ## Changelog > Added TextureAtlasImageBundle --------- Co-authored-by: ickshonpe <david.curthoys@googlemail.com>
2023-06-19 21:52:02 +00:00
[package.metadata.example.ui_texture_atlas]
name = "UI Texture Atlas"
description = "Illustrates how to use TextureAtlases in UI"
category = "UI (User Interface)"
wasm = true
UI Texture 9 slice (#11600) > Follow up to #10588 > Closes #11749 (Supersedes #11756) Enable Texture slicing for the following UI nodes: - `ImageBundle` - `ButtonBundle` <img width="739" alt="Screenshot 2024-01-29 at 13 57 43" src="https://github.com/bevyengine/bevy/assets/26703856/37675681-74eb-4689-ab42-024310cf3134"> I also added a collection of `fantazy-ui-borders` from [Kenney's](www.kenney.nl) assets, with the appropriate license (CC). If it's a problem I can use the same textures as the `sprite_slice` example # Work done Added the `ImageScaleMode` component to the targetted bundles, most of the logic is directly reused from `bevy_sprite`. The only additional internal component is the UI specific `ComputedSlices`, which does the same thing as its spritee equivalent but adapted to UI code. Again the slicing is not compatible with `TextureAtlas`, it's something I need to tackle more deeply in the future # Fixes * [x] I noticed that `TextureSlicer::compute_slices` could infinitely loop if the border was larger that the image half extents, now an error is triggered and the texture will fallback to being stretched * [x] I noticed that when using small textures with very small *tiling* options we could generate hundred of thousands of slices. Now I set a minimum size of 1 pixel per slice, which is already ridiculously small, and a warning will be sent at runtime when slice count goes above 1000 * [x] Sprite slicing with `flip_x` or `flip_y` would give incorrect results, correct flipping is now supported to both sprites and ui image nodes thanks to @odecay observation # GPU Alternative I create a separate branch attempting to implementing 9 slicing and tiling directly through the `ui.wgsl` fragment shader. It works but requires sending more data to the GPU: - slice border - tiling factors And more importantly, the actual quad *scale* which is hard to put in the shader with the current code, so that would be for a later iteration
2024-02-07 20:07:53 +00:00
[[example]]
name = "ui_texture_slice"
path = "examples/ui/ui_texture_slice.rs"
doc-scrape-examples = true
[package.metadata.example.ui_texture_slice]
name = "UI Texture Slice"
description = "Illustrates how to use 9 Slicing in UI"
category = "UI (User Interface)"
wasm = true
UI texture slice texture flipping reimplementation (#15034) # Objective Fixes #15032 ## Solution Reimplement support for the `flip_x` and `flip_y` fields. This doesn't flip the border geometry, I'm not really sure whether that is desirable or not. Also fixes a bug that was causing the side and center slices to tile incorrectly. ### Testing ``` cargo run --example ui_texture_slice_flip_and_tile ``` ## Showcase <img width="787" alt="nearest" src="https://github.com/user-attachments/assets/bc044bae-1748-42ba-92b5-0500c87264f6"> With tiling need to use nearest filtering to avoid bleeding between the slices. --------- Co-authored-by: Jan Hohenheim <jan@hohenheim.ch> Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2024-09-04 19:31:41 +00:00
[[example]]
name = "ui_texture_slice_flip_and_tile"
path = "examples/ui/ui_texture_slice_flip_and_tile.rs"
doc-scrape-examples = true
[package.metadata.example.ui_texture_slice_flip_and_tile]
name = "UI Texture Slice Flipping and Tiling"
description = "Illustrates how to flip and tile images with 9 Slicing in UI"
category = "UI (User Interface)"
wasm = true
Slicing support for texture atlas (#12059) # Objective Follow up to #11600 and #10588 https://github.com/bevyengine/bevy/issues/11944 made clear that some people want to use slicing with texture atlases ## Changelog * Added support for `TextureAtlas` slicing and tiling. `SpriteSheetBundle` and `AtlasImageBundle` can now use `ImageScaleMode` * Added new `ui_texture_atlas_slice` example using a texture sheet <img width="798" alt="Screenshot 2024-02-23 at 11 58 35" src="https://github.com/bevyengine/bevy/assets/26703856/47a8b764-127c-4a06-893f-181703777501"> --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Pablo Reinhardt <126117294+pablo-lua@users.noreply.github.com>
2024-03-05 16:05:39 +00:00
[[example]]
name = "ui_texture_atlas_slice"
path = "examples/ui/ui_texture_atlas_slice.rs"
doc-scrape-examples = true
[package.metadata.example.ui_texture_atlas_slice]
name = "UI Texture Atlas Slice"
description = "Illustrates how to use 9 Slicing for TextureAtlases in UI"
category = "UI (User Interface)"
wasm = true
Ui Node Borders (#7795) # Objective Implement borders for UI nodes. Relevant discussion: #7785 Related: #5924, #3991 <img width="283" alt="borders" src="https://user-images.githubusercontent.com/27962798/220968899-7661d5ec-6f5b-4b0f-af29-bf9af02259b5.PNG"> ## Solution Add an extraction function to draw the borders. --- Can only do one colour rectangular borders due to the limitations of the Bevy UI renderer. Maybe it can be combined with #3991 eventually to add curved border support. ## Changelog * Added a component `BorderColor`. * Added the `extract_uinode_borders` system to the UI Render App. * Added the UI example `borders` --------- Co-authored-by: Nico Burns <nico@nicoburns.com>
2023-06-14 22:43:38 +00:00
[[example]]
name = "viewport_debug"
path = "examples/ui/viewport_debug.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Ui Node Borders (#7795) # Objective Implement borders for UI nodes. Relevant discussion: #7785 Related: #5924, #3991 <img width="283" alt="borders" src="https://user-images.githubusercontent.com/27962798/220968899-7661d5ec-6f5b-4b0f-af29-bf9af02259b5.PNG"> ## Solution Add an extraction function to draw the borders. --- Can only do one colour rectangular borders due to the limitations of the Bevy UI renderer. Maybe it can be combined with #3991 eventually to add curved border support. ## Changelog * Added a component `BorderColor`. * Added the `extract_uinode_borders` system to the UI Render App. * Added the UI example `borders` --------- Co-authored-by: Nico Burns <nico@nicoburns.com>
2023-06-14 22:43:38 +00:00
[package.metadata.example.viewport_debug]
name = "Viewport Debug"
description = "An example for debugging viewport coordinates"
category = "UI (User Interface)"
wasm = true
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
# Window
render: add ClearColor resource
2020-06-25 22:24:27 +00:00
[[example]]
name = "clear_color"
path = "examples/window/clear_color.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add an example 'showcasing' using multiple windows (#3367) # Objective - The multiple windows example which was viciously murdered in #3175. - cart asked me to ## Solution - Rework the example to work on pipelined-rendering, based on the work from #2898
2021-12-18 19:38:05 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.clear_color]
name = "Clear Color"
description = "Creates a solid color window"
category = "Window"
wasm = true
fix: upgrade to winit v0.30 (#13366) # Objective - Upgrade winit to v0.30 - Fixes https://github.com/bevyengine/bevy/issues/13331 ## Solution This is a rewrite/adaptation of the new trait system described and implemented in `winit` v0.30. ## Migration Guide The custom UserEvent is now renamed as WakeUp, used to wake up the loop if anything happens outside the app (a new [custom_user_event](https://github.com/bevyengine/bevy/pull/13366/files#diff-2de8c0a8d3028d0059a3d80ae31b2bbc1cde2595ce2d317ea378fe3e0cf6ef2d) shows this behavior. The internal `UpdateState` has been removed and replaced internally by the AppLifecycle. When changed, the AppLifecycle is sent as an event. The `UpdateMode` now accepts only two values: `Continuous` and `Reactive`, but the latter exposes 3 new properties to enable reactive to device, user or window events. The previous `UpdateMode::Reactive` is now equivalent to `UpdateMode::reactive()`, while `UpdateMode::ReactiveLowPower` to `UpdateMode::reactive_low_power()`. The `ApplicationLifecycle` has been renamed as `AppLifecycle`, and now contains the possible values of the application state inside the event loop: * `Idle`: the loop has not started yet * `Running` (previously called `Started`): the loop is running * `WillSuspend`: the loop is going to be suspended * `Suspended`: the loop is suspended * `WillResume`: the loop is going to be resumed Note: the `Resumed` state has been removed since the resumed app is just running. Finally, now that `winit` enables this, it extends the `WinitPlugin` to support custom events. ## Test platforms - [x] Windows - [x] MacOs - [x] Linux (x11) - [x] Linux (Wayland) - [x] Android - [x] iOS - [x] WASM/WebGPU - [x] WASM/WebGL2 ## Outstanding issues / regressions - [ ] iOS: build failed in CI - blocking, but may just be flakiness - [x] Cross-platform: when the window is maximised, changes in the scale factor don't apply, to make them apply one has to make the window smaller again. (Re-maximising keeps the updated scale factor) - non-blocking, but good to fix - [ ] Android: it's pretty easy to quickly open and close the app and then the music keeps playing when suspended. - non-blocking but worrying - [ ] Web: the application will hang when switching tabs - Not new, duplicate of https://github.com/bevyengine/bevy/issues/13486 - [ ] Cross-platform?: Screenshot failure, `ERROR present_frames: wgpu_core::present: No work has been submitted for this frame before` taking the first screenshot, but after pressing space - non-blocking, but good to fix --------- Co-authored-by: François <francois.mockers@vleue.com>
2024-06-03 13:06:48 +00:00
[[example]]
name = "custom_user_event"
path = "examples/window/custom_user_event.rs"
doc-scrape-examples = true
[package.metadata.example.custom_user_event]
name = "Custom User Event"
description = "Handles custom user events within the event loop"
category = "Window"
wasm = true
Reduce power usage with configurable event loop (#3974) # Objective - Reduce power usage for games when not focused. - Reduce power usage to ~0 when a desktop application is minimized (opt-in). - Reduce power usage when focused, only updating on a `winit` event, or the user sends a redraw request. (opt-in) https://user-images.githubusercontent.com/2632925/156904387-ec47d7de-7f06-4c6f-8aaf-1e952c1153a2.mp4 Note resource usage in the Task Manager in the above video. ## Solution - Added a type `UpdateMode` that allows users to specify how the winit event loop is updated, without exposing winit types. - Added two fields to `WinitConfig`, both with the `UpdateMode` type. One configures how the application updates when focused, and the other configures how the application behaves when it is not focused. Users can modify this resource manually to set the type of event loop control flow they want. - For convenience, two functions were added to `WinitConfig`, that provide reasonable presets: `game()` (default) and `desktop_app()`. - The `game()` preset, which is used by default, is unchanged from current behavior with one exception: when the app is out of focus the app updates at a minimum of 10fps, or every time a winit event is received. This has a huge positive impact on power use and responsiveness on my machine, which will otherwise continue running the app at many hundreds of fps when out of focus or minimized. - The `desktop_app()` preset is fully reactive, only updating when user input (winit event) is supplied or a `RedrawRequest` event is sent. When the app is out of focus, it only updates on `Window` events - i.e. any winit event that directly interacts with the window. What this means in practice is that the app uses *zero* resources when minimized or not interacted with, but still updates fluidly when the app is out of focus and the user mouses over the application. - Added a `RedrawRequest` event so users can force an update even if there are no events. This is useful in an application when you want to, say, run an animation even when the user isn't providing input. - Added an example `low_power` to demonstrate these changes ## Usage Configuring the event loop: ```rs use bevy::winit::{WinitConfig}; // ... .insert_resource(WinitConfig::desktop_app()) // preset // or .insert_resource(WinitConfig::game()) // preset // or .insert_resource(WinitConfig{ .. }) // manual ``` Requesting a redraw: ```rs use bevy::window::RequestRedraw; // ... fn request_redraw(mut event: EventWriter<RequestRedraw>) { event.send(RequestRedraw); } ``` ## Other details - Because we have a single event loop for multiple windows, every time I've mentioned "focused" above, I more precisely mean, "if at least one bevy window is focused". - Due to a platform bug in winit (https://github.com/rust-windowing/winit/issues/1619), we can't simply use `Window::request_redraw()`. As a workaround, this PR will temporarily set the window mode to `Poll` when a redraw is requested. This is then reset to the user's `WinitConfig` setting on the next frame.
2022-03-07 23:32:05 +00:00
[[example]]
name = "low_power"
path = "examples/window/low_power.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Reduce power usage with configurable event loop (#3974) # Objective - Reduce power usage for games when not focused. - Reduce power usage to ~0 when a desktop application is minimized (opt-in). - Reduce power usage when focused, only updating on a `winit` event, or the user sends a redraw request. (opt-in) https://user-images.githubusercontent.com/2632925/156904387-ec47d7de-7f06-4c6f-8aaf-1e952c1153a2.mp4 Note resource usage in the Task Manager in the above video. ## Solution - Added a type `UpdateMode` that allows users to specify how the winit event loop is updated, without exposing winit types. - Added two fields to `WinitConfig`, both with the `UpdateMode` type. One configures how the application updates when focused, and the other configures how the application behaves when it is not focused. Users can modify this resource manually to set the type of event loop control flow they want. - For convenience, two functions were added to `WinitConfig`, that provide reasonable presets: `game()` (default) and `desktop_app()`. - The `game()` preset, which is used by default, is unchanged from current behavior with one exception: when the app is out of focus the app updates at a minimum of 10fps, or every time a winit event is received. This has a huge positive impact on power use and responsiveness on my machine, which will otherwise continue running the app at many hundreds of fps when out of focus or minimized. - The `desktop_app()` preset is fully reactive, only updating when user input (winit event) is supplied or a `RedrawRequest` event is sent. When the app is out of focus, it only updates on `Window` events - i.e. any winit event that directly interacts with the window. What this means in practice is that the app uses *zero* resources when minimized or not interacted with, but still updates fluidly when the app is out of focus and the user mouses over the application. - Added a `RedrawRequest` event so users can force an update even if there are no events. This is useful in an application when you want to, say, run an animation even when the user isn't providing input. - Added an example `low_power` to demonstrate these changes ## Usage Configuring the event loop: ```rs use bevy::winit::{WinitConfig}; // ... .insert_resource(WinitConfig::desktop_app()) // preset // or .insert_resource(WinitConfig::game()) // preset // or .insert_resource(WinitConfig{ .. }) // manual ``` Requesting a redraw: ```rs use bevy::window::RequestRedraw; // ... fn request_redraw(mut event: EventWriter<RequestRedraw>) { event.send(RequestRedraw); } ``` ## Other details - Because we have a single event loop for multiple windows, every time I've mentioned "focused" above, I more precisely mean, "if at least one bevy window is focused". - Due to a platform bug in winit (https://github.com/rust-windowing/winit/issues/1619), we can't simply use `Window::request_redraw()`. As a workaround, this PR will temporarily set the window mode to `Poll` when a redraw is requested. This is then reset to the user's `WinitConfig` setting on the next frame.
2022-03-07 23:32:05 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.low_power]
name = "Low Power"
description = "Demonstrates settings to reduce power use for bevy applications"
category = "Window"
wasm = true
Add an example 'showcasing' using multiple windows (#3367) # Objective - The multiple windows example which was viciously murdered in #3175. - cart asked me to ## Solution - Rework the example to work on pipelined-rendering, based on the work from #2898
2021-12-18 19:38:05 +00:00
[[example]]
name = "multiple_windows"
path = "examples/window/multiple_windows.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
render: add ClearColor resource
2020-06-25 22:24:27 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.multiple_windows]
name = "Multiple Windows"
description = "Demonstrates creating multiple windows, and rendering to them"
category = "Window"
wasm = false
Added use_dpi setting to WindowDescriptor (#1131) Added scale_factor_override
2020-12-28 20:26:50 +00:00
[[example]]
name = "scale_factor_override"
path = "examples/window/scale_factor_override.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Added use_dpi setting to WindowDescriptor (#1131) Added scale_factor_override
2020-12-28 20:26:50 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.scale_factor_override]
Fix small typo in example name (#5217) **This Commit** Renames "Scale Factor Iverride" to "Scale Factor Override". **Why?** I imagine the current name is a typo.
2022-07-05 16:59:31 +00:00
name = "Scale Factor Override"
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
description = "Illustrates how to customize the default window settings"
category = "Window"
wasm = true
Add screenshot api (#7163) Fixes https://github.com/bevyengine/bevy/issues/1207 # Objective Right now, it's impossible to capture a screenshot of the entire window without forking bevy. This is because - The swapchain texture never has the COPY_SRC usage - It can't be accessed without taking ownership of it - Taking ownership of it breaks *a lot* of stuff ## Solution - Introduce a dedicated api for taking a screenshot of a given bevy window, and guarantee this screenshot will always match up with what gets put on the screen. --- ## Changelog - Added the `ScreenshotManager` resource with two functions, `take_screenshot` and `save_screenshot_to_disk`
2023-04-19 21:28:42 +00:00
[[example]]
name = "screenshot"
path = "examples/window/screenshot.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add screenshot api (#7163) Fixes https://github.com/bevyengine/bevy/issues/1207 # Objective Right now, it's impossible to capture a screenshot of the entire window without forking bevy. This is because - The swapchain texture never has the COPY_SRC usage - It can't be accessed without taking ownership of it - Taking ownership of it breaks *a lot* of stuff ## Solution - Introduce a dedicated api for taking a screenshot of a given bevy window, and guarantee this screenshot will always match up with what gets put on the screen. --- ## Changelog - Added the `ScreenshotManager` resource with two functions, `take_screenshot` and `save_screenshot_to_disk`
2023-04-19 21:28:42 +00:00
[package.metadata.example.screenshot]
name = "Screenshot"
description = "Shows how to save screenshots to disk"
category = "Window"
Screenshots in wasm (#8455) # Objective - Enable taking a screenshot in wasm - Followup on #7163 ## Solution - Create a blob from the image data, generate a url to that blob, add an `a` element to the document linking to that url, click on that element, then revoke the url - This will automatically trigger a download of the screenshot file in the browser
2023-04-28 19:37:11 +00:00
wasm = true
Add screenshot api (#7163) Fixes https://github.com/bevyengine/bevy/issues/1207 # Objective Right now, it's impossible to capture a screenshot of the entire window without forking bevy. This is because - The swapchain texture never has the COPY_SRC usage - It can't be accessed without taking ownership of it - Taking ownership of it breaks *a lot* of stuff ## Solution - Introduce a dedicated api for taking a screenshot of a given bevy window, and guarantee this screenshot will always match up with what gets put on the screen. --- ## Changelog - Added the `ScreenshotManager` resource with two functions, `take_screenshot` and `save_screenshot_to_disk`
2023-04-19 21:28:42 +00:00
Added transparency to window builder (#3105) Applogies, had to recreate this pr because of branching issue. Old PR: https://github.com/bevyengine/bevy/pull/3033 # Objective Fixes #3032 Allowing a user to create a transparent window ## Solution I've allowed the transparent bool to be passed to the winit window builder
2021-12-08 20:53:35 +00:00
[[example]]
name = "transparent_window"
path = "examples/window/transparent_window.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Added transparency to window builder (#3105) Applogies, had to recreate this pr because of branching issue. Old PR: https://github.com/bevyengine/bevy/pull/3033 # Objective Fixes #3032 Allowing a user to create a transparent window ## Solution I've allowed the transparent bool to be passed to the winit window builder
2021-12-08 20:53:35 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.transparent_window]
name = "Transparent Window"
description = "Illustrates making the window transparent and hiding the window decoration"
category = "Window"
wasm = false
window: customizable default descriptor
2020-07-20 09:05:56 +00:00
[[example]]
name = "window_settings"
Allow calling winit with the 'run_return' variant of the run function (#243) This adds a new WinitConfig resource that can be used to configure the behavior of winit. When `return_from_run` is set to `true`, `App::run()` will return on `target_os` configurations that support it. Closes bevyengine/bevy#167.
2020-08-21 05:37:19 +00:00
path = "examples/window/window_settings.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Implement single threaded task scheduler for WebAssembly (#496) * Add hello_wasm example * Implement single threaded task scheduler for WebAssembly
2020-09-16 01:05:31 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.window_settings]
name = "Window Settings"
description = "Demonstrates customizing default window settings"
category = "Window"
wasm = true
Add window drag move and drag resize without decoration example. (#15814) # Objective Add an example for the new drag move and drag resize introduced by PR #15674 and fix #15734. ## Solution I created an example that allows the user to exercise drag move and drag resize separately. The user can also choose what direction the resize works in. ![Screenshot 2024-10-10 at 4 06 43 AM](https://github.com/user-attachments/assets/1da558ab-a80f-49af-8b7d-bb635b0f038f) ### Name The example is called `window_drag_move`. Happy to have that bikeshedded. ### Contentious Refactor? This PR removed the `ResizeDirection` enumeration in favor of using `CompassOctant` which had the same variants. Perhaps this is contentious. ### Unsafe? In PR #15674 I mentioned that `start_drag_move()` and `start_drag_resize()`'s requirement to only be called in the presence of a left-click looks like a compiler-unenforceable contract that can cause intermittent panics when not observed, so perhaps the functions should be marked them unsafe. **I have not made that change** here since I didn't see a clear consensus on that. ## Testing I exercised this on x86 macOS. However, winit for macOS does not support drag resize. It reports a good error when `start_drag_resize()` is called. I'd like to see it tested on Windows and Linux. --- ## Showcase Example window_drag_move shows how to drag or resize a window without decoration. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2024-10-15 23:38:35 +00:00
[[example]]
name = "window_drag_move"
path = "examples/window/window_drag_move.rs"
doc-scrape-examples = true
[package.metadata.example.window_drag_move]
name = "Window Drag Move"
description = "Demonstrates drag move and drag resize without window decoration"
category = "Window"
wasm = false
Test for ambiguous system ordering in CI (#13950) Progress towards https://github.com/bevyengine/bevy/issues/7386. Following discussion https://discord.com/channels/691052431525675048/1253260494538539048/1253387942311886960 This Pull Request adds an example to detect system order ambiguities, and also asserts none exist. A lot of schedules are ignored in ordered to have the test passing, we should thrive to make them pass, but in other pull requests. <details><summary>example output <b>summary</b>, without ignored schedules</summary> <p> ```txt $ cargo run --example ambiguity_detection 2>&1 | grep -C 1 "pairs of syst" 2024-06-21T13:17:55.776585Z WARN bevy_ecs::schedule::schedule: Schedule First has ambiguities. 1 pairs of systems with conflicting data access have indeterminate execution order. Consider adding `before`, `after`, or `ambiguous_with` relationships between these: -- bevy_time::time_system (in set TimeSystem) and bevy_ecs::event::event_update_system (in set EventUpdates) -- 2024-06-21T13:17:55.782265Z WARN bevy_ecs::schedule::schedule: Schedule PreUpdate has ambiguities. 11 pairs of systems with conflicting data access have indeterminate execution order. Consider adding `before`, `after`, or `ambiguous_with` relationships between these: -- bevy_pbr::prepass::update_mesh_previous_global_transforms and bevy_asset::server::handle_internal_asset_events -- 2024-06-21T13:17:55.809516Z WARN bevy_ecs::schedule::schedule: Schedule PostUpdate has ambiguities. 63 pairs of systems with conflicting data access have indeterminate execution order. Consider adding `before`, `after`, or `ambiguous_with` relationships between these: -- bevy_ui::accessibility::image_changed and bevy_ecs::schedule::executor::apply_deferred -- 2024-06-21T13:17:55.816287Z WARN bevy_ecs::schedule::schedule: Schedule Last has ambiguities. 3 pairs of systems with conflicting data access have indeterminate execution order. Consider adding `before`, `after`, or `ambiguous_with` relationships between these: -- bevy_gizmos::update_gizmo_meshes<bevy_gizmos::aabb::AabbGizmoConfigGroup> (in set UpdateGizmoMeshes) and bevy_gizmos::update_gizmo_meshes<bevy_gizmos::light::LightGizmoConfigGroup> (in set UpdateGizmoMeshes) -- 2024-06-21T13:17:55.831074Z WARN bevy_ecs::schedule::schedule: Schedule ExtractSchedule has ambiguities. 296 pairs of systems with conflicting data access have indeterminate execution order. Consider adding `before`, `after`, or `ambiguous_with` relationships between these: -- bevy_render::extract_component::extract_components<bevy_sprite::SpriteSource> and bevy_render::render_asset::extract_render_asset<bevy_sprite::mesh2d::material::PreparedMaterial2d<bevy_sprite::mesh2d::color_material::ColorMaterial>> ``` </p> </details> To try locally: ```sh CI_TESTING_CONFIG="./.github/example-run/ambiguity_detection.ron" cargo run --example ambiguity_detection --features "bevy_ci_testing,trace,trace_chrome" ``` --------- Co-authored-by: Jan Hohenheim <jan@hohenheim.ch>
2024-07-17 21:05:48 +00:00
[[example]]
name = "ambiguity_detection"
path = "tests/ecs/ambiguity_detection.rs"
doc-scrape-examples = true
[package.metadata.example.ambiguity_detection]
hidden = true
Add an example to test small window sizes (#3597) # Objective We keep getting issues where things break at small window sizes, e.g #3368 (caused by #3153), #3596 ('caused' by #3545) ## Solution - Add a test that we can make small windows. Currently, this fails on my machine with some quite scary vulkan errors: ``` 2022-01-08T22:55:13.770261Z ERROR wgpu_hal::vulkan::instance: VALIDATION [VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 (0x7cd0911d)] Validation Error: [ VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 ] Object 0: handle = 0x1adbd410a60, type = VK_OBJECT_TYPE_DEVICE; | MessageID = 0x7cd0911d | vkCreateSwapchainKHR() called with imageExtent = (225,60), which is outside the bounds returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR(): currentExtent = (225,56), minImageExtent = (225,56), maxImageExtent = (225,56). The Vulkan spec states: imageExtent must be between minImageExtent and maxImageExtent, inclusive, where minImageExtent and maxImageExtent are members of the VkSurfaceCapabilitiesKHR structure returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface (https://vulkan.lunarg.com/doc/view/1.2.198.1/windows/1.2-extensions/vkspec.html#VUID-VkSwapchainCreateInfoKHR-imageExtent-01274) 2022-01-08T22:55:13.770808Z ERROR wgpu_hal::vulkan::instance: objects: (type: DEVICE, hndl: 0x1adbd410a60, name: ?) 2022-01-08T22:55:13.787403Z ERROR wgpu_hal::vulkan::instance: VALIDATION [VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 (0x7cd0911d)] Validation Error: [ VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 ] Object 0: handle = 0x1adbd410a60, type = VK_OBJECT_TYPE_DEVICE; | MessageID = 0x7cd0911d | vkCreateSwapchainKHR() called with imageExtent = (225,56), which is outside the bounds returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR(): currentExtent = (225,52), minImageExtent = (225,52), maxImageExtent = (225,52). The Vulkan spec states: imageExtent must be between minImageExtent and maxImageExtent, inclusive, where minImageExtent and maxImageExtent are members of the VkSurfaceCapabilitiesKHR structure returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface (https://vulkan.lunarg.com/doc/view/1.2.198.1/windows/1.2-extensions/vkspec.html#VUID-VkSwapchainCreateInfoKHR-imageExtent-01274) ``` etc. This might be a new issue here, although I'm surprised it's vulkan giving this error; wgpu should stop it if this is illegal.
2022-04-26 22:15:24 +00:00
[[example]]
name = "resizing"
path = "tests/window/resizing.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add an example to test small window sizes (#3597) # Objective We keep getting issues where things break at small window sizes, e.g #3368 (caused by #3153), #3596 ('caused' by #3545) ## Solution - Add a test that we can make small windows. Currently, this fails on my machine with some quite scary vulkan errors: ``` 2022-01-08T22:55:13.770261Z ERROR wgpu_hal::vulkan::instance: VALIDATION [VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 (0x7cd0911d)] Validation Error: [ VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 ] Object 0: handle = 0x1adbd410a60, type = VK_OBJECT_TYPE_DEVICE; | MessageID = 0x7cd0911d | vkCreateSwapchainKHR() called with imageExtent = (225,60), which is outside the bounds returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR(): currentExtent = (225,56), minImageExtent = (225,56), maxImageExtent = (225,56). The Vulkan spec states: imageExtent must be between minImageExtent and maxImageExtent, inclusive, where minImageExtent and maxImageExtent are members of the VkSurfaceCapabilitiesKHR structure returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface (https://vulkan.lunarg.com/doc/view/1.2.198.1/windows/1.2-extensions/vkspec.html#VUID-VkSwapchainCreateInfoKHR-imageExtent-01274) 2022-01-08T22:55:13.770808Z ERROR wgpu_hal::vulkan::instance: objects: (type: DEVICE, hndl: 0x1adbd410a60, name: ?) 2022-01-08T22:55:13.787403Z ERROR wgpu_hal::vulkan::instance: VALIDATION [VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 (0x7cd0911d)] Validation Error: [ VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 ] Object 0: handle = 0x1adbd410a60, type = VK_OBJECT_TYPE_DEVICE; | MessageID = 0x7cd0911d | vkCreateSwapchainKHR() called with imageExtent = (225,56), which is outside the bounds returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR(): currentExtent = (225,52), minImageExtent = (225,52), maxImageExtent = (225,52). The Vulkan spec states: imageExtent must be between minImageExtent and maxImageExtent, inclusive, where minImageExtent and maxImageExtent are members of the VkSurfaceCapabilitiesKHR structure returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface (https://vulkan.lunarg.com/doc/view/1.2.198.1/windows/1.2-extensions/vkspec.html#VUID-VkSwapchainCreateInfoKHR-imageExtent-01274) ``` etc. This might be a new issue here, although I'm surprised it's vulkan giving this error; wgpu should stop it if this is illegal.
2022-04-26 22:15:24 +00:00
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
[package.metadata.example.resizing]
hidden = true
Add an example to test small window sizes (#3597) # Objective We keep getting issues where things break at small window sizes, e.g #3368 (caused by #3153), #3596 ('caused' by #3545) ## Solution - Add a test that we can make small windows. Currently, this fails on my machine with some quite scary vulkan errors: ``` 2022-01-08T22:55:13.770261Z ERROR wgpu_hal::vulkan::instance: VALIDATION [VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 (0x7cd0911d)] Validation Error: [ VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 ] Object 0: handle = 0x1adbd410a60, type = VK_OBJECT_TYPE_DEVICE; | MessageID = 0x7cd0911d | vkCreateSwapchainKHR() called with imageExtent = (225,60), which is outside the bounds returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR(): currentExtent = (225,56), minImageExtent = (225,56), maxImageExtent = (225,56). The Vulkan spec states: imageExtent must be between minImageExtent and maxImageExtent, inclusive, where minImageExtent and maxImageExtent are members of the VkSurfaceCapabilitiesKHR structure returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface (https://vulkan.lunarg.com/doc/view/1.2.198.1/windows/1.2-extensions/vkspec.html#VUID-VkSwapchainCreateInfoKHR-imageExtent-01274) 2022-01-08T22:55:13.770808Z ERROR wgpu_hal::vulkan::instance: objects: (type: DEVICE, hndl: 0x1adbd410a60, name: ?) 2022-01-08T22:55:13.787403Z ERROR wgpu_hal::vulkan::instance: VALIDATION [VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 (0x7cd0911d)] Validation Error: [ VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 ] Object 0: handle = 0x1adbd410a60, type = VK_OBJECT_TYPE_DEVICE; | MessageID = 0x7cd0911d | vkCreateSwapchainKHR() called with imageExtent = (225,56), which is outside the bounds returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR(): currentExtent = (225,52), minImageExtent = (225,52), maxImageExtent = (225,52). The Vulkan spec states: imageExtent must be between minImageExtent and maxImageExtent, inclusive, where minImageExtent and maxImageExtent are members of the VkSurfaceCapabilitiesKHR structure returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface (https://vulkan.lunarg.com/doc/view/1.2.198.1/windows/1.2-extensions/vkspec.html#VUID-VkSwapchainCreateInfoKHR-imageExtent-01274) ``` etc. This might be a new issue here, although I'm surprised it's vulkan giving this error; wgpu should stop it if this is illegal.
2022-04-26 22:15:24 +00:00
[[example]]
Use `en-us` locale for `typos` (#16037) # Objective Bevy seems to want to standardize on "American English" spellings. Not sure if this is laid out anywhere in writing, but see also #15947. While perusing the docs for `typos`, I noticed that it has a `locale` config option and tried it out. ## Solution Switch to `en-us` locale in the `typos` config and run `typos -w` ## Migration Guide The following methods or fields have been renamed from `*dependants*` to `*dependents*`. - `ProcessorAssetInfo::dependants` - `ProcessorAssetInfos::add_dependant` - `ProcessorAssetInfos::non_existent_dependants` - `AssetInfo::dependants_waiting_on_load` - `AssetInfo::dependants_waiting_on_recursive_dep_load` - `AssetInfos::loader_dependants` - `AssetInfos::remove_dependants_and_labels`
2024-10-20 18:55:17 +00:00
name = "minimizing"
path = "tests/window/minimizing.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add an example to test small window sizes (#3597) # Objective We keep getting issues where things break at small window sizes, e.g #3368 (caused by #3153), #3596 ('caused' by #3545) ## Solution - Add a test that we can make small windows. Currently, this fails on my machine with some quite scary vulkan errors: ``` 2022-01-08T22:55:13.770261Z ERROR wgpu_hal::vulkan::instance: VALIDATION [VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 (0x7cd0911d)] Validation Error: [ VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 ] Object 0: handle = 0x1adbd410a60, type = VK_OBJECT_TYPE_DEVICE; | MessageID = 0x7cd0911d | vkCreateSwapchainKHR() called with imageExtent = (225,60), which is outside the bounds returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR(): currentExtent = (225,56), minImageExtent = (225,56), maxImageExtent = (225,56). The Vulkan spec states: imageExtent must be between minImageExtent and maxImageExtent, inclusive, where minImageExtent and maxImageExtent are members of the VkSurfaceCapabilitiesKHR structure returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface (https://vulkan.lunarg.com/doc/view/1.2.198.1/windows/1.2-extensions/vkspec.html#VUID-VkSwapchainCreateInfoKHR-imageExtent-01274) 2022-01-08T22:55:13.770808Z ERROR wgpu_hal::vulkan::instance: objects: (type: DEVICE, hndl: 0x1adbd410a60, name: ?) 2022-01-08T22:55:13.787403Z ERROR wgpu_hal::vulkan::instance: VALIDATION [VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 (0x7cd0911d)] Validation Error: [ VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 ] Object 0: handle = 0x1adbd410a60, type = VK_OBJECT_TYPE_DEVICE; | MessageID = 0x7cd0911d | vkCreateSwapchainKHR() called with imageExtent = (225,56), which is outside the bounds returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR(): currentExtent = (225,52), minImageExtent = (225,52), maxImageExtent = (225,52). The Vulkan spec states: imageExtent must be between minImageExtent and maxImageExtent, inclusive, where minImageExtent and maxImageExtent are members of the VkSurfaceCapabilitiesKHR structure returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface (https://vulkan.lunarg.com/doc/view/1.2.198.1/windows/1.2-extensions/vkspec.html#VUID-VkSwapchainCreateInfoKHR-imageExtent-01274) ``` etc. This might be a new issue here, although I'm surprised it's vulkan giving this error; wgpu should stop it if this is illegal.
2022-04-26 22:15:24 +00:00
Use `en-us` locale for `typos` (#16037) # Objective Bevy seems to want to standardize on "American English" spellings. Not sure if this is laid out anywhere in writing, but see also #15947. While perusing the docs for `typos`, I noticed that it has a `locale` config option and tried it out. ## Solution Switch to `en-us` locale in the `typos` config and run `typos -w` ## Migration Guide The following methods or fields have been renamed from `*dependants*` to `*dependents*`. - `ProcessorAssetInfo::dependants` - `ProcessorAssetInfos::add_dependant` - `ProcessorAssetInfos::non_existent_dependants` - `AssetInfo::dependants_waiting_on_load` - `AssetInfo::dependants_waiting_on_recursive_dep_load` - `AssetInfos::loader_dependants` - `AssetInfos::remove_dependants_and_labels`
2024-10-20 18:55:17 +00:00
[package.metadata.example.minimizing]
Examples metadata in Cargo.toml (#4741) # Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - https://github.com/bevyengine/bevy-website/issues/299 for other ToDos Co-authored-by: Readme <github-actions@github.com>
2022-06-25 20:23:24 +00:00
hidden = true
Add an example to test small window sizes (#3597) # Objective We keep getting issues where things break at small window sizes, e.g #3368 (caused by #3153), #3596 ('caused' by #3545) ## Solution - Add a test that we can make small windows. Currently, this fails on my machine with some quite scary vulkan errors: ``` 2022-01-08T22:55:13.770261Z ERROR wgpu_hal::vulkan::instance: VALIDATION [VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 (0x7cd0911d)] Validation Error: [ VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 ] Object 0: handle = 0x1adbd410a60, type = VK_OBJECT_TYPE_DEVICE; | MessageID = 0x7cd0911d | vkCreateSwapchainKHR() called with imageExtent = (225,60), which is outside the bounds returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR(): currentExtent = (225,56), minImageExtent = (225,56), maxImageExtent = (225,56). The Vulkan spec states: imageExtent must be between minImageExtent and maxImageExtent, inclusive, where minImageExtent and maxImageExtent are members of the VkSurfaceCapabilitiesKHR structure returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface (https://vulkan.lunarg.com/doc/view/1.2.198.1/windows/1.2-extensions/vkspec.html#VUID-VkSwapchainCreateInfoKHR-imageExtent-01274) 2022-01-08T22:55:13.770808Z ERROR wgpu_hal::vulkan::instance: objects: (type: DEVICE, hndl: 0x1adbd410a60, name: ?) 2022-01-08T22:55:13.787403Z ERROR wgpu_hal::vulkan::instance: VALIDATION [VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 (0x7cd0911d)] Validation Error: [ VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 ] Object 0: handle = 0x1adbd410a60, type = VK_OBJECT_TYPE_DEVICE; | MessageID = 0x7cd0911d | vkCreateSwapchainKHR() called with imageExtent = (225,56), which is outside the bounds returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR(): currentExtent = (225,52), minImageExtent = (225,52), maxImageExtent = (225,52). The Vulkan spec states: imageExtent must be between minImageExtent and maxImageExtent, inclusive, where minImageExtent and maxImageExtent are members of the VkSurfaceCapabilitiesKHR structure returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface (https://vulkan.lunarg.com/doc/view/1.2.198.1/windows/1.2-extensions/vkspec.html#VUID-VkSwapchainCreateInfoKHR-imageExtent-01274) ``` etc. This might be a new issue here, although I'm surprised it's vulkan giving this error; wgpu should stop it if this is illegal.
2022-04-26 22:15:24 +00:00
Add window resizing example (#5813) # Objective - Adopted from #3836 - Example showcases how to request a new resolution - Example showcases how to react to resolution changes Co-authored-by: Andreas Weibye <13300393+Weibye@users.noreply.github.com>
2022-08-29 23:56:43 +00:00
[[example]]
name = "window_resizing"
path = "examples/window/window_resizing.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Add window resizing example (#5813) # Objective - Adopted from #3836 - Example showcases how to request a new resolution - Example showcases how to react to resolution changes Co-authored-by: Andreas Weibye <13300393+Weibye@users.noreply.github.com>
2022-08-29 23:56:43 +00:00
Expand `FallbackImage` to include a `GpuImage` for each possible `TextureViewDimension` (#6974) # Objective Fixes #6920 ## Solution From the issue discussion: > From looking at the `AsBindGroup` derive macro implementation, the fallback image's `TextureView` is used when the binding's `Option<Handle<Image>>` is `None`. Because this relies on already having a view that matches the desired binding dimensions, I think the solution will require creating a separate `GpuImage` for each possible `TextureViewDimension`. --- ## Changelog Users can now rely on `FallbackImage` to work with a texture binding of any dimension.
2023-06-19 22:56:25 +00:00
[[example]]
name = "fallback_image"
path = "examples/shader/fallback_image.rs"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
doc-scrape-examples = true
Expand `FallbackImage` to include a `GpuImage` for each possible `TextureViewDimension` (#6974) # Objective Fixes #6920 ## Solution From the issue discussion: > From looking at the `AsBindGroup` derive macro implementation, the fallback image's `TextureView` is used when the binding's `Option<Handle<Image>>` is `None`. Because this relies on already having a view that matches the desired binding dimensions, I think the solution will require creating a separate `GpuImage` for each possible `TextureViewDimension`. --- ## Changelog Users can now rely on `FallbackImage` to work with a texture binding of any dimension.
2023-06-19 22:56:25 +00:00
Implement minimal reflection probes (fixed macOS, iOS, and Android). (#11366) This pull request re-submits #10057, which was backed out for breaking macOS, iOS, and Android. I've tested this version on macOS and Android and on the iOS simulator. # Objective This pull request implements *reflection probes*, which generalize environment maps to allow for multiple environment maps in the same scene, each of which has an axis-aligned bounding box. This is a standard feature of physically-based renderers and was inspired by [the corresponding feature in Blender's Eevee renderer]. ## Solution This is a minimal implementation of reflection probes that allows artists to define cuboid bounding regions associated with environment maps. For every view, on every frame, a system builds up a list of the nearest 4 reflection probes that are within the view's frustum and supplies that list to the shader. The PBR fragment shader searches through the list, finds the first containing reflection probe, and uses it for indirect lighting, falling back to the view's environment map if none is found. Both forward and deferred renderers are fully supported. A reflection probe is an entity with a pair of components, *LightProbe* and *EnvironmentMapLight* (as well as the standard *SpatialBundle*, to position it in the world). The *LightProbe* component (along with the *Transform*) defines the bounding region, while the *EnvironmentMapLight* component specifies the associated diffuse and specular cubemaps. A frequent question is "why two components instead of just one?" The advantages of this setup are: 1. It's readily extensible to other types of light probes, in particular *irradiance volumes* (also known as ambient cubes or voxel global illumination), which use the same approach of bounding cuboids. With a single component that applies to both reflection probes and irradiance volumes, we can share the logic that implements falloff and blending between multiple light probes between both of those features. 2. It reduces duplication between the existing *EnvironmentMapLight* and these new reflection probes. Systems can treat environment maps attached to cameras the same way they treat environment maps applied to reflection probes if they wish. Internally, we gather up all environment maps in the scene and place them in a cubemap array. At present, this means that all environment maps must have the same size, mipmap count, and texture format. A warning is emitted if this restriction is violated. We could potentially relax this in the future as part of the automatic mipmap generation work, which could easily do texture format conversion as part of its preprocessing. An easy way to generate reflection probe cubemaps is to bake them in Blender and use the `export-blender-gi` tool that's part of the [`bevy-baked-gi`] project. This tool takes a `.blend` file containing baked cubemaps as input and exports cubemap images, pre-filtered with an embedded fork of the [glTF IBL Sampler], alongside a corresponding `.scn.ron` file that the scene spawner can use to recreate the reflection probes. Note that this is intentionally a minimal implementation, to aid reviewability. Known issues are: * Reflection probes are basically unsupported on WebGL 2, because WebGL 2 has no cubemap arrays. (Strictly speaking, you can have precisely one reflection probe in the scene if you have no other cubemaps anywhere, but this isn't very useful.) * Reflection probes have no falloff, so reflections will abruptly change when objects move from one bounding region to another. * As mentioned before, all cubemaps in the world of a given type (diffuse or specular) must have the same size, format, and mipmap count. Future work includes: * Blending between multiple reflection probes. * A falloff/fade-out region so that reflected objects disappear gradually instead of vanishing all at once. * Irradiance volumes for voxel-based global illumination. This should reuse much of the reflection probe logic, as they're both GI techniques based on cuboid bounding regions. * Support for WebGL 2, by breaking batches when reflection probes are used. These issues notwithstanding, I think it's best to land this with roughly the current set of functionality, because this patch is useful as is and adding everything above would make the pull request significantly larger and harder to review. --- ## Changelog ### Added * A new *LightProbe* component is available that specifies a bounding region that an *EnvironmentMapLight* applies to. The combination of a *LightProbe* and an *EnvironmentMapLight* offers *reflection probe* functionality similar to that available in other engines. [the corresponding feature in Blender's Eevee renderer]: https://docs.blender.org/manual/en/latest/render/eevee/light_probes/reflection_cubemaps.html [`bevy-baked-gi`]: https://github.com/pcwalton/bevy-baked-gi [glTF IBL Sampler]: https://github.com/KhronosGroup/glTF-IBL-Sampler
2024-01-19 07:33:52 +00:00
[[example]]
name = "reflection_probes"
path = "examples/3d/reflection_probes.rs"
doc-scrape-examples = true
[package.metadata.example.reflection_probes]
name = "Reflection Probes"
description = "Demonstrates reflection probes"
category = "3D Rendering"
wasm = false
Expand `FallbackImage` to include a `GpuImage` for each possible `TextureViewDimension` (#6974) # Objective Fixes #6920 ## Solution From the issue discussion: > From looking at the `AsBindGroup` derive macro implementation, the fallback image's `TextureView` is used when the binding's `Option<Handle<Image>>` is `None`. Because this relies on already having a view that matches the desired binding dimensions, I think the solution will require creating a separate `GpuImage` for each possible `TextureViewDimension`. --- ## Changelog Users can now rely on `FallbackImage` to work with a texture binding of any dimension.
2023-06-19 22:56:25 +00:00
[package.metadata.example.fallback_image]
hidden = true
Add window resizing example (#5813) # Objective - Adopted from #3836 - Example showcases how to request a new resolution - Example showcases how to react to resolution changes Co-authored-by: Andreas Weibye <13300393+Weibye@users.noreply.github.com>
2022-08-29 23:56:43 +00:00
[package.metadata.example.window_resizing]
name = "Window Resizing"
description = "Demonstrates resizing and responding to resizing a window"
category = "Window"
wasm = true
Add UI Materials (#9506) # Objective - Add Ui Materials so that UI can render more complex and animated widgets. - Fixes #5607 ## Solution - Create a UiMaterial trait for specifying a Shader Asset and Bind Group Layout/Data. - Create a pipeline for rendering these Materials inside the Ui layout/tree. - Create a MaterialNodeBundle for simple spawning. ## Changelog - Created a `UiMaterial` trait for specifying a Shader asset and Bind Group. - Created a `UiMaterialPipeline` for rendering said Materials. - Added Example [`ui_material` ](https://github.com/MarkusTheOrt/bevy/blob/ui_material/examples/ui/ui_material.rs) for example usage. - Created [`UiVertexOutput`](https://github.com/MarkusTheOrt/bevy/blob/ui_material/crates/bevy_ui/src/render/ui_vertex_output.wgsl) export as VertexData for shaders. - Created [`material_ui`](https://github.com/MarkusTheOrt/bevy/blob/ui_material/crates/bevy_ui/src/render/ui_material.wgsl) shader as default for both Vertex and Fragment shaders. --------- Co-authored-by: ickshonpe <david.curthoys@googlemail.com> Co-authored-by: François <mockersf@gmail.com>
2023-11-03 22:33:01 +00:00
[[example]]
name = "ui_material"
path = "examples/ui/ui_material.rs"
doc-scrape-examples = true
[package.metadata.example.ui_material]
name = "UI Material"
description = "Demonstrates creating and using custom Ui materials"
category = "UI (User Interface)"
wasm = true
Cyclic splines (#14106) # Objective Fill a gap in the functionality of our curve constructions by allowing users to easily build cyclic curves from control data. ## Solution Here I opted for something lightweight and discoverable. There is a new `CyclicCubicGenerator` trait with a method `to_curve_cyclic` which uses splines' control data to create curves that are cyclic. For now, its signature is exactly like that of `CubicGenerator` — `to_curve_cyclic` just yields a `CubicCurve`: ```rust /// Implement this on cubic splines that can generate a cyclic cubic curve from their spline parameters. /// /// This makes sense only when the control data can be interpreted cyclically. pub trait CyclicCubicGenerator<P: VectorSpace> { /// Build a cyclic [`CubicCurve`] by computing the interpolation coefficients for each curve segment. fn to_curve_cyclic(&self) -> CubicCurve<P>; } ``` This trait has been implemented for `CubicHermite`, `CubicCardinalSpline`, `CubicBSpline`, and `LinearSpline`: <img width="753" alt="Screenshot 2024-07-01 at 8 58 27 PM" src="https://github.com/bevyengine/bevy/assets/2975848/69ae0802-3b78-4fb9-b73a-6f842cf3b33c"> <img width="628" alt="Screenshot 2024-07-01 at 9 00 14 PM" src="https://github.com/bevyengine/bevy/assets/2975848/2992175a-a96c-40fc-b1a1-5206c3572cde"> <img width="606" alt="Screenshot 2024-07-01 at 8 59 36 PM" src="https://github.com/bevyengine/bevy/assets/2975848/9e99eb3a-dbe6-42da-886c-3d3e00410d03"> <img width="603" alt="Screenshot 2024-07-01 at 8 59 01 PM" src="https://github.com/bevyengine/bevy/assets/2975848/d037bc0c-396a-43af-ab5c-fad9a29417ef"> (Each type pictured respectively with the control points rendered as green spheres; tangents not pictured in the case of the Hermite spline.) These curves are all parametrized so that the output of `to_curve` and the output of `to_curve_cyclic` are similar. For instance, in `CubicCardinalSpline`, the first output segment is a curve segment joining the first and second control points in each, although it is constructed differently. In the other cases, the segments from `to_curve` are a subset of those in `to_curve_cyclic`, with the new segments appearing at the end. ## Testing I rendered cyclic splines from control data and made sure they looked reasonable. Existing tests are intact for splines where previous code was modified. (Note that the coefficient computation for cyclic spline segments is almost verbatim identical to that of their non-cyclic counterparts.) The Bezier benchmarks also look fine. --- ## Changelog - Added `CyclicCubicGenerator` trait to `bevy_math::cubic_splines` for creating cyclic curves from control data. - Implemented `CyclicCubicGenerator` for `CubicHermite`, `CubicCardinalSpline`, `CubicBSpline`, and `LinearSpline`. - `bevy_math` now depends on `itertools`. --- ## Discussion ### Design decisions The biggest thing here is just the approach taken in the first place: namely, the cyclic constructions use new methods on the same old structs. This choice was made to reduce friction and increase discoverability but also because creating new ones just seemed unnecessary: the underlying data would have been the same, so creating something like "`CyclicCubicBSpline`" whose internally-held control data is regarded as cyclic in nature doesn't really accomplish much — the end result for the user is basically the same either way. Similarly, I don't presently see a pressing need for `to_curve_cyclic` to output something other than a `CubicCurve`, although changing this in the future may be useful. See below. A notable omission here is that `CyclicCubicGenerator` is not implemented for `CubicBezier`. This is not a gap waiting to be filled — `CubicBezier` just doesn't have enough data to join its start with its end without just making up the requisite control points wholesale. In all the cases where `CyclicCubicGenerator` has been implemented here, the fashion in which the ends are connected is quite natural and follows the semantics of the associated spline construction. ### Future direction There are two main things here: 1. We should investigate whether we should do something similar for NURBS. I just don't know that much about NURBS at the moment, so I regarded this as out of scope for the PR. 2. We may eventually want to change the output type of `CyclicCubicGenerator::to_curve_cyclic` to a type which reifies the cyclic nature of the curve output. This wasn't done in this PR because I'm unsure how much value a type-level guarantee of cyclicity actually has, but if some useful features make sense only in the case of cyclic curves, this might be worth pursuing.
2024-07-17 13:02:31 +00:00
[[example]]
name = "cubic_splines"
path = "examples/math/cubic_splines.rs"
doc-scrape-examples = true
[package.metadata.example.cubic_splines]
name = "Cubic Splines"
description = "Exhibits different modes of constructing cubic curves using splines"
category = "Math"
wasm = true
Dedicated primitive example (#11697) I just implemented this to record a video for the new blog post, but I figured it would also make a good dedicated example. This also allows us to remove a lot of code from the 2d/3d gizmo examples since it supersedes this portion of code. Depends on: https://github.com/bevyengine/bevy/pull/11699
2024-02-14 16:55:44 +00:00
[[example]]
name = "render_primitives"
path = "examples/math/render_primitives.rs"
doc-scrape-examples = true
[package.metadata.example.render_primitives]
name = "Rendering Primitives"
description = "Shows off rendering for all math primitives as both Meshes and Gizmos"
category = "Math"
wasm = true
Create a primitive sampling showcase example (#13519) # Objective - Show + Visually Test that 3D primitive sampling works - Make an example that looks nice. ## Solution - Added a `sampling_primitives` examples which shows all the 3D primitives being sampled, with a firefly aesthetic. ![image](https://github.com/bevyengine/bevy/assets/27301845/f882438b-2c72-48b1-a6e9-162a80c4273e) ## Testing - `cargo run --example sampling_primitives` - Haven't tested WASM. ## Changelog ### Added - Added a new example, `sampling_primitives`, to showcase all the 3D sampleable primitives. ## Additional notes: This example borrowed a bunch of code from the other sampling example, by @mweatherley. In future updates this example should be updated with new 3D primitives as they become sampleable. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Joona Aalto <jondolf.dev@gmail.com>
2024-05-27 16:44:52 +00:00
# Math
[[example]]
name = "sampling_primitives"
path = "examples/math/sampling_primitives.rs"
doc-scrape-examples = true
[package.metadata.example.sampling_primitives]
name = "Sampling Primitives"
description = "Demonstrates all the primitives which can be sampled."
category = "Math"
wasm = true
Custom primitives example (#13795) # Objective - Add a new example showcasing how to add custom primitives and what you can do with them. ## Solution - Added a new example `custom_primitives` with a 2D heart shape primitive highlighting - `Bounded2d` by implementing and visualising bounding shapes, - `Measured2d` by implementing it, - `Meshable` to show the shape on the screen - The example also includes an `Extrusion<Heart>` implementing - `Measured3d`, - `Bounded3d` using the `BoundedExtrusion` trait and - meshing using the `Extrudable` trait. ## Additional information Here are two images of the heart and its extrusion: ![image_2024-06-10_194631194](https://github.com/bevyengine/bevy/assets/62256001/53f1836c-df74-4ba6-85e9-fabdafa94c66) ![Screenshot 2024-06-10 194609](https://github.com/bevyengine/bevy/assets/62256001/b1630e71-6e94-4293-b7b5-da8d9cc98faf) --------- Co-authored-by: Jakub Marcowski <37378746+Chubercik@users.noreply.github.com>
2024-06-10 21:15:21 +00:00
[[example]]
name = "custom_primitives"
path = "examples/math/custom_primitives.rs"
doc-scrape-examples = true
[package.metadata.example.custom_primitives]
name = "Custom Primitives"
description = "Demonstrates how to add custom primitives and useful traits for them."
category = "Math"
wasm = true
Example for random sampling (#13507) # Objective We introduced a bunch of neat random sampling stuff in this release; we should do a good job of showing people how to use it, and writing examples is part of this. ## Solution A new Math example, `random_sampling`, shows off the `ShapeSample` API functionality. For the moment, it renders a cube and allows the user to sample points from its interior or boundary in sets of either 1 or 100: <img width="1440" alt="Screenshot 2024-05-25 at 1 16 08 PM" src="https://github.com/bevyengine/bevy/assets/2975848/9cb6f53f-c89a-42c2-8907-b11d294c402a"> On the level of code, these are reflected by two ways of using `ShapeSample`: ```rust // Get a single random Vec3: let sample: Vec3 = match *mode { Mode::Interior => shape.0.sample_interior(rng), Mode::Boundary => shape.0.sample_boundary(rng), }; ``` ```rust // Get 100 random Vec3s: let samples: Vec<Vec3> = match *mode { Mode::Interior => { let dist = shape.0.interior_dist(); dist.sample_iter(&mut rng).take(100).collect() } Mode::Boundary => { let dist = shape.0.boundary_dist(); dist.sample_iter(&mut rng).take(100).collect() } }; ``` ## Testing Run the example! ## Discussion Maybe in the future it would be nice to show off all of the different shapes that we have implemented `ShapeSample` for, but I wanted to start just by demonstrating the functionality. Here, I chose a cube because it's simple and because it looks good rendered transparently with backface culling disabled.
2024-05-27 13:46:11 +00:00
[[example]]
name = "random_sampling"
path = "examples/math/random_sampling.rs"
doc-scrape-examples = true
[package.metadata.example.random_sampling]
name = "Random Sampling"
description = "Demonstrates how to sample random points from mathematical primitives"
category = "Math"
wasm = true
Stable interpolation and smooth following (#13741) # Objective Partially address #13408 Rework of #13613 Unify the very nice forms of interpolation specifically present in `bevy_math` under a shared trait upon which further behavior can be based. The ideas in this PR were prompted by [Lerp smoothing is broken by Freya Holmer](https://www.youtube.com/watch?v=LSNQuFEDOyQ). ## Solution There is a new trait `StableInterpolate` in `bevy_math::common_traits` which enshrines a quite-specific notion of interpolation with a lot of guarantees: ```rust /// A type with a natural interpolation that provides strong subdivision guarantees. /// /// Although the only required method is `interpolate_stable`, many things are expected of it: /// /// 1. The notion of interpolation should follow naturally from the semantics of the type, so /// that inferring the interpolation mode from the type alone is sensible. /// /// 2. The interpolation recovers something equivalent to the starting value at `t = 0.0` /// and likewise with the ending value at `t = 1.0`. /// /// 3. Importantly, the interpolation must be *subdivision-stable*: for any interpolation curve /// between two (unnamed) values and any parameter-value pairs `(t0, p)` and `(t1, q)`, the /// interpolation curve between `p` and `q` must be the *linear* reparametrization of the original /// interpolation curve restricted to the interval `[t0, t1]`. /// /// The last of these conditions is very strong and indicates something like constant speed. It /// is called "subdivision stability" because it guarantees that breaking up the interpolation /// into segments and joining them back together has no effect. /// /// Here is a diagram depicting it: /// ```text /// top curve = u.interpolate_stable(v, t) /// /// t0 => p t1 => q /// |-------------|---------|-------------| /// 0 => u / \ 1 => v /// / \ /// / \ /// / linear \ /// / reparametrization \ /// / t = t0 * (1 - s) + t1 * s \ /// / \ /// |-------------------------------------| /// 0 => p 1 => q /// /// bottom curve = p.interpolate_stable(q, s) /// ``` /// /// Note that some common forms of interpolation do not satisfy this criterion. For example, /// [`Quat::lerp`] and [`Rot2::nlerp`] are not subdivision-stable. /// /// Furthermore, this is not to be used as a general trait for abstract interpolation. /// Consumers rely on the strong guarantees in order for behavior based on this trait to be /// well-behaved. /// /// [`Quat::lerp`]: crate::Quat::lerp /// [`Rot2::nlerp`]: crate::Rot2::nlerp pub trait StableInterpolate: Clone { /// Interpolate between this value and the `other` given value using the parameter `t`. /// Note that the parameter `t` is not necessarily clamped to lie between `0` and `1`. /// When `t = 0.0`, `self` is recovered, while `other` is recovered at `t = 1.0`, /// with intermediate values lying between the two. fn interpolate_stable(&self, other: &Self, t: f32) -> Self; } ``` This trait has a blanket implementation over `NormedVectorSpace`, where `lerp` is used, along with implementations for `Rot2`, `Quat`, and the direction types using variants of `slerp`. Other areas may choose to implement this trait in order to hook into its functionality, but the stringent requirements must actually be met. This trait bears no direct relationship with `bevy_animation`'s `Animatable` trait, although they may choose to use `interpolate_stable` in their trait implementations if they wish, as both traits involve type-inferred interpolations of the same kind. `StableInterpolate` is not a supertrait of `Animatable` for a couple reasons: 1. Notions of interpolation in animation are generally going to be much more general than those allowed under these constraints. 2. Laying out these generalized interpolation notions is the domain of `bevy_animation` rather than of `bevy_math`. (Consider also that inferring interpolation from types is not universally desirable.) Similarly, this is not implemented on `bevy_color`'s color types, although their current mixing behavior does meet the conditions of the trait. As an aside, the subdivision-stability condition is of interest specifically for the [Curve RFC](https://github.com/bevyengine/rfcs/pull/80), where it also ensures a kind of stability for subsampling. Importantly, this trait ensures that the "smooth following" behavior defined in this PR behaves predictably: ```rust /// Smoothly nudge this value towards the `target` at a given decay rate. The `decay_rate` /// parameter controls how fast the distance between `self` and `target` decays relative to /// the units of `delta`; the intended usage is for `decay_rate` to generally remain fixed, /// while `delta` is something like `delta_time` from an updating system. This produces a /// smooth following of the target that is independent of framerate. /// /// More specifically, when this is called repeatedly, the result is that the distance between /// `self` and a fixed `target` attenuates exponentially, with the rate of this exponential /// decay given by `decay_rate`. /// /// For example, at `decay_rate = 0.0`, this has no effect. /// At `decay_rate = f32::INFINITY`, `self` immediately snaps to `target`. /// In general, higher rates mean that `self` moves more quickly towards `target`. /// /// # Example /// ``` /// # use bevy_math::{Vec3, StableInterpolate}; /// # let delta_time: f32 = 1.0 / 60.0; /// let mut object_position: Vec3 = Vec3::ZERO; /// let target_position: Vec3 = Vec3::new(2.0, 3.0, 5.0); /// // Decay rate of ln(10) => after 1 second, remaining distance is 1/10th /// let decay_rate = f32::ln(10.0); /// // Calling this repeatedly will move `object_position` towards `target_position`: /// object_position.smooth_nudge(&target_position, decay_rate, delta_time); /// ``` fn smooth_nudge(&mut self, target: &Self, decay_rate: f32, delta: f32) { self.interpolate_stable_assign(target, 1.0 - f32::exp(-decay_rate * delta)); } ``` As the documentation indicates, the intention is for this to be called in game update systems, and `delta` would be something like `Time::delta_seconds` in Bevy, allowing positions, orientations, and so on to smoothly follow a target. A new example, `smooth_follow`, demonstrates a basic implementation of this, with a sphere smoothly following a sharply moving target: https://github.com/bevyengine/bevy/assets/2975848/7124b28b-6361-47e3-acf7-d1578ebd0347 ## Testing Tested by running the example with various parameters.
2024-06-10 12:50:59 +00:00
[[example]]
name = "smooth_follow"
Moves smooth_follow to movement dir (#14249) # Objective - Moves the smooth_follow.rs into movement directory in examples - Fixes #14241 ## Solution - Move the smooth_follow.rs to movement dir in examples.
2024-07-09 18:22:47 +00:00
path = "examples/movement/smooth_follow.rs"
Stable interpolation and smooth following (#13741) # Objective Partially address #13408 Rework of #13613 Unify the very nice forms of interpolation specifically present in `bevy_math` under a shared trait upon which further behavior can be based. The ideas in this PR were prompted by [Lerp smoothing is broken by Freya Holmer](https://www.youtube.com/watch?v=LSNQuFEDOyQ). ## Solution There is a new trait `StableInterpolate` in `bevy_math::common_traits` which enshrines a quite-specific notion of interpolation with a lot of guarantees: ```rust /// A type with a natural interpolation that provides strong subdivision guarantees. /// /// Although the only required method is `interpolate_stable`, many things are expected of it: /// /// 1. The notion of interpolation should follow naturally from the semantics of the type, so /// that inferring the interpolation mode from the type alone is sensible. /// /// 2. The interpolation recovers something equivalent to the starting value at `t = 0.0` /// and likewise with the ending value at `t = 1.0`. /// /// 3. Importantly, the interpolation must be *subdivision-stable*: for any interpolation curve /// between two (unnamed) values and any parameter-value pairs `(t0, p)` and `(t1, q)`, the /// interpolation curve between `p` and `q` must be the *linear* reparametrization of the original /// interpolation curve restricted to the interval `[t0, t1]`. /// /// The last of these conditions is very strong and indicates something like constant speed. It /// is called "subdivision stability" because it guarantees that breaking up the interpolation /// into segments and joining them back together has no effect. /// /// Here is a diagram depicting it: /// ```text /// top curve = u.interpolate_stable(v, t) /// /// t0 => p t1 => q /// |-------------|---------|-------------| /// 0 => u / \ 1 => v /// / \ /// / \ /// / linear \ /// / reparametrization \ /// / t = t0 * (1 - s) + t1 * s \ /// / \ /// |-------------------------------------| /// 0 => p 1 => q /// /// bottom curve = p.interpolate_stable(q, s) /// ``` /// /// Note that some common forms of interpolation do not satisfy this criterion. For example, /// [`Quat::lerp`] and [`Rot2::nlerp`] are not subdivision-stable. /// /// Furthermore, this is not to be used as a general trait for abstract interpolation. /// Consumers rely on the strong guarantees in order for behavior based on this trait to be /// well-behaved. /// /// [`Quat::lerp`]: crate::Quat::lerp /// [`Rot2::nlerp`]: crate::Rot2::nlerp pub trait StableInterpolate: Clone { /// Interpolate between this value and the `other` given value using the parameter `t`. /// Note that the parameter `t` is not necessarily clamped to lie between `0` and `1`. /// When `t = 0.0`, `self` is recovered, while `other` is recovered at `t = 1.0`, /// with intermediate values lying between the two. fn interpolate_stable(&self, other: &Self, t: f32) -> Self; } ``` This trait has a blanket implementation over `NormedVectorSpace`, where `lerp` is used, along with implementations for `Rot2`, `Quat`, and the direction types using variants of `slerp`. Other areas may choose to implement this trait in order to hook into its functionality, but the stringent requirements must actually be met. This trait bears no direct relationship with `bevy_animation`'s `Animatable` trait, although they may choose to use `interpolate_stable` in their trait implementations if they wish, as both traits involve type-inferred interpolations of the same kind. `StableInterpolate` is not a supertrait of `Animatable` for a couple reasons: 1. Notions of interpolation in animation are generally going to be much more general than those allowed under these constraints. 2. Laying out these generalized interpolation notions is the domain of `bevy_animation` rather than of `bevy_math`. (Consider also that inferring interpolation from types is not universally desirable.) Similarly, this is not implemented on `bevy_color`'s color types, although their current mixing behavior does meet the conditions of the trait. As an aside, the subdivision-stability condition is of interest specifically for the [Curve RFC](https://github.com/bevyengine/rfcs/pull/80), where it also ensures a kind of stability for subsampling. Importantly, this trait ensures that the "smooth following" behavior defined in this PR behaves predictably: ```rust /// Smoothly nudge this value towards the `target` at a given decay rate. The `decay_rate` /// parameter controls how fast the distance between `self` and `target` decays relative to /// the units of `delta`; the intended usage is for `decay_rate` to generally remain fixed, /// while `delta` is something like `delta_time` from an updating system. This produces a /// smooth following of the target that is independent of framerate. /// /// More specifically, when this is called repeatedly, the result is that the distance between /// `self` and a fixed `target` attenuates exponentially, with the rate of this exponential /// decay given by `decay_rate`. /// /// For example, at `decay_rate = 0.0`, this has no effect. /// At `decay_rate = f32::INFINITY`, `self` immediately snaps to `target`. /// In general, higher rates mean that `self` moves more quickly towards `target`. /// /// # Example /// ``` /// # use bevy_math::{Vec3, StableInterpolate}; /// # let delta_time: f32 = 1.0 / 60.0; /// let mut object_position: Vec3 = Vec3::ZERO; /// let target_position: Vec3 = Vec3::new(2.0, 3.0, 5.0); /// // Decay rate of ln(10) => after 1 second, remaining distance is 1/10th /// let decay_rate = f32::ln(10.0); /// // Calling this repeatedly will move `object_position` towards `target_position`: /// object_position.smooth_nudge(&target_position, decay_rate, delta_time); /// ``` fn smooth_nudge(&mut self, target: &Self, decay_rate: f32, delta: f32) { self.interpolate_stable_assign(target, 1.0 - f32::exp(-decay_rate * delta)); } ``` As the documentation indicates, the intention is for this to be called in game update systems, and `delta` would be something like `Time::delta_seconds` in Bevy, allowing positions, orientations, and so on to smoothly follow a target. A new example, `smooth_follow`, demonstrates a basic implementation of this, with a sphere smoothly following a sharply moving target: https://github.com/bevyengine/bevy/assets/2975848/7124b28b-6361-47e3-acf7-d1578ebd0347 ## Testing Tested by running the example with various parameters.
2024-06-10 12:50:59 +00:00
doc-scrape-examples = true
[package.metadata.example.smooth_follow]
name = "Smooth Follow"
description = "Demonstrates how to make an entity smoothly follow another using interpolation"
category = "Math"
wasm = true
Move gizmos examples in the separate folder (#11916) # Objective Move Gizmo examples into the separate directory Fixes #11899 --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Joona Aalto <jondolf.dev@gmail.com>
2024-02-21 20:16:25 +00:00
# Gizmos
[[example]]
name = "2d_gizmos"
path = "examples/gizmos/2d_gizmos.rs"
doc-scrape-examples = true
[package.metadata.example.2d_gizmos]
name = "2D Gizmos"
description = "A scene showcasing 2D gizmos"
category = "Gizmos"
wasm = true
[[example]]
name = "3d_gizmos"
path = "examples/gizmos/3d_gizmos.rs"
doc-scrape-examples = true
[package.metadata.example.3d_gizmos]
name = "3D Gizmos"
description = "A scene showcasing 3D gizmos"
category = "Gizmos"
wasm = true
Example for axes gizmos (#12299) # Objective - Follow-up to #12211 - Introduces an example project that demonstrates the implementation and behavior of `Gizmos::axes` for an entity with a `Transform` component. ## Solution In order to demonstrate how `Gizmo::axes` can be used and behaves in practice, we introduce an example of a simple scene containing a pair of cuboids locked in a grotesque, inscrutable dance: the two are repeatedly given random `Transform`s which they interpolate to, showing how the axes move with objects as they translate, rotate, and scale. <img width="1023" alt="Screenshot 2024-03-04 at 1 16 33 PM" src="https://github.com/bevyengine/bevy/assets/2975848/c1ff4794-6722-491c-8522-f59801645139"> On the implementation side, we demonstrate how to draw axes for entities, automatically sizing them according to their bounding boxes (so that the axes will be visible): ````rust fn draw_axes(mut gizmos: Gizmos, query: Query<(&Transform, &Aabb), With<ShowAxes>>) { for (&transform, &aabb) in &query { let length = aabb.half_extents.length(); gizmos.axes(transform, length); } } ```` --- ## Changelog - Created examples/gizmos/axes.rs. - Added 'axes' example to Cargo.toml.
2024-03-04 19:30:39 +00:00
[[example]]
name = "axes"
path = "examples/gizmos/axes.rs"
doc-scrape-examples = true
[package.metadata.example.axes]
name = "Axes"
description = "Demonstrates the function of axes gizmos"
category = "Gizmos"
wasm = true
Add basic light gizmos (#12228) # Objective - Part of #9400. - Add light gizmos for `SpotLight`, `PointLight` and `DirectionalLight`. ## Solution - Add a `ShowLightGizmo` and its related gizmo group and plugin, that shows a gizmo for all lights of an entities when inserted on it. Light display can also be toggled globally through the gizmo config in the same way it can already be done for `Aabb`s. - Add distinct segment setters for height and base one `Cone3dBuilder`. This allow having a properly rounded base without too much edges along the height. The doc comments explain how to ensure height and base connect when setting different values. Gizmo for the three light types without radius with the depth bias set to -1: ![without-radius](https://github.com/bevyengine/bevy/assets/18357657/699d0154-f367-4727-9b09-8b458d96a0e2) With Radius: ![with-radius](https://github.com/bevyengine/bevy/assets/18357657/f3af003e-dbba-427a-a305-c5cc1676e340) Possible future improvements: - Add a billboarded sprite with a distinct sprite for each light type. - Display the intensity of the light somehow (no idea how to represent that apart from some text). --- ## Changelog ### Added - The new `ShowLightGizmo`, part of the `LightGizmoPlugin` and configurable globally with `LightGizmoConfigGroup`, allows drawing gizmo for `PointLight`, `SpotLight` and `DirectionalLight`. The gizmos color behavior can be controlled with the `LightGizmoColor` member of `ShowLightGizmo` and `LightGizmoConfigGroup`. - The cone gizmo builder (`Cone3dBuilder`) now allows setting a differing number of segments for the base and height. --------- Co-authored-by: Gino Valente <49806985+MrGVSV@users.noreply.github.com>
2024-03-03 18:50:46 +00:00
[[example]]
name = "light_gizmos"
path = "examples/gizmos/light_gizmos.rs"
doc-scrape-examples = true
[package.metadata.example.light_gizmos]
name = "Light Gizmos"
description = "A scene showcasing light gizmos"
category = "Gizmos"
wasm = true
Fps overlay (#12382) # Objective - Part of #12351 - Add fps overlay ## Solution - Create `FpsOverlayPlugin` - Allow for configuration through resource `FpsOverlayConfig` - Allow for configuration during runtime ### Preview on default settings ![20240308_22h23m25s_grim](https://github.com/bevyengine/bevy/assets/62356462/33d3d7a9-435e-4e0b-9814-d3274e779a69) --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2024-03-11 19:26:14 +00:00
[[example]]
name = "fps_overlay"
path = "examples/dev_tools/fps_overlay.rs"
doc-scrape-examples = true
required-features = ["bevy_dev_tools"]
2D top-down camera example (#12720) # Objective This PR addresses the 2D part of #12658. I plan to separate the examples and make one PR per camera example. ## Solution Added a new top-down example composed of: - [x] Player keyboard movements - [x] UI for keyboard instructions - [x] Colors and bloom effect to see the movement of the player - [x] Camera smooth movement towards the player (lerp) ## Testing ```bash cargo run --features="wayland,bevy/dynamic_linking" --example 2d_top_down_camera ``` https://github.com/bevyengine/bevy/assets/10638479/95db0587-e5e0-4f55-be11-97444b795793
2024-06-10 12:33:48 +00:00
[[example]]
name = "2d_top_down_camera"
path = "examples/camera/2d_top_down_camera.rs"
doc-scrape-examples = true
[package.metadata.example.2d_top_down_camera]
name = "2D top-down camera"
description = "A 2D top-down camera smoothly following player movements"
category = "Camera"
wasm = true
Add first person view model example (#13828) # Objective A very common way to organize a first-person view is to split it into two kinds of models: - The *view model* is the model that represents the player's body. - The *world model* is everything else. The reason for this distinction is that these two models should be rendered with different FOVs. The view model is typically designed and animated with a very specific FOV in mind, so it is generally *fixed* and cannot be changed by a player. The world model, on the other hand, should be able to change its FOV to accommodate the player's preferences for the following reasons: - *Accessibility*: How prone is the player to motion sickness? A wider FOV can help. - *Tactical preference*: Does the player want to see more of the battlefield? Or have a more zoomed-in view for precision aiming? - *Physical considerations*: How well does the in-game FOV match the player's real-world FOV? Are they sitting in front of a monitor or playing on a TV in the living room? How big is the screen? ## Solution I've added an example implementing the described setup as follows. The `Player` is an entity holding two cameras, one for each model. The view model camera has a fixed FOV of 70 degrees, while the world model camera has a variable FOV that can be changed by the player. I use different `RenderLayers` to select what to render. - The world model camera has no explicit `RenderLayers` component, so it uses the layer 0. All static objects in the scene are also on layer 0 for the same reason. - The view model camera has a `RenderLayers` component with layer 1, so it only renders objects explicitly assigned to layer 1. The arm of the player is one such object. The order of the view model camera is additionally bumped to 1 to ensure it renders on top of the world model. - The light source in the scene must illuminate both the view model and the world model, so it is assigned to both layers 0 and 1. To better see the effect, the player can move the camera by dragging their mouse and change the world model's FOV with the arrow keys. The arrow up key maps to "decrease FOV" and the arrow down key maps to "increase FOV". This sounds backwards on paper, but is more intuitive when actually changing the FOV in-game since a decrease in FOV looks like a zoom-in. I intentionally do not allow changing the view model's FOV even though it would be illustrative because that would be an anti-pattern and bloat the code a bit. The example is called `first_person_view_model` and not just `first_person` because I want to highlight that this is not a simple flycam, but actually renders the player. ## Testing Default FOV: <img width="1392" alt="image" src="https://github.com/bevyengine/bevy/assets/9047632/8c2e804f-fac2-48c7-8a22-d85af999dfb2"> Decreased FOV: <img width="1392" alt="image" src="https://github.com/bevyengine/bevy/assets/9047632/1733b3e5-f583-4214-a454-3554e3cbd066"> Increased FOV: <img width="1392" alt="image" src="https://github.com/bevyengine/bevy/assets/9047632/0b0640e6-5743-46f6-a79a-7181ba9678e8"> Note that the white bar on the right represents the player's arm, which is more obvious in-game because you can move the camera around. The box on top is there to make sure that the view model is receiving shadows. I tested only on macOS. --- ## Changelog I don't think new examples go in here, do they? ## Caveat The solution used here was implemented with help by @robtfm on [Discord](https://discord.com/channels/691052431525675048/866787577687310356/1241019224491561000): > shadow maps are specific to lights, not to layers > if you want shadows from some meshes that are not visible, you could have light on layer 1+2, meshes on layer 2, camera on layer 1 (for example) > but this might change in future, it's not exactly an intended feature In other words, the example code as-is is not guaranteed to work in the future. I want to bring this up because the use-case presented here is extremely common in first-person games and important for accessibility. It would be good to have a blessed and easy way of how to achieve it. I'm also not happy about how I get the `perspective` variable in `change_fov`. Very open to suggestions :) ## Related issues - Addresses parts of #12658 - Addresses parts of #12588 --------- Co-authored-by: Pascal Hertleif <killercup@gmail.com>
2024-06-17 15:03:31 +00:00
[[example]]
name = "first_person_view_model"
path = "examples/camera/first_person_view_model.rs"
doc-scrape-examples = true
[package.metadata.example.first_person_view_model]
name = "First person view model"
description = "A first-person camera that uses a world model and a view model with different field of views (FOV)"
category = "Camera"
wasm = true
Add examples for orthographic and perspective zoom (#15092) # Objective Add examples for zooming (and orbiting) orthographic and perspective cameras. I'm pretty green with 3D, so please treat with suspicion! I note that if/when #15075 is merged, `.scale` will go away so this example uses `.scaling_mode`. Closes #2580
2024-09-09 23:30:52 +00:00
[[example]]
name = "projection_zoom"
path = "examples/camera/projection_zoom.rs"
doc-scrape-examples = true
[package.metadata.example.projection_zoom]
name = "Projection Zoom"
Split zoom/orbit into separate examples (#15135) # Objective As previously discussed, split camera zoom and orbiting examples to keep things less cluttered. See discussion on #15092 for context.
2024-09-10 23:40:48 +00:00
description = "Shows how to zoom orthographic and perspective projection cameras."
category = "Camera"
wasm = true
[[example]]
name = "camera_orbit"
path = "examples/camera/camera_orbit.rs"
doc-scrape-examples = true
[package.metadata.example.camera_orbit]
name = "Camera Orbit"
description = "Shows how to orbit a static scene using pitch, yaw, and roll."
Add examples for orthographic and perspective zoom (#15092) # Objective Add examples for zooming (and orbiting) orthographic and perspective cameras. I'm pretty green with 3D, so please treat with suspicion! I note that if/when #15075 is merged, `.scale` will go away so this example uses `.scaling_mode`. Closes #2580
2024-09-09 23:30:52 +00:00
category = "Camera"
wasm = true
Screen shake example (#15567) # Objective Closes https://github.com/bevyengine/bevy/issues/15564 ## Solution Adds a screen shake example. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2024-10-07 21:14:07 +00:00
[[example]]
name = "2d_screen_shake"
path = "examples/camera/2d_screen_shake.rs"
doc-scrape-examples = true
[package.metadata.example.2d_screen_shake]
name = "Screen Shake"
description = "A simple 2D screen shake effect"
category = "Camera"
wasm = true
Fps overlay (#12382) # Objective - Part of #12351 - Add fps overlay ## Solution - Create `FpsOverlayPlugin` - Allow for configuration through resource `FpsOverlayConfig` - Allow for configuration during runtime ### Preview on default settings ![20240308_22h23m25s_grim](https://github.com/bevyengine/bevy/assets/62356462/33d3d7a9-435e-4e0b-9814-d3274e779a69) --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2024-03-11 19:26:14 +00:00
[package.metadata.example.fps_overlay]
name = "FPS overlay"
description = "Demonstrates FPS overlay"
category = "Dev tools"
wasm = true
Implement visibility ranges, also known as hierarchical levels of detail (HLODs). (#12916) Implement visibility ranges, also known as hierarchical levels of detail (HLODs). This commit introduces a new component, `VisibilityRange`, which allows developers to specify camera distances in which meshes are to be shown and hidden. Hiding meshes happens early in the rendering pipeline, so this feature can be used for level of detail optimization. Additionally, this feature is properly evaluated per-view, so different views can show different levels of detail. This feature differs from proper mesh LODs, which can be implemented later. Engines generally implement true mesh LODs later in the pipeline; they're typically more efficient than HLODs with GPU-driven rendering. However, mesh LODs are more limited than HLODs, because they require the lower levels of detail to be meshes with the same vertex layout and shader (and perhaps the same material) as the original mesh. Games often want to use objects other than meshes to replace distant models, such as *octahedral imposters* or *billboard imposters*. The reason why the feature is called *hierarchical level of detail* is that HLODs can replace multiple meshes with a single mesh when the camera is far away. This can be useful for reducing drawcall count. Note that `VisibilityRange` doesn't automatically propagate down to children; it must be placed on every mesh. Crossfading between different levels of detail is supported, using the standard 4x4 ordered dithering pattern from [1]. The shader code to compute the dithering patterns should be well-optimized. The dithering code is only active when visibility ranges are in use for the mesh in question, so that we don't lose early Z. Cascaded shadow maps show the HLOD level of the view they're associated with. Point light and spot light shadow maps, which have no CSMs, display all HLOD levels that are visible in any view. To support this efficiently and avoid doing visibility checks multiple times, we precalculate all visible HLOD levels for each entity with a `VisibilityRange` during the `check_visibility_range` system. A new example, `visibility_range`, has been added to the tree, as well as a new low-poly version of the flight helmet model to go with it. It demonstrates use of the visibility range feature to provide levels of detail. [1]: https://en.wikipedia.org/wiki/Ordered_dithering#Threshold_map [^1]: Unreal doesn't have a feature that exactly corresponds to visibility ranges, but Unreal's HLOD system serves roughly the same purpose. ## Changelog ### Added * A new `VisibilityRange` component is available to conditionally enable entity visibility at camera distances, with optional crossfade support. This can be used to implement different levels of detail (LODs). ## Screenshots High-poly model: ![Screenshot 2024-04-09 185541](https://github.com/bevyengine/bevy/assets/157897/7e8be017-7187-4471-8866-974e2d8f2623) Low-poly model up close: ![Screenshot 2024-04-09 185546](https://github.com/bevyengine/bevy/assets/157897/429603fe-6bb7-4246-8b4e-b4888fd1d3a0) Crossfading between the two: ![Screenshot 2024-04-09 185604](https://github.com/bevyengine/bevy/assets/157897/86d0d543-f8f3-49ec-8fe5-caa4d0784fd4) --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2024-05-03 00:11:35 +00:00
[[example]]
name = "visibility_range"
path = "examples/3d/visibility_range.rs"
doc-scrape-examples = true
[package.metadata.example.visibility_range]
name = "Visibility range"
description = "Demonstrates visibility ranges"
category = "3D Rendering"
wasm = true
Implement opt-in sharp screen-space reflections for the deferred renderer, with improved raymarching code. (#13418) This commit, a revamp of #12959, implements screen-space reflections (SSR), which approximate real-time reflections based on raymarching through the depth buffer and copying samples from the final rendered frame. This patch is a relatively minimal implementation of SSR, so as to provide a flexible base on which to customize and build in the future. However, it's based on the production-quality [raymarching code by Tomasz Stachowiak](https://gist.github.com/h3r2tic/9c8356bdaefbe80b1a22ae0aaee192db). For a general basic overview of screen-space reflections, see [1](https://lettier.github.io/3d-game-shaders-for-beginners/screen-space-reflection.html). The raymarching shader uses the basic algorithm of tracing forward in large steps, refining that trace in smaller increments via binary search, and then using the secant method. No temporal filtering or roughness blurring, is performed at all; for this reason, SSR currently only operates on very shiny surfaces. No acceleration via the hierarchical Z-buffer is implemented (though note that https://github.com/bevyengine/bevy/pull/12899 will add the infrastructure for this). Reflections are traced at full resolution, which is often considered slow. All of these improvements and more can be follow-ups. SSR is built on top of the deferred renderer and is currently only supported in that mode. Forward screen-space reflections are possible albeit uncommon (though e.g. *Doom Eternal* uses them); however, they require tracing from the previous frame, which would add complexity. This patch leaves the door open to implementing SSR in the forward rendering path but doesn't itself have such an implementation. Screen-space reflections aren't supported in WebGL 2, because they require sampling from the depth buffer, which Naga can't do because of a bug (`sampler2DShadow` is incorrectly generated instead of `sampler2D`; this is the same reason why depth of field is disabled on that platform). To add screen-space reflections to a camera, use the `ScreenSpaceReflectionsBundle` bundle or the `ScreenSpaceReflectionsSettings` component. In addition to `ScreenSpaceReflectionsSettings`, `DepthPrepass` and `DeferredPrepass` must also be present for the reflections to show up. The `ScreenSpaceReflectionsSettings` component contains several settings that artists can tweak, and also comes with sensible defaults. A new example, `ssr`, has been added. It's loosely based on the [three.js ocean sample](https://threejs.org/examples/webgl_shaders_ocean.html), but all the assets are original. Note that the three.js demo has no screen-space reflections and instead renders a mirror world. In contrast to #12959, this demo tests not only a cube but also a more complex model (the flight helmet). ## Changelog ### Added * Screen-space reflections can be enabled for very smooth surfaces by adding the `ScreenSpaceReflections` component to a camera. Deferred rendering must be enabled for the reflections to appear. ![Screenshot 2024-05-18 143555](https://github.com/bevyengine/bevy/assets/157897/b8675b39-8a89-433e-a34e-1b9ee1233267) ![Screenshot 2024-05-18 143606](https://github.com/bevyengine/bevy/assets/157897/cc9e1cd0-9951-464a-9a08-e589210e5606)
2024-05-27 13:43:40 +00:00
[[example]]
name = "ssr"
path = "examples/3d/ssr.rs"
doc-scrape-examples = true
[package.metadata.example.ssr]
name = "Screen Space Reflections"
description = "Demonstrates screen space reflections with water ripples"
category = "3D Rendering"
wasm = false
Add `sub_camera_view`, enabling sheared projection (#15537) # Objective - This PR fixes #12488 ## Solution - This PR adds a new property to `Camera` that emulates the functionality of the [setViewOffset()](https://threejs.org/docs/#api/en/cameras/PerspectiveCamera.setViewOffset) API in three.js. - When set, the perspective and orthographic projections will restrict the visible area of the camera to a part of the view frustum defined by `offset` and `size`. ## Testing - In the new `camera_sub_view` example, a fixed, moving and control sub view is created for both perspective and orthographic projection - Run the example with `cargo run --example camera_sub_view` - The code can be tested by adding a `SubCameraView` to a camera --- ## Showcase ![image](https://github.com/user-attachments/assets/75ac45fc-d75d-4664-8ef6-ff7865297c25) - Left Half: Perspective Projection - Right Half: Orthographic Projection - Small boxes in order: - Sub view of the left half of the full image - Sub view moving from the top left to the bottom right of the full image - Sub view of the full image (acting as a control) - Large box: No sub view <details> <summary>Shortened camera setup of `camera_sub_view` example</summary> ```rust // Main perspective Camera commands.spawn(Camera3dBundle { transform, ..default() }); // Perspective camera left half commands.spawn(Camera3dBundle { camera: Camera { sub_camera_view: Some(SubCameraView { // Set the sub view camera to the left half of the full image full_size: uvec2(500, 500), offset: ivec2(0, 0), size: uvec2(250, 500), }), order: 1, ..default() }, transform, ..default() }); // Perspective camera moving commands.spawn(( Camera3dBundle { camera: Camera { sub_camera_view: Some(SubCameraView { // Set the sub view camera to a fifth of the full view and // move it in another system full_size: uvec2(500, 500), offset: ivec2(0, 0), size: uvec2(100, 100), }), order: 2, ..default() }, transform, ..default() }, MovingCameraMarker, )); // Perspective camera control commands.spawn(Camera3dBundle { camera: Camera { sub_camera_view: Some(SubCameraView { // Set the sub view to the full image, to ensure that it matches // the projection without sub view full_size: uvec2(450, 450), offset: ivec2(0, 0), size: uvec2(450, 450), }), order: 3, ..default() }, transform, ..default() }); // Main orthographic camera commands.spawn(Camera3dBundle { projection: OrthographicProjection { ... } .into(), camera: Camera { order: 4, ..default() }, transform, ..default() }); // Orthographic camera left half commands.spawn(Camera3dBundle { projection: OrthographicProjection { ... } .into(), camera: Camera { sub_camera_view: Some(SubCameraView { // Set the sub view camera to the left half of the full image full_size: uvec2(500, 500), offset: ivec2(0, 0), size: uvec2(250, 500), }), order: 5, ..default() }, transform, ..default() }); // Orthographic camera moving commands.spawn(( Camera3dBundle { projection: OrthographicProjection { ... } .into(), camera: Camera { sub_camera_view: Some(SubCameraView { // Set the sub view camera to a fifth of the full view and // move it in another system full_size: uvec2(500, 500), offset: ivec2(0, 0), size: uvec2(100, 100), }), order: 6, ..default() }, transform, ..default() }, MovingCameraMarker, )); // Orthographic camera control commands.spawn(Camera3dBundle { projection: OrthographicProjection { ... } .into(), camera: Camera { sub_camera_view: Some(SubCameraView { // Set the sub view to the full image, to ensure that it matches // the projection without sub view full_size: uvec2(450, 450), offset: ivec2(0, 0), size: uvec2(450, 450), }), order: 7, ..default() }, transform, ..default() }); ``` </details>
2024-10-01 14:11:24 +00:00
[[example]]
name = "camera_sub_view"
path = "examples/3d/camera_sub_view.rs"
doc-scrape-examples = true
[package.metadata.example.camera_sub_view]
name = "Camera sub view"
description = "Demonstrates using different sub view effects on a camera"
category = "3D Rendering"
wasm = true
Implement filmic color grading. (#13121) This commit expands Bevy's existing tonemapping feature to a complete set of filmic color grading tools, matching those of engines like Unity, Unreal, and Godot. The following features are supported: * White point adjustment. This is inspired by Unity's implementation of the feature, but simplified and optimized. *Temperature* and *tint* control the adjustments to the *x* and *y* chromaticity values of [CIE 1931]. Following Unity, the adjustments are made relative to the [D65 standard illuminant] in the [LMS color space]. * Hue rotation. This simply converts the RGB value to [HSV], alters the hue, and converts back. * Color correction. This allows the *gamma*, *gain*, and *lift* values to be adjusted according to the standard [ASC CDL combined function]. * Separate color correction for shadows, midtones, and highlights. Blender's source code was used as a reference for the implementation of this. The midtone ranges can be adjusted by the user. To avoid abrupt color changes, a small crossfade is used between the different sections of the image, again following Blender's formulas. A new example, `color_grading`, has been added, offering a GUI to change all the color grading settings. It uses the same test scene as the existing `tonemapping` example, which has been factored out into a shared glTF scene. [CIE 1931]: https://en.wikipedia.org/wiki/CIE_1931_color_space [D65 standard illuminant]: https://en.wikipedia.org/wiki/Standard_illuminant#Illuminant_series_D [LMS color space]: https://en.wikipedia.org/wiki/LMS_color_space [HSV]: https://en.wikipedia.org/wiki/HSL_and_HSV [ASC CDL combined function]: https://en.wikipedia.org/wiki/ASC_CDL#Combined_Function ## Changelog ### Added * Many new filmic color grading options have been added to the `ColorGrading` component. ## Migration Guide * `ColorGrading::gamma` and `ColorGrading::pre_saturation` are now set separately for the `shadows`, `midtones`, and `highlights` sections. You can migrate code with the `ColorGrading::all_sections` and `ColorGrading::all_sections_mut` functions, which access and/or update all sections at once. * `ColorGrading::post_saturation` and `ColorGrading::exposure` are now fields of `ColorGrading::global`. ## Screenshots ![Screenshot 2024-04-27 143144](https://github.com/bevyengine/bevy/assets/157897/c1de5894-917d-4101-b5c9-e644d141a941) ![Screenshot 2024-04-27 143216](https://github.com/bevyengine/bevy/assets/157897/da393c8a-d747-42f5-b47c-6465044c788d)
2024-05-02 12:18:59 +00:00
[[example]]
name = "color_grading"
path = "examples/3d/color_grading.rs"
doc-scrape-examples = true
[package.metadata.example.color_grading]
name = "Color grading"
description = "Demonstrates color grading"
category = "3D Rendering"
wasm = true
Implement clearcoat per the Filament and the `KHR_materials_clearcoat` specifications. (#13031) Clearcoat is a separate material layer that represents a thin translucent layer of a material. Examples include (from the [Filament spec]) car paint, soda cans, and lacquered wood. This commit implements support for clearcoat following the Filament and Khronos specifications, marking the beginnings of support for multiple PBR layers in Bevy. The [`KHR_materials_clearcoat`] specification describes the clearcoat support in glTF. In Blender, applying a clearcoat to the Principled BSDF node causes the clearcoat settings to be exported via this extension. As of this commit, Bevy parses and reads the extension data when present in glTF. Note that the `gltf` crate has no support for `KHR_materials_clearcoat`; this patch therefore implements the JSON semantics manually. Clearcoat is integrated with `StandardMaterial`, but the code is behind a series of `#ifdef`s that only activate when clearcoat is present. Additionally, the `pbr_feature_layer_material_textures` Cargo feature must be active in order to enable support for clearcoat factor maps, clearcoat roughness maps, and clearcoat normal maps. This approach mirrors the same pattern used by the existing transmission feature and exists to avoid running out of texture bindings on platforms like WebGL and WebGPU. Note that constant clearcoat factors and roughness values *are* supported in the browser; only the relatively-less-common maps are disabled on those platforms. This patch refactors the lighting code in `StandardMaterial` significantly in order to better support multiple layers in a natural way. That code was due for a refactor in any case, so this is a nice improvement. A new demo, `clearcoat`, has been added. It's based on [the corresponding three.js demo], but all the assets (aside from the skybox and environment map) are my original work. [Filament spec]: https://google.github.io/filament/Filament.html#materialsystem/clearcoatmodel [`KHR_materials_clearcoat`]: https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Khronos/KHR_materials_clearcoat/README.md [the corresponding three.js demo]: https://threejs.org/examples/webgl_materials_physical_clearcoat.html ![Screenshot 2024-04-19 101143](https://github.com/bevyengine/bevy/assets/157897/3444bcb5-5c20-490c-b0ad-53759bd47ae2) ![Screenshot 2024-04-19 102054](https://github.com/bevyengine/bevy/assets/157897/6e953944-75b8-49ef-bc71-97b0a53b3a27) ## Changelog ### Added * `StandardMaterial` now supports a clearcoat layer, which represents a thin translucent layer over an underlying material. * The glTF loader now supports the `KHR_materials_clearcoat` extension, representing materials with clearcoat layers. ## Migration Guide * The lighting functions in the `pbr_lighting` WGSL module now have clearcoat parameters, if `STANDARD_MATERIAL_CLEARCOAT` is defined. * The `R` reflection vector parameter has been removed from some lighting functions, as it was unused.
2024-05-05 22:57:05 +00:00
[[example]]
name = "clearcoat"
path = "examples/3d/clearcoat.rs"
doc-scrape-examples = true
required-features = ["pbr_multi_layer_material_textures"]
[package.metadata.example.clearcoat]
name = "Clearcoat"
description = "Demonstrates the clearcoat PBR feature"
category = "3D Rendering"
wasm = false
Implement fast depth of field as a postprocessing effect. (#13009) This commit implements the [depth of field] effect, simulating the blur of objects out of focus of the virtual lens. Either the [hexagonal bokeh] effect or a faster Gaussian blur may be used. In both cases, the implementation is a simple separable two-pass convolution. This is not the most physically-accurate real-time bokeh technique that exists; Unreal Engine has [a more accurate implementation] of "cinematic depth of field" from 2018. However, it's simple, and most engines provide something similar as a fast option, often called "mobile" depth of field. The general approach is outlined in [a blog post from 2017]. We take advantage of the fact that both Gaussian blurs and hexagonal bokeh blurs are *separable*. This means that their 2D kernels can be reduced to a small number of 1D kernels applied one after another, asymptotically reducing the amount of work that has to be done. Gaussian blurs can be accomplished by blurring horizontally and then vertically, while hexagonal bokeh blurs can be done with a vertical blur plus a diagonal blur, plus two diagonal blurs. In both cases, only two passes are needed. Bokeh requires the first pass to have a second render target and requires two subpasses in the second pass, which decreases its performance relative to the Gaussian blur. The bokeh blur is generally more aesthetically pleasing than the Gaussian blur, as it simulates the effect of a camera more accurately. The shape of the bokeh circles are determined by the number of blades of the aperture. In our case, we use a hexagon, which is usually considered specific to lower-quality cameras. (This is a downside of the fast hexagon approach compared to the higher-quality approaches.) The blur amount is generally specified by the [f-number], which we use to compute the focal length from the film size and FOV. By default, we simulate standard cinematic cameras of f/1 and [Super 35]. The developer can customize these values as desired. A new example has been added to demonstrate depth of field. It allows customization of the mode (Gaussian vs. bokeh), focal distance and f-numbers. The test scene is inspired by a [blog post on depth of field in Unity]; however, the effect is implemented in a completely different way from that blog post, and all the assets (textures, etc.) are original. Bokeh depth of field: ![Screenshot 2024-04-17 152535](https://github.com/bevyengine/bevy/assets/157897/702f0008-1c8a-4cf3-b077-4110f8c46584) Gaussian depth of field: ![Screenshot 2024-04-17 152542](https://github.com/bevyengine/bevy/assets/157897/f4ece47a-520e-4483-a92d-f4fa760795d3) No depth of field: ![Screenshot 2024-04-17 152547](https://github.com/bevyengine/bevy/assets/157897/9444e6aa-fcae-446c-b66b-89469f1a1325) [depth of field]: https://en.wikipedia.org/wiki/Depth_of_field [hexagonal bokeh]: https://colinbarrebrisebois.com/2017/04/18/hexagonal-bokeh-blur-revisited/ [a more accurate implementation]: https://epicgames.ent.box.com/s/s86j70iamxvsuu6j35pilypficznec04 [a blog post from 2017]: https://colinbarrebrisebois.com/2017/04/18/hexagonal-bokeh-blur-revisited/ [f-number]: https://en.wikipedia.org/wiki/F-number [Super 35]: https://en.wikipedia.org/wiki/Super_35 [blog post on depth of field in Unity]: https://catlikecoding.com/unity/tutorials/advanced-rendering/depth-of-field/ ## Changelog ### Added * A depth of field postprocessing effect is now available, to simulate objects being out of focus of the camera. To use it, add `DepthOfFieldSettings` to an entity containing a `Camera3d` component. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Bram Buurlage <brambuurlage@gmail.com>
2024-05-13 18:23:56 +00:00
[[example]]
name = "depth_of_field"
path = "examples/3d/depth_of_field.rs"
doc-scrape-examples = true
[package.metadata.example.depth_of_field]
name = "Depth of field"
description = "Demonstrates depth of field"
category = "3D Rendering"
wasm = false
Implement volumetric fog and volumetric lighting, also known as light shafts or god rays. (#13057) This commit implements a more physically-accurate, but slower, form of fog than the `bevy_pbr::fog` module does. Notably, this *volumetric fog* allows for light beams from directional lights to shine through, creating what is known as *light shafts* or *god rays*. To add volumetric fog to a scene, add `VolumetricFogSettings` to the camera, and add `VolumetricLight` to directional lights that you wish to be volumetric. `VolumetricFogSettings` has numerous settings that allow you to define the accuracy of the simulation, as well as the look of the fog. Currently, only interaction with directional lights that have shadow maps is supported. Note that the overhead of the effect scales directly with the number of directional lights in use, so apply `VolumetricLight` sparingly for the best results. The overall algorithm, which is implemented as a postprocessing effect, is a combination of the techniques described in [Scratchapixel] and [this blog post]. It uses raymarching in screen space, transformed into shadow map space for sampling and combined with physically-based modeling of absorption and scattering. Bevy employs the widely-used [Henyey-Greenstein phase function] to model asymmetry; this essentially allows light shafts to fade into and out of existence as the user views them. Volumetric rendering is a huge subject, and I deliberately kept the scope of this commit small. Possible follow-ups include: 1. Raymarching at a lower resolution. 2. A post-processing blur (especially useful when combined with (1)). 3. Supporting point lights and spot lights. 4. Supporting lights with no shadow maps. 5. Supporting irradiance volumes and reflection probes. 6. Voxel components that reuse the volumetric fog code to create voxel shapes. 7. *Horizon: Zero Dawn*-style clouds. These are all useful, but out of scope of this patch for now, to keep things tidy and easy to review. A new example, `volumetric_fog`, has been added to demonstrate the effect. ## Changelog ### Added * A new component, `VolumetricFog`, is available, to allow for a more physically-accurate, but more resource-intensive, form of fog. * A new component, `VolumetricLight`, can be placed on directional lights to make them interact with `VolumetricFog`. Notably, this allows such lights to emit light shafts/god rays. ![Screenshot 2024-04-21 162808](https://github.com/bevyengine/bevy/assets/157897/7a1fc81d-eed5-4735-9419-286c496391a9) ![Screenshot 2024-04-21 132005](https://github.com/bevyengine/bevy/assets/157897/e6d3b5ca-8f59-488d-a3de-15e95aaf4995) [Scratchapixel]: https://www.scratchapixel.com/lessons/3d-basic-rendering/volume-rendering-for-developers/intro-volume-rendering.html [this blog post]: https://www.alexandre-pestana.com/volumetric-lights/ [Henyey-Greenstein phase function]: https://www.pbr-book.org/4ed/Volume_Scattering/Phase_Functions#TheHenyeyndashGreensteinPhaseFunction
2024-05-16 17:13:18 +00:00
[[example]]
name = "volumetric_fog"
path = "examples/3d/volumetric_fog.rs"
doc-scrape-examples = true
[package.metadata.example.volumetric_fog]
name = "Volumetric fog"
description = "Demonstrates volumetric fog and lighting"
category = "3D Rendering"
wasm = true
Initial implementation of the Bevy Remote Protocol (Adopted) (#14880) # Objective Adopted from #13563. The goal is to implement the Bevy Remote Protocol over HTTP/JSON, allowing the ECS to be interacted with remotely. ## Solution At a high level, there are really two separate things that have been undertaken here: 1. First, `RemotePlugin` has been created, which has the effect of embedding a [JSON-RPC](https://www.jsonrpc.org/specification) endpoint into a Bevy application. 2. Second, the [Bevy Remote Protocol verbs](https://gist.github.com/coreh/1baf6f255d7e86e4be29874d00137d1d#file-bevy-remote-protocol-md) (excluding `POLL`) have been implemented as remote methods for that JSON-RPC endpoint under a Bevy-exclusive namespace (e.g. `bevy/get`, `bevy/list`, etc.). To avoid some repetition, here is the crate-level documentation, which explains the request/response structure, built-in-methods, and custom method configuration: <details> <summary>Click to view crate-level docs</summary> ```rust //! An implementation of the Bevy Remote Protocol over HTTP and JSON, to allow //! for remote control of a Bevy app. //! //! Adding the [`RemotePlugin`] to your [`App`] causes Bevy to accept //! connections over HTTP (by default, on port 15702) while your app is running. //! These *remote clients* can inspect and alter the state of the //! entity-component system. Clients are expected to `POST` JSON requests to the //! root URL; see the `client` example for a trivial example of use. //! //! The Bevy Remote Protocol is based on the JSON-RPC 2.0 protocol. //! //! ## Request objects //! //! A typical client request might look like this: //! //! ```json //! { //! "method": "bevy/get", //! "id": 0, //! "params": { //! "entity": 4294967298, //! "components": [ //! "bevy_transform::components::transform::Transform" //! ] //! } //! } //! ``` //! //! The `id` and `method` fields are required. The `param` field may be omitted //! for certain methods: //! //! * `id` is arbitrary JSON data. The server completely ignores its contents, //! and the client may use it for any purpose. It will be copied via //! serialization and deserialization (so object property order, etc. can't be //! relied upon to be identical) and sent back to the client as part of the //! response. //! //! * `method` is a string that specifies one of the possible [`BrpRequest`] //! variants: `bevy/query`, `bevy/get`, `bevy/insert`, etc. It's case-sensitive. //! //! * `params` is parameter data specific to the request. //! //! For more information, see the documentation for [`BrpRequest`]. //! [`BrpRequest`] is serialized to JSON via `serde`, so [the `serde` //! documentation] may be useful to clarify the correspondence between the Rust //! structure and the JSON format. //! //! ## Response objects //! //! A response from the server to the client might look like this: //! //! ```json //! { //! "jsonrpc": "2.0", //! "id": 0, //! "result": { //! "bevy_transform::components::transform::Transform": { //! "rotation": { "x": 0.0, "y": 0.0, "z": 0.0, "w": 1.0 }, //! "scale": { "x": 1.0, "y": 1.0, "z": 1.0 }, //! "translation": { "x": 0.0, "y": 0.5, "z": 0.0 } //! } //! } //! } //! ``` //! //! The `id` field will always be present. The `result` field will be present if the //! request was successful. Otherwise, an `error` field will replace it. //! //! * `id` is the arbitrary JSON data that was sent as part of the request. It //! will be identical to the `id` data sent during the request, modulo //! serialization and deserialization. If there's an error reading the `id` field, //! it will be `null`. //! //! * `result` will be present if the request succeeded and will contain the response //! specific to the request. //! //! * `error` will be present if the request failed and will contain an error object //! with more information about the cause of failure. //! //! ## Error objects //! //! An error object might look like this: //! //! ```json //! { //! "code": -32602, //! "message": "Missing \"entity\" field" //! } //! ``` //! //! The `code` and `message` fields will always be present. There may also be a `data` field. //! //! * `code` is an integer representing the kind of an error that happened. Error codes documented //! in the [`error_codes`] module. //! //! * `message` is a short, one-sentence human-readable description of the error. //! //! * `data` is an optional field of arbitrary type containing additional information about the error. //! //! ## Built-in methods //! //! The Bevy Remote Protocol includes a number of built-in methods for accessing and modifying data //! in the ECS. Each of these methods uses the `bevy/` prefix, which is a namespace reserved for //! BRP built-in methods. //! //! ### bevy/get //! //! Retrieve the values of one or more components from an entity. //! //! `params`: //! - `entity`: The ID of the entity whose components will be fetched. //! - `components`: An array of fully-qualified type names of components to fetch. //! //! `result`: A map associating each type name to its value on the requested entity. //! //! ### bevy/query //! //! Perform a query over components in the ECS, returning all matching entities and their associated //! component values. //! //! All of the arrays that comprise this request are optional, and when they are not provided, they //! will be treated as if they were empty. //! //! `params`: //! `params`: //! - `data`: //! - `components` (optional): An array of fully-qualified type names of components to fetch. //! - `option` (optional): An array of fully-qualified type names of components to fetch optionally. //! - `has` (optional): An array of fully-qualified type names of components whose presence will be //! reported as boolean values. //! - `filter` (optional): //! - `with` (optional): An array of fully-qualified type names of components that must be present //! on entities in order for them to be included in results. //! - `without` (optional): An array of fully-qualified type names of components that must *not* be //! present on entities in order for them to be included in results. //! //! `result`: An array, each of which is an object containing: //! - `entity`: The ID of a query-matching entity. //! - `components`: A map associating each type name from `components`/`option` to its value on the matching //! entity if the component is present. //! - `has`: A map associating each type name from `has` to a boolean value indicating whether or not the //! entity has that component. If `has` was empty or omitted, this key will be omitted in the response. //! //! ### bevy/spawn //! //! Create a new entity with the provided components and return the resulting entity ID. //! //! `params`: //! - `components`: A map associating each component's fully-qualified type name with its value. //! //! `result`: //! - `entity`: The ID of the newly spawned entity. //! //! ### bevy/destroy //! //! Despawn the entity with the given ID. //! //! `params`: //! - `entity`: The ID of the entity to be despawned. //! //! `result`: null. //! //! ### bevy/remove //! //! Delete one or more components from an entity. //! //! `params`: //! - `entity`: The ID of the entity whose components should be removed. //! - `components`: An array of fully-qualified type names of components to be removed. //! //! `result`: null. //! //! ### bevy/insert //! //! Insert one or more components into an entity. //! //! `params`: //! - `entity`: The ID of the entity to insert components into. //! - `components`: A map associating each component's fully-qualified type name with its value. //! //! `result`: null. //! //! ### bevy/reparent //! //! Assign a new parent to one or more entities. //! //! `params`: //! - `entities`: An array of entity IDs of entities that will be made children of the `parent`. //! - `parent` (optional): The entity ID of the parent to which the child entities will be assigned. //! If excluded, the given entities will be removed from their parents. //! //! `result`: null. //! //! ### bevy/list //! //! List all registered components or all components present on an entity. //! //! When `params` is not provided, this lists all registered components. If `params` is provided, //! this lists only those components present on the provided entity. //! //! `params` (optional): //! - `entity`: The ID of the entity whose components will be listed. //! //! `result`: An array of fully-qualified type names of components. //! //! ## Custom methods //! //! In addition to the provided methods, the Bevy Remote Protocol can be extended to include custom //! methods. This is primarily done during the initialization of [`RemotePlugin`], although the //! methods may also be extended at runtime using the [`RemoteMethods`] resource. //! //! ### Example //! ```ignore //! fn main() { //! App::new() //! .add_plugins(DefaultPlugins) //! .add_plugins( //! // `default` adds all of the built-in methods, while `with_method` extends them //! RemotePlugin::default() //! .with_method("super_user/cool_method".to_owned(), path::to::my::cool::handler) //! // ... more methods can be added by chaining `with_method` //! ) //! .add_systems( //! // ... standard application setup //! ) //! .run(); //! } //! ``` //! //! The handler is expected to be a system-convertible function which takes optional JSON parameters //! as input and returns a [`BrpResult`]. This means that it should have a type signature which looks //! something like this: //! ``` //! # use serde_json::Value; //! # use bevy_ecs::prelude::{In, World}; //! # use bevy_remote::BrpResult; //! fn handler(In(params): In<Option<Value>>, world: &mut World) -> BrpResult { //! todo!() //! } //! ``` //! //! Arbitrary system parameters can be used in conjunction with the optional `Value` input. The //! handler system will always run with exclusive `World` access. //! //! [the `serde` documentation]: https://serde.rs/ ``` </details> ### Message lifecycle At a high level, the lifecycle of client-server interactions is something like this: 1. The client sends one or more `BrpRequest`s. The deserialized version of that is just the Rust representation of a JSON-RPC request, and it looks like this: ```rust pub struct BrpRequest { /// The action to be performed. Parsing is deferred for the sake of error reporting. pub method: Option<Value>, /// Arbitrary data that will be returned verbatim to the client as part of /// the response. pub id: Option<Value>, /// The parameters, specific to each method. /// /// These are passed as the first argument to the method handler. /// Sometimes params can be omitted. pub params: Option<Value>, } ``` 2. These requests are accumulated in a mailbox resource (small lie but close enough). 3. Each update, the mailbox is drained by a system `process_remote_requests`, where each request is processed according to its `method`, which has an associated handler. Each handler is a Bevy system that runs with exclusive world access and returns a result; e.g.: ```rust pub fn process_remote_get_request(In(params): In<Option<Value>>, world: &World) -> BrpResult { // ... } ``` 4. The result (or an error) is reported back to the client. ## Testing This can be tested by using the `server` and `client` examples. The `client` example is not particularly exhaustive at the moment (it only creates barebones `bevy/query` requests) but is still informative. Other queries can be made using `curl` with the `server` example running. For example, to make a `bevy/list` request and list all registered components: ```bash curl -X POST -d '{ "jsonrpc": "2.0", "id": 1, "method": "bevy/list" }' 127.0.0.1:15702 | jq . ``` --- ## Future direction There were a couple comments on BRP versioning while this was in draft. I agree that BRP versioning is a good idea, but I think that it requires some consensus on a couple fronts: - First of all, what does the version actually mean? Is it a version for the protocol itself or for the `bevy/*` methods implemented using it? Both? - Where does the version actually live? The most natural place is just where we have `"jsonrpc"` right now (at least if it's versioning the protocol itself), but this means we're not actually conforming to JSON-RPC any more (so, for example, any client library used to construct JSON-RPC requests would stop working). I'm not really against that, but it's at least a real decision. - What do we actually do when we encounter mismatched versions? Adding handling for this would be actual scope creep instead of just a little add-on in my opinion. Another thing that would be nice is making the internal structure of the implementation less JSON-specific. Right now, for example, component values that will appear in server responses are quite eagerly converted to JSON `Value`s, which prevents disentangling the handler logic from the communication medium, but it can probably be done in principle and I imagine it would enable more code reuse (e.g. for custom method handlers) in addition to making the internals more readily usable for other formats. --------- Co-authored-by: Patrick Walton <pcwalton@mimiga.net> Co-authored-by: DragonGamesStudios <margos.michal@gmail.com> Co-authored-by: Christopher Biscardi <chris@christopherbiscardi.com> Co-authored-by: Gino Valente <49806985+MrGVSV@users.noreply.github.com>
2024-09-23 18:36:16 +00:00
[[example]]
name = "client"
path = "examples/remote/client.rs"
doc-scrape-examples = true
[package.metadata.example.client]
name = "client"
description = "A simple command line client that can control Bevy apps via the BRP"
category = "Remote Protocol"
wasm = false
[[example]]
name = "server"
path = "examples/remote/server.rs"
doc-scrape-examples = true
[package.metadata.example.server]
name = "server"
description = "A Bevy app that you can connect to with the BRP and edit"
category = "Remote Protocol"
wasm = false
Implement PBR anisotropy per `KHR_materials_anisotropy`. (#13450) This commit implements support for physically-based anisotropy in Bevy's `StandardMaterial`, following the specification for the [`KHR_materials_anisotropy`] glTF extension. [*Anisotropy*] (not to be confused with [anisotropic filtering]) is a PBR feature that allows roughness to vary along the tangent and bitangent directions of a mesh. In effect, this causes the specular light to stretch out into lines instead of a round lobe. This is useful for modeling brushed metal, hair, and similar surfaces. Support for anisotropy is a common feature in major game and graphics engines; Unity, Unreal, Godot, three.js, and Blender all support it to varying degrees. Two new parameters have been added to `StandardMaterial`: `anisotropy_strength` and `anisotropy_rotation`. Anisotropy strength, which ranges from 0 to 1, represents how much the roughness differs between the tangent and the bitangent of the mesh. In effect, it controls how stretched the specular highlight is. Anisotropy rotation allows the roughness direction to differ from the tangent of the model. In addition to these two fixed parameters, an *anisotropy texture* can be supplied. Such a texture should be a 3-channel RGB texture, where the red and green values specify a direction vector using the same conventions as a normal map ([0, 1] color values map to [-1, 1] vector values), and the the blue value represents the strength. This matches the format that the [`KHR_materials_anisotropy`] specification requires. Such textures should be loaded as linear and not sRGB. Note that this texture does consume one additional texture binding in the standard material shader. The glTF loader has been updated to properly parse the `KHR_materials_anisotropy` extension. A new example, `anisotropy`, has been added. This example loads and displays the barn lamp example from the [`glTF-Sample-Assets`] repository. Note that the textures were rather large, so I shrunk them down and converted them to a mixture of JPEG and KTX2 format, in the interests of saving space in the Bevy repository. [*Anisotropy*]: https://google.github.io/filament/Filament.md.html#materialsystem/anisotropicmodel [anisotropic filtering]: https://en.wikipedia.org/wiki/Anisotropic_filtering [`KHR_materials_anisotropy`]: https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Khronos/KHR_materials_anisotropy/README.md [`glTF-Sample-Assets`]: https://github.com/KhronosGroup/glTF-Sample-Assets/ ## Changelog ### Added * Physically-based anisotropy is now available for materials, which enhances the look of surfaces such as brushed metal or hair. glTF scenes can use the new feature with the `KHR_materials_anisotropy` extension. ## Screenshots With anisotropy: ![Screenshot 2024-05-20 233414](https://github.com/bevyengine/bevy/assets/157897/379f1e42-24e9-40b6-a430-f7d1479d0335) Without anisotropy: ![Screenshot 2024-05-20 233420](https://github.com/bevyengine/bevy/assets/157897/aa220f05-b8e7-417c-9671-b242d4bf9fc4)
2024-06-03 23:46:06 +00:00
[[example]]
name = "anisotropy"
path = "examples/3d/anisotropy.rs"
doc-scrape-examples = true
Added feature switch to default Standard Material's new anisotropy texture to off (#14048) # Objective - Standard Material is starting to run out of samplers (currently uses 13 with no additional features off, I think in 0.13 it was 12). - This change adds a new feature switch, modelled on the other ones which add features to Standard Material, to turn off the new anisotropy feature by default. ## Solution - feature + texture define ## Testing - Anisotropy example still works fine - Other samples work fine - Standard Material now takes 12 samplers by default on my Mac instead of 13 ## Migration Guide - Add feature pbr_anisotropy_texture if you are using that texture in any standard materials. --------- Co-authored-by: John Payne <20407779+johngpayne@users.noreply.github.com>
2024-07-02 18:02:05 +00:00
required-features = ["jpeg", "pbr_anisotropy_texture"]
Implement PBR anisotropy per `KHR_materials_anisotropy`. (#13450) This commit implements support for physically-based anisotropy in Bevy's `StandardMaterial`, following the specification for the [`KHR_materials_anisotropy`] glTF extension. [*Anisotropy*] (not to be confused with [anisotropic filtering]) is a PBR feature that allows roughness to vary along the tangent and bitangent directions of a mesh. In effect, this causes the specular light to stretch out into lines instead of a round lobe. This is useful for modeling brushed metal, hair, and similar surfaces. Support for anisotropy is a common feature in major game and graphics engines; Unity, Unreal, Godot, three.js, and Blender all support it to varying degrees. Two new parameters have been added to `StandardMaterial`: `anisotropy_strength` and `anisotropy_rotation`. Anisotropy strength, which ranges from 0 to 1, represents how much the roughness differs between the tangent and the bitangent of the mesh. In effect, it controls how stretched the specular highlight is. Anisotropy rotation allows the roughness direction to differ from the tangent of the model. In addition to these two fixed parameters, an *anisotropy texture* can be supplied. Such a texture should be a 3-channel RGB texture, where the red and green values specify a direction vector using the same conventions as a normal map ([0, 1] color values map to [-1, 1] vector values), and the the blue value represents the strength. This matches the format that the [`KHR_materials_anisotropy`] specification requires. Such textures should be loaded as linear and not sRGB. Note that this texture does consume one additional texture binding in the standard material shader. The glTF loader has been updated to properly parse the `KHR_materials_anisotropy` extension. A new example, `anisotropy`, has been added. This example loads and displays the barn lamp example from the [`glTF-Sample-Assets`] repository. Note that the textures were rather large, so I shrunk them down and converted them to a mixture of JPEG and KTX2 format, in the interests of saving space in the Bevy repository. [*Anisotropy*]: https://google.github.io/filament/Filament.md.html#materialsystem/anisotropicmodel [anisotropic filtering]: https://en.wikipedia.org/wiki/Anisotropic_filtering [`KHR_materials_anisotropy`]: https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Khronos/KHR_materials_anisotropy/README.md [`glTF-Sample-Assets`]: https://github.com/KhronosGroup/glTF-Sample-Assets/ ## Changelog ### Added * Physically-based anisotropy is now available for materials, which enhances the look of surfaces such as brushed metal or hair. glTF scenes can use the new feature with the `KHR_materials_anisotropy` extension. ## Screenshots With anisotropy: ![Screenshot 2024-05-20 233414](https://github.com/bevyengine/bevy/assets/157897/379f1e42-24e9-40b6-a430-f7d1479d0335) Without anisotropy: ![Screenshot 2024-05-20 233420](https://github.com/bevyengine/bevy/assets/157897/aa220f05-b8e7-417c-9671-b242d4bf9fc4)
2024-06-03 23:46:06 +00:00
[package.metadata.example.anisotropy]
name = "Anisotropy"
description = "Displays an example model with anisotropy"
category = "3D Rendering"
wasm = false
Allow phase items not associated with meshes to be binned. (#14029) As reported in #14004, many third-party plugins, such as Hanabi, enqueue entities that don't have meshes into render phases. However, the introduction of indirect mode added a dependency on mesh-specific data, breaking this workflow. This is because GPU preprocessing requires that the render phases manage indirect draw parameters, which don't apply to objects that aren't meshes. The existing code skips over binned entities that don't have indirect draw parameters, which causes the rendering to be skipped for such objects. To support this workflow, this commit adds a new field, `non_mesh_items`, to `BinnedRenderPhase`. This field contains a simple list of (bin key, entity) pairs. After drawing batchable and unbatchable objects, the non-mesh items are drawn one after another. Bevy itself doesn't enqueue any items into this list; it exists solely for the application and/or plugins to use. Additionally, this commit switches the asset ID in the standard bin keys to be an untyped asset ID rather than that of a mesh. This allows more flexibility, allowing bins to be keyed off any type of asset. This patch adds a new example, `custom_phase_item`, which simultaneously serves to demonstrate how to use this new feature and to act as a regression test so this doesn't break again. Fixes #14004. ## Changelog ### Added * `BinnedRenderPhase` now contains a `non_mesh_items` field for plugins to add custom items to.
2024-06-27 16:13:03 +00:00
[[example]]
name = "custom_phase_item"
path = "examples/shader/custom_phase_item.rs"
doc-scrape-examples = true
[package.metadata.example.custom_phase_item]
name = "Custom phase item"
description = "Demonstrates how to enqueue custom draw commands in a render phase"
category = "Shaders"
wasm = true
Allow volumetric fog to be localized to specific, optionally voxelized, regions. (#14099) Currently, volumetric fog is global and affects the entire scene uniformly. This is inadequate for many use cases, such as local smoke effects. To address this problem, this commit introduces *fog volumes*, which are axis-aligned bounding boxes (AABBs) that specify fog parameters inside their boundaries. Such volumes can also specify a *density texture*, a 3D texture of voxels that specifies the density of the fog at each point. To create a fog volume, add a `FogVolume` component to an entity (which is included in the new `FogVolumeBundle` convenience bundle). Like light probes, a fog volume is conceptually a 1×1×1 cube centered on the origin; a transform can be used to position and resize this region. Many of the fields on the existing `VolumetricFogSettings` have migrated to the new `FogVolume` component. `VolumetricFogSettings` on a camera is still needed to enable volumetric fog. However, by itself `VolumetricFogSettings` is no longer sufficient to enable volumetric fog; a `FogVolume` must be present. Applications that wish to retain the old global fog behavior can simply surround the scene with a large fog volume. By way of implementation, this commit converts the volumetric fog shader from a full-screen shader to one applied to a mesh. The strategy is different depending on whether the camera is inside or outside the fog volume. If the camera is inside the fog volume, the mesh is simply a plane scaled to the viewport, effectively falling back to a full-screen pass. If the camera is outside the fog volume, the mesh is a cube transformed to coincide with the boundaries of the fog volume's AABB. Importantly, in the latter case, only the front faces of the cuboid are rendered. Instead of treating the boundaries of the fog as a sphere centered on the camera position, as we did prior to this patch, we raytrace the far planes of the AABB to determine the portion of each ray contained within the fog volume. We then raymarch in shadow map space as usual. If a density texture is present, we modulate the fixed density value with the trilinearly-interpolated value from that texture. Furthermore, this patch introduces optional jitter to fog volumes, intended for use with TAA. This modifies the position of the ray from frame to frame using interleaved gradient noise, in order to reduce aliasing artifacts. Many implementations of volumetric fog in games use this technique. Note that this patch makes no attempt to write a motion vector; this is because when a view ray intersects multiple voxels there's no single direction of motion. Consequently, fog volumes can have ghosting artifacts, but because fog is "ghostly" by its nature, these artifacts are less objectionable than they would be for opaque objects. A new example, `fog_volumes`, has been added. It demonstrates a single fog volume containing a voxelized representation of the Stanford bunny. The existing `volumetric_fog` example has been updated to use the new local volumetrics API. ## Changelog ### Added * Local `FogVolume`s are now supported, to localize fog to specific regions. They can optionally have 3D density voxel textures for precise control over the distribution of the fog. ### Changed * `VolumetricFogSettings` on a camera no longer enables volumetric fog; instead, it simply enables the processing of `FogVolume`s within the scene. ## Migration Guide * A `FogVolume` is now necessary in order to enable volumetric fog, in addition to `VolumetricFogSettings` on the camera. Existing uses of volumetric fog can be migrated by placing a large `FogVolume` surrounding the scene. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: François Mockers <mockersf@gmail.com>
2024-07-16 03:14:12 +00:00
[[example]]
name = "fog_volumes"
path = "examples/3d/fog_volumes.rs"
doc-scrape-examples = true
[package.metadata.example.fog_volumes]
name = "Fog volumes"
description = "Demonstrates fog volumes"
category = "3D Rendering"
wasm = false
Allow fog density texture to be scrolled over time with an offset (#14868) # Objective - The goal of this PR is to make it possible to move the density texture of a `FogVolume` over time in order to create dynamic effects like fog moving in the wind. - You could theoretically move the `FogVolume` itself, but this is not ideal, because the `FogVolume` AABB would eventually leave the area. If you want an area to remain foggy while also creating the impression that the fog is moving in the wind, a scrolling density texture is a better solution. ## Solution - The PR adds a `density_texture_offset` field to the `FogVolume` component. This offset is in the UVW coordinates of the density texture, meaning that a value of `(0.5, 0.0, 0.0)` moves the 3d texture by half along the x-axis. - Values above 1.0 are wrapped, a 1.5 offset is the same as a 0.5 offset. This makes it so that the density texture wraps around on the other side, meaning that a repeating 3d noise texture can seamlessly scroll forever. It also makes it easy to move the density texture over time by simply increasing the offset every frame. ## Testing - A `scrolling_fog` example has been added to demonstrate the feature. It uses the offset to scroll a repeating 3d noise density texture to create the impression of fog moving in the wind. - The camera is looking at a pillar with the sun peaking behind it. This highlights the effect the changing density has on the volumetric lighting interactions. - Temporal anti-aliasing combined with the `jitter` option of `VolumetricFogSettings` is used to improve the quality of the effect. --- ## Showcase https://github.com/user-attachments/assets/3aa50ebd-771c-4c99-ab5d-255c0c3be1a8
2024-08-22 19:43:14 +00:00
[[example]]
name = "scrolling_fog"
path = "examples/3d/scrolling_fog.rs"
doc-scrape-examples = true
[package.metadata.example.scrolling_fog]
name = "Scrolling fog"
description = "Demonstrates how to create the effect of fog moving in the wind"
category = "3D Rendering"
wasm = false
Add an example for doing movement in fixed timesteps (#14223) _copy-pasted from my doc comment in the code_ # Objective This example shows how to properly handle player input, advance a physics simulation in a fixed timestep, and display the results. The classic source for how and why this is done is Glenn Fiedler's article [Fix Your Timestep!](https://gafferongames.com/post/fix_your_timestep/). ## Motivation The naive way of moving a player is to just update their position like so: ```rust transform.translation += velocity; ``` The issue here is that the player's movement speed will be tied to the frame rate. Faster machines will move the player faster, and slower machines will move the player slower. In fact, you can observe this today when running some old games that did it this way on modern hardware! The player will move at a breakneck pace. The more sophisticated way is to update the player's position based on the time that has passed: ```rust transform.translation += velocity * time.delta_seconds(); ``` This way, velocity represents a speed in units per second, and the player will move at the same speed regardless of the frame rate. However, this can still be problematic if the frame rate is very low or very high. If the frame rate is very low, the player will move in large jumps. This may lead to a player moving in such large jumps that they pass through walls or other obstacles. In general, you cannot expect a physics simulation to behave nicely with *any* delta time. Ideally, we want to have some stability in what kinds of delta times we feed into our physics simulation. The solution is using a fixed timestep. This means that we advance the physics simulation by a fixed amount at a time. If the real time that passed between two frames is less than the fixed timestep, we simply don't advance the physics simulation at all. If it is more, we advance the physics simulation multiple times until we catch up. You can read more about how Bevy implements this in the documentation for [`bevy::time::Fixed`](https://docs.rs/bevy/latest/bevy/time/struct.Fixed.html). This leaves us with a last problem, however. If our physics simulation may advance zero or multiple times per frame, there may be frames in which the player's position did not need to be updated at all, and some where it is updated by a large amount that resulted from running the physics simulation multiple times. This is physically correct, but visually jarring. Imagine a player moving in a straight line, but depending on the frame rate, they may sometimes advance by a large amount and sometimes not at all. Visually, we want the player to move smoothly. This is why we need to separate the player's position in the physics simulation from the player's position in the visual representation. The visual representation can then be interpolated smoothly based on the last and current actual player position in the physics simulation. This is a tradeoff: every visual frame is now slightly lagging behind the actual physical frame, but in return, the player's movement will appear smooth. There are other ways to compute the visual representation of the player, such as extrapolation. See the [documentation of the lightyear crate](https://cbournhonesque.github.io/lightyear/book/concepts/advanced_replication/visual_interpolation.html) for a nice overview of the different methods and their tradeoffs. ## Implementation - The player's velocity is stored in a `Velocity` component. This is the speed in units per second. - The player's current position in the physics simulation is stored in a `PhysicalTranslation` component. - The player's previous position in the physics simulation is stored in a `PreviousPhysicalTranslation` component. - The player's visual representation is stored in Bevy's regular `Transform` component. - Every frame, we go through the following steps: - Advance the physics simulation by one fixed timestep in the `advance_physics` system. This is run in the `FixedUpdate` schedule, which runs before the `Update` schedule. - Update the player's visual representation in the `update_displayed_transform` system. This interpolates between the player's previous and current position in the physics simulation. - Update the player's velocity based on the player's input in the `handle_input` system. ## Relevant Issues Related to #1259. I'm also fairly sure I've seen an issue somewhere made by @alice-i-cecile about showing how to move a character correctly in a fixed timestep, but I cannot find it.
2024-07-09 14:23:10 +00:00
[[example]]
name = "physics_in_fixed_timestep"
path = "examples/movement/physics_in_fixed_timestep.rs"
doc-scrape-examples = true
[package.metadata.example.physics_in_fixed_timestep]
name = "Run physics in a fixed timestep"
description = "Handles input, physics, and rendering in an industry-standard way by using a fixed timestep"
category = "Movement"
wasm = true
Start a built-in postprocessing stack, and implement chromatic aberration in it. (#13695) This commit creates a new built-in postprocessing shader that's designed to hold miscellaneous postprocessing effects, and starts it off with chromatic aberration. Possible future effects include vignette, film grain, and lens distortion. [Chromatic aberration] is a common postprocessing effect that simulates lenses that fail to focus all colors of light to a single point. It's often used for impact effects and/or horror games. This patch uses the technique from *Inside* ([Gjøl & Svendsen 2016]), which allows the developer to customize the particular color pattern to achieve different effects. Unity HDRP uses the same technique, while Unreal has a hard-wired fixed color pattern. A new example, `post_processing`, has been added, in order to demonstrate the technique. The existing `post_processing` shader has been renamed to `custom_post_processing`, for clarity. [Chromatic aberration]: https://en.wikipedia.org/wiki/Chromatic_aberration [Gjøl & Svendsen 2016]: https://github.com/playdeadgames/publications/blob/master/INSIDE/rendering_inside_gdc2016.pdf ![Screenshot 2024-06-04 180304](https://github.com/bevyengine/bevy/assets/157897/3631c64f-a615-44fe-91ca-7f04df0a54b2) ![Screenshot 2024-06-04 180743](https://github.com/bevyengine/bevy/assets/157897/ee055cbf-4314-49c5-8bfa-8d8a17bd52bb) ## Changelog ### Added * Chromatic aberration is now available as a built-in postprocessing effect. To use it, add `ChromaticAberration` to your camera.
2024-07-15 13:59:02 +00:00
[[example]]
name = "post_processing"
path = "examples/3d/post_processing.rs"
doc-scrape-examples = true
[package.metadata.example.post_processing]
name = "Built-in postprocessing"
description = "Demonstrates the built-in postprocessing features"
category = "3D Rendering"
wasm = true
Add support for environment map transformation (#14290) # Objective - Fixes: https://github.com/bevyengine/bevy/issues/14036 ## Solution - Add a world space transformation for the environment sample direction. ## Testing - I have tested the newly added `transform` field using the newly added `rotate_environment_map` example. https://github.com/user-attachments/assets/2de77c65-14bc-48ee-b76a-fb4e9782dbdb ## Migration Guide - Since we have added a new filed to the `EnvironmentMapLight` struct, users will need to include `..default()` or some rotation value in their initialization code.
2024-07-19 15:00:50 +00:00
[[example]]
name = "rotate_environment_map"
path = "examples/3d/rotate_environment_map.rs"
doc-scrape-examples = true
required-features = ["pbr_multi_layer_material_textures"]
[package.metadata.example.rotate_environment_map]
name = "Rotate Environment Map"
description = "Demonstrates how to rotate the skybox and the environment map simultaneously"
category = "3D Rendering"
wasm = false
Add mesh picking backend and `MeshRayCast` system parameter (#15800) # Objective Closes #15545. `bevy_picking` supports UI and sprite picking, but not mesh picking. Being able to pick meshes would be extremely useful for various games, tools, and our own examples, as well as scene editors and inspectors. So, we need a mesh picking backend! Luckily, [`bevy_mod_picking`](https://github.com/aevyrie/bevy_mod_picking) (which `bevy_picking` is based on) by @aevyrie already has a [backend for it](https://github.com/aevyrie/bevy_mod_picking/blob/74f0c3c0fbc8048632ba46fd8f14e26aaea9c76c/backends/bevy_picking_raycast/src/lib.rs) using [`bevy_mod_raycast`](https://github.com/aevyrie/bevy_mod_raycast). As a side product of adding mesh picking, we also get support for performing ray casts on meshes! ## Solution Upstream a large chunk of the immediate-mode ray casting functionality from `bevy_mod_raycast`, and add a mesh picking backend based on `bevy_mod_picking`. Huge thanks to @aevyrie who did all the hard work on these incredible crates! All meshes are pickable by default. Picking can be disabled for individual entities by adding `PickingBehavior::IGNORE`, like normal. Or, if you want mesh picking to be entirely opt-in, you can set `MeshPickingBackendSettings::require_markers` to `true` and add a `RayCastPickable` component to the desired camera and target entities. You can also use the new `MeshRayCast` system parameter to cast rays into the world manually: ```rust fn ray_cast_system(mut ray_cast: MeshRayCast, foo_query: Query<(), With<Foo>>) { let ray = Ray3d::new(Vec3::ZERO, Dir3::X); // Only ray cast against entities with the `Foo` component. let filter = |entity| foo_query.contains(entity); // Never early-exit. Note that you can change behavior per-entity. let early_exit_test = |_entity| false; // Ignore the visibility of entities. This allows ray casting hidden entities. let visibility = RayCastVisibility::Any; let settings = RayCastSettings::default() .with_filter(&filter) .with_early_exit_test(&early_exit_test) .with_visibility(visibility); // Cast the ray with the settings, returning a list of intersections. let hits = ray_cast.cast_ray(ray, &settings); } ``` This is largely a direct port, but I did make several changes to match our APIs better, remove things we don't need or that I think are unnecessary, and do some general improvements to code quality and documentation. ### Changes Relative to `bevy_mod_raycast` and `bevy_mod_picking` - Every `Raycast` and "raycast" has been renamed to `RayCast` and "ray cast" (similar reasoning as the "Naming" section in #15724) - `Raycast` system param has been renamed to `MeshRayCast` to avoid naming conflicts and to be explicit that it is not for colliders - `RaycastBackend` has been renamed to `MeshPickingBackend` - `RayCastVisibility` variants are now `Any`, `Visible`, and `VisibleInView` instead of `Ignore`, `MustBeVisible`, and `MustBeVisibleAndInView` - `NoBackfaceCulling` has been renamed to `RayCastBackfaces`, to avoid implying that it affects the rendering of backfaces for meshes (it doesn't) - `SimplifiedMesh` and `RayCastBackfaces` live near other ray casting API types, not in their own 10 LoC module - All intersection logic and types are in the same `intersections` module, not split across several modules - Some intersection types have been renamed to be clearer and more consistent - `IntersectionData` -> `RayMeshHit` - `RayHit` -> `RayTriangleHit` - General documentation and code quality improvements ### Removed / Not Ported - Removed unused ray helpers and types, like `PrimitiveIntersection` - Removed getters on intersection types, and made their properties public - There is no `2d` feature, and `Raycast::mesh_query` and `Raycast::mesh2d_query` have been merged into `MeshRayCast::mesh_query`, which handles both 2D and 3D - I assume this existed previously because `Mesh2dHandle` used to be in `bevy_sprite`. Now both the 2D and 3D mesh are in `bevy_render`. - There is no `debug` feature or ray debug rendering - There is no deferred API (`RaycastSource`) - There is no `CursorRayPlugin` (the picking backend handles this) ### Note for Reviewers In case it's helpful, the [first commit](https://github.com/bevyengine/bevy/commit/281638ef10ebd25f783bee2533509fdf756f7ab4) here is essentially a one-to-one port. The rest of the commits are primarily refactoring and cleaning things up in the ways listed earlier, as well as changes to the module structure. It may also be useful to compare the original [picking backend](https://github.com/aevyrie/bevy_mod_picking/blob/74f0c3c0fbc8048632ba46fd8f14e26aaea9c76c/backends/bevy_picking_raycast/src/lib.rs) and [`bevy_mod_raycast`](https://github.com/aevyrie/bevy_mod_raycast) to this PR. Feel free to mention if there are any changes that I should revert or something I should not include in this PR. ## Testing I tested mesh picking and relevant components in some examples, for both 2D and 3D meshes, and added a new `mesh_picking` example. I also ~~stole~~ ported over the [ray-mesh intersection benchmark](https://github.com/aevyrie/bevy_mod_raycast/blob/dbc5ef32fe48997a1a7eeec7434d9dd8b829e52e/benches/ray_mesh_intersection.rs) from `bevy_mod_raycast`. --- ## Showcase Below is a version of the `2d_shapes` example modified to demonstrate 2D mesh picking. This is not included in this PR. https://github.com/user-attachments/assets/7742528c-8630-4c00-bacd-81576ac432bf And below is the new `mesh_picking` example: https://github.com/user-attachments/assets/b65c7a5a-fa3a-4c2d-8bbd-e7a2c772986e There is also a really cool new `mesh_ray_cast` example ported over from `bevy_mod_raycast`: https://github.com/user-attachments/assets/3c5eb6c0-bd94-4fb0-bec6-8a85668a06c9 --------- Co-authored-by: Aevyrie <aevyrie@gmail.com> Co-authored-by: Trent <2771466+tbillington@users.noreply.github.com> Co-authored-by: François Mockers <mockersf@gmail.com>
2024-10-13 17:24:19 +00:00
[[example]]
name = "mesh_picking"
path = "examples/picking/mesh_picking.rs"
doc-scrape-examples = true
required-features = ["bevy_mesh_picking_backend"]
[package.metadata.example.mesh_picking]
name = "Mesh Picking"
description = "Demonstrates picking meshes"
category = "Picking"
wasm = true
hooking up observers and clicking for ui node (#14695) Makes the newly merged picking usable for UI elements. currently it both triggers the events, as well as sends them as throught commands.trigger_targets. We should probably figure out if this is needed for them all. # Objective Hooks up obserers and picking for a very simple example ## Solution upstreamed the UI picking backend from bevy_mod_picking ## Testing tested with the new example picking/simple_picking.rs --- --------- Co-authored-by: Lixou <82600264+DasLixou@users.noreply.github.com> Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Kristoffer Søholm <k.soeholm@gmail.com>
2024-08-15 14:43:55 +00:00
[[example]]
name = "simple_picking"
path = "examples/picking/simple_picking.rs"
doc-scrape-examples = true
required-features = ["bevy_picking"]
[package.metadata.example.simple_picking]
name = "Showcases simple picking events and usage"
description = "Demonstrates how to use picking events to spawn simple objects"
category = "Picking"
wasm = true
Add bevy_picking sprite backend (#14757) # Objective Add `bevy_picking` sprite backend as part of the `bevy_mod_picking` upstreamening (#12365). ## Solution More or less a copy/paste from `bevy_mod_picking`, with the changes [here](https://github.com/aevyrie/bevy_mod_picking/pull/354). I'm putting that link here since those changes haven't yet made it through review, so should probably be reviewed on their own. ## Testing I couldn't find any sprite-backend-specific tests in `bevy_mod_picking` and unfortunately I'm not familiar enough with Bevy's testing patterns to write tests for code that relies on windowing and input. I'm willing to break the pointer hit system into testable blocks and add some more modular tests if that's deemed important enough to block, otherwise I can open an issue for adding tests as follow-up. ## Follow-up work - More docs/tests - Ignore pick events on transparent sprite pixels with potential opt-out --------- Co-authored-by: Aevyrie <aevyrie@gmail.com>
2024-08-26 18:01:32 +00:00
[[example]]
name = "sprite_picking"
path = "examples/picking/sprite_picking.rs"
doc-scrape-examples = true
feature gate picking backends (#15369) # Objective Fixes #15306 ## Solution - Add feature gate on the module and the place where each one is used - Declare the features and make them default ## Testing - CI
2024-09-22 19:35:15 +00:00
required-features = ["bevy_sprite_picking_backend"]
Add bevy_picking sprite backend (#14757) # Objective Add `bevy_picking` sprite backend as part of the `bevy_mod_picking` upstreamening (#12365). ## Solution More or less a copy/paste from `bevy_mod_picking`, with the changes [here](https://github.com/aevyrie/bevy_mod_picking/pull/354). I'm putting that link here since those changes haven't yet made it through review, so should probably be reviewed on their own. ## Testing I couldn't find any sprite-backend-specific tests in `bevy_mod_picking` and unfortunately I'm not familiar enough with Bevy's testing patterns to write tests for code that relies on windowing and input. I'm willing to break the pointer hit system into testable blocks and add some more modular tests if that's deemed important enough to block, otherwise I can open an issue for adding tests as follow-up. ## Follow-up work - More docs/tests - Ignore pick events on transparent sprite pixels with potential opt-out --------- Co-authored-by: Aevyrie <aevyrie@gmail.com>
2024-08-26 18:01:32 +00:00
[package.metadata.example.sprite_picking]
name = "Sprite Picking"
description = "Demonstrates picking sprites and sprite atlases"
category = "Picking"
wasm = true
feature gate picking backends (#15369) # Objective Fixes #15306 ## Solution - Add feature gate on the module and the place where each one is used - Declare the features and make them default ## Testing - CI
2024-09-22 19:35:15 +00:00
required-features = ["bevy_sprite_picking_backend"]
Add bevy_picking sprite backend (#14757) # Objective Add `bevy_picking` sprite backend as part of the `bevy_mod_picking` upstreamening (#12365). ## Solution More or less a copy/paste from `bevy_mod_picking`, with the changes [here](https://github.com/aevyrie/bevy_mod_picking/pull/354). I'm putting that link here since those changes haven't yet made it through review, so should probably be reviewed on their own. ## Testing I couldn't find any sprite-backend-specific tests in `bevy_mod_picking` and unfortunately I'm not familiar enough with Bevy's testing patterns to write tests for code that relies on windowing and input. I'm willing to break the pointer hit system into testable blocks and add some more modular tests if that's deemed important enough to block, otherwise I can open an issue for adding tests as follow-up. ## Follow-up work - More docs/tests - Ignore pick events on transparent sprite pixels with potential opt-out --------- Co-authored-by: Aevyrie <aevyrie@gmail.com>
2024-08-26 18:01:32 +00:00
Implement animation masks, allowing fine control of the targets that animations affect. (#15013) This commit adds support for *masks* to the animation graph. A mask is a set of animation targets (bones) that neither a node nor its descendants are allowed to animate. Animation targets can be assigned one or more *mask group*s, which are specific to a single graph. If a node masks out any mask group that an animation target belongs to, animation curves for that target will be ignored during evaluation. The canonical use case for masks is to support characters holding objects. Typically, character animations will contain hand animations in the case that the character's hand is empty. (For example, running animations may close a character's fingers into a fist.) However, when the character is holding an object, the animation must be altered so that the hand grips the object. Bevy currently has no convenient way to handle this. The only workaround that I can see is to have entirely separate animation clips for characters' hands and bodies and keep them in sync, which is burdensome and doesn't match artists' expectations from other engines, which all effectively have support for masks. However, with mask group support, this task is simple. We assign each hand to a mask group and parent all character animations to a node. When a character grasps an object in hand, we position the fingers as appropriate and then enable the mask group for that hand in that node. This allows the character's animations to run normally, while the object remains correctly attached to the hand. Note that even with this PR, we won't have support for running separate animations for a character's hand and the rest of the character. This is because we're missing additive blending: there's no way to combine the two masked animations together properly. I intend that to be a follow-up PR. The major engines all have support for masks, though the workflow varies from engine to engine: * Unity has support for masks [essentially as implemented here], though with layers instead of a tree. However, when using the Mecanim ("Humanoid") feature, precise control over bones is lost in favor of predefined muscle groups. * Unreal has a feature named [*layered blend per bone*]. This allows for separate blend weights for different bones, effectively achieving masks. I believe that the combination of blend nodes and masks make Bevy's animation graph as expressible as that of Unreal, once we have support for additive blending, though you may have to use more nodes than you would in Unreal. Moreover, separating out the concepts of "blend weight" and "which bones this node applies to" seems like a cleaner design than what Unreal has. * Godot's `AnimationTree` has the notion of [*blend filters*], which are essentially the same as masks as implemented in this PR. Additionally, this patch fixes a bug with weight evaluation whereby weights weren't properly propagated down to grandchildren, because the weight evaluation for a node only checked its parent's weight, not its evaluated weight. I considered submitting this as a separate PR, but given that this PR refactors that code entirely to support masks and weights under a unified "evaluated node" concept, I simply included the fix here. A new example, `animation_masks`, has been added. It demonstrates how to toggle masks on and off for specific portions of a skin. This is part of #14395, but I'm going to defer closing that issue until we have additive blending. [essentially as implemented here]: https://docs.unity3d.com/560/Documentation/Manual/class-AvatarMask.html [*layered blend per bone*]: https://dev.epicgames.com/documentation/en-us/unreal-engine/using-layered-animations-in-unreal-engine [*blend filters*]: https://docs.godotengine.org/en/stable/tutorials/animation/animation_tree.html ## Migration Guide * The serialized format of animation graphs has changed with the addition of animation masks. To upgrade animation graph RON files, add `mask` and `mask_groups` fields as appropriate. (They can be safely set to zero.)
2024-09-02 17:10:34 +00:00
[[example]]
name = "animation_masks"
path = "examples/animation/animation_masks.rs"
doc-scrape-examples = true
[package.metadata.example.animation_masks]
name = "Animation Masks"
description = "Demonstrates animation masks"
category = "Animation"
wasm = true
Implement percentage-closer soft shadows (PCSS). (#13497) [*Percentage-closer soft shadows*] are a technique from 2004 that allow shadows to become blurrier farther from the objects that cast them. It works by introducing a *blocker search* step that runs before the normal shadow map sampling. The blocker search step detects the difference between the depth of the fragment being rasterized and the depth of the nearby samples in the depth buffer. Larger depth differences result in a larger penumbra and therefore a blurrier shadow. To enable PCSS, fill in the `soft_shadow_size` value in `DirectionalLight`, `PointLight`, or `SpotLight`, as appropriate. This shadow size value represents the size of the light and should be tuned as appropriate for your scene. Higher values result in a wider penumbra (i.e. blurrier shadows). When using PCSS, temporal shadow maps (`ShadowFilteringMethod::Temporal`) are recommended. If you don't use `ShadowFilteringMethod::Temporal` and instead use `ShadowFilteringMethod::Gaussian`, Bevy will use the same technique as `Temporal`, but the result won't vary over time. This produces a rather noisy result. Doing better would likely require downsampling the shadow map, which would be complex and slower (and would require PR #13003 to land first). In addition to PCSS, this commit makes the near Z plane for the shadow map configurable on a per-light basis. Previously, it had been hardcoded to 0.1 meters. This change was necessary to make the point light shadow map in the example look reasonable, as otherwise the shadows appeared far too aliased. A new example, `pcss`, has been added. It demonstrates the percentage-closer soft shadow technique with directional lights, point lights, spot lights, non-temporal operation, and temporal operation. The assets are my original work. Both temporal and non-temporal shadows are rather noisy in the example, and, as mentioned before, this is unavoidable without downsampling the depth buffer, which we can't do yet. Note also that the shadows don't look particularly great for point lights; the example simply isn't an ideal scene for them. Nevertheless, I felt that the benefits of the ability to do a side-by-side comparison of directional and point lights outweighed the unsightliness of the point light shadows in that example, so I kept the point light feature in. Fixes #3631. [*Percentage-closer soft shadows*]: https://developer.download.nvidia.com/shaderlibrary/docs/shadow_PCSS.pdf ## Changelog ### Added * Percentage-closer soft shadows (PCSS) are now supported, allowing shadows to become blurrier as they stretch away from objects. To use them, set the `soft_shadow_size` field in `DirectionalLight`, `PointLight`, or `SpotLight`, as applicable. * The near Z value for shadow maps is now customizable via the `shadow_map_near_z` field in `DirectionalLight`, `PointLight`, and `SpotLight`. ## Screenshots PCSS off: ![Screenshot 2024-05-24 120012](https://github.com/bevyengine/bevy/assets/157897/0d35fe98-245b-44fb-8a43-8d0272a73b86) PCSS on: ![Screenshot 2024-05-24 115959](https://github.com/bevyengine/bevy/assets/157897/83397ef8-1317-49dd-bfb3-f8286d7610cd) --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Torstein Grindvik <52322338+torsteingrindvik@users.noreply.github.com>
2024-09-18 18:07:17 +00:00
[[example]]
name = "pcss"
path = "examples/3d/pcss.rs"
doc-scrape-examples = true
Make PCSS experimental (#16382) # Objective PCSS still has some fundamental issues (#16155). We should resolve them before "releasing" the feature. ## Solution 1. Rename the already-optional `pbr_pcss` cargo feature to `experimental_pbr_pcss` to better communicate its state to developers. 2. Adjust the description of the `experimental_pbr_pcss` cargo feature to better communicate its state to developers. 3. Gate PCSS-related light component fields behind that cargo feature, to prevent surfacing them to developers by default.
2024-11-14 07:39:26 +00:00
required-features = ["experimental_pbr_pcss"]
Implement percentage-closer soft shadows (PCSS). (#13497) [*Percentage-closer soft shadows*] are a technique from 2004 that allow shadows to become blurrier farther from the objects that cast them. It works by introducing a *blocker search* step that runs before the normal shadow map sampling. The blocker search step detects the difference between the depth of the fragment being rasterized and the depth of the nearby samples in the depth buffer. Larger depth differences result in a larger penumbra and therefore a blurrier shadow. To enable PCSS, fill in the `soft_shadow_size` value in `DirectionalLight`, `PointLight`, or `SpotLight`, as appropriate. This shadow size value represents the size of the light and should be tuned as appropriate for your scene. Higher values result in a wider penumbra (i.e. blurrier shadows). When using PCSS, temporal shadow maps (`ShadowFilteringMethod::Temporal`) are recommended. If you don't use `ShadowFilteringMethod::Temporal` and instead use `ShadowFilteringMethod::Gaussian`, Bevy will use the same technique as `Temporal`, but the result won't vary over time. This produces a rather noisy result. Doing better would likely require downsampling the shadow map, which would be complex and slower (and would require PR #13003 to land first). In addition to PCSS, this commit makes the near Z plane for the shadow map configurable on a per-light basis. Previously, it had been hardcoded to 0.1 meters. This change was necessary to make the point light shadow map in the example look reasonable, as otherwise the shadows appeared far too aliased. A new example, `pcss`, has been added. It demonstrates the percentage-closer soft shadow technique with directional lights, point lights, spot lights, non-temporal operation, and temporal operation. The assets are my original work. Both temporal and non-temporal shadows are rather noisy in the example, and, as mentioned before, this is unavoidable without downsampling the depth buffer, which we can't do yet. Note also that the shadows don't look particularly great for point lights; the example simply isn't an ideal scene for them. Nevertheless, I felt that the benefits of the ability to do a side-by-side comparison of directional and point lights outweighed the unsightliness of the point light shadows in that example, so I kept the point light feature in. Fixes #3631. [*Percentage-closer soft shadows*]: https://developer.download.nvidia.com/shaderlibrary/docs/shadow_PCSS.pdf ## Changelog ### Added * Percentage-closer soft shadows (PCSS) are now supported, allowing shadows to become blurrier as they stretch away from objects. To use them, set the `soft_shadow_size` field in `DirectionalLight`, `PointLight`, or `SpotLight`, as applicable. * The near Z value for shadow maps is now customizable via the `shadow_map_near_z` field in `DirectionalLight`, `PointLight`, and `SpotLight`. ## Screenshots PCSS off: ![Screenshot 2024-05-24 120012](https://github.com/bevyengine/bevy/assets/157897/0d35fe98-245b-44fb-8a43-8d0272a73b86) PCSS on: ![Screenshot 2024-05-24 115959](https://github.com/bevyengine/bevy/assets/157897/83397ef8-1317-49dd-bfb3-f8286d7610cd) --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Torstein Grindvik <52322338+torsteingrindvik@users.noreply.github.com>
2024-09-18 18:07:17 +00:00
[package.metadata.example.pcss]
name = "Percentage-closer soft shadows"
description = "Demonstrates percentage-closer soft shadows (PCSS)"
category = "3D Rendering"
wasm = false
Allow animation clips to animate arbitrary properties. (#15282) Currently, Bevy restricts animation clips to animating `Transform::translation`, `Transform::rotation`, `Transform::scale`, or `MorphWeights`, which correspond to the properties that glTF can animate. This is insufficient for many use cases such as animating UI, as the UI layout systems expect to have exclusive control over UI elements' `Transform`s and therefore the `Style` properties must be animated instead. This commit fixes this, allowing for `AnimationClip`s to animate arbitrary properties. The `Keyframes` structure has been turned into a low-level trait that can be implemented to achieve arbitrary animation behavior. Along with `Keyframes`, this patch adds a higher-level trait, `AnimatableProperty`, that simplifies the task of animating single interpolable properties. Built-in `Keyframes` implementations exist for translation, rotation, scale, and morph weights. For the most part, you can migrate by simply changing your code from `Keyframes::Translation(...)` to `TranslationKeyframes(...)`, and likewise for rotation, scale, and morph weights. An example `AnimatableProperty` implementation for the font size of a text section follows: #[derive(Reflect)] struct FontSizeProperty; impl AnimatableProperty for FontSizeProperty { type Component = Text; type Property = f32; fn get_mut(component: &mut Self::Component) -> Option<&mut Self::Property> { Some(&mut component.sections.get_mut(0)?.style.font_size) } } In order to keep this patch relatively small, this patch doesn't include an implementation of `AnimatableProperty` on top of the reflection system. That can be a follow-up. This patch builds on top of the new `EntityMutExcept<>` type in order to widen the `AnimationTarget` query to include write access to all components. Because `EntityMutExcept<>` has some performance overhead over an explicit query, we continue to explicitly query `Transform` in order to avoid regressing the performance of skeletal animation, such as the `many_foxes` benchmark. I've measured the performance of that benchmark and have found no significant regressions. A new example, `animated_ui`, has been added. This example shows how to use Bevy's built-in animation infrastructure to animate font size and color, which wasn't possible before this patch. ## Showcase https://github.com/user-attachments/assets/1fa73492-a9ce-405a-a8f2-4aacd7f6dc97 ## Migration Guide * Animation keyframes are now an extensible trait, not an enum. Replace `Keyframes::Translation(...)`, `Keyframes::Scale(...)`, `Keyframes::Rotation(...)`, and `Keyframes::Weights(...)` with `Box::new(TranslationKeyframes(...))`, `Box::new(ScaleKeyframes(...))`, `Box::new(RotationKeyframes(...))`, and `Box::new(MorphWeightsKeyframes(...))` respectively.
2024-09-23 17:14:12 +00:00
[[example]]
name = "animated_ui"
path = "examples/animation/animated_ui.rs"
doc-scrape-examples = true
[package.metadata.example.animated_ui]
name = "Animated UI"
description = "Shows how to use animation clips to animate UI properties"
category = "Animation"
wasm = true
Wasm optimization tips (#5443) # Objective Add a section to the example's README on how to reduce generated wasm executable size. Add a `wasm-release` profile to bevy's `Cargo.toml` in order to use it when building bevy-website. Notes: - We do not recommend `strip = "symbols"` since it breaks bindgen - see https://github.com/bevyengine/bevy-website/pull/402
2022-07-25 15:48:13 +00:00
[profile.wasm-release]
inherits = "release"
opt-level = "z"
lto = "fat"
codegen-units = 1
Add a stress test profile (#6901) # Objective This adds a custom profile for testing against stress tests. Bevy seemingly gets notably faster with LTO turned on. To more accurately depict production level performance, LTO and other rustc-level optimizations should be enabled when performance testing on stress tests. Also updated the stress test docs to reflect that users should be using it.
2022-12-20 15:59:41 +00:00
[profile.stress-test]
inherits = "release"
lto = "fat"
panic = "abort"
Rustdoc: Scrape examples (#9154) # Objective Provide more usage examples in API docs so that people can see methods being used in context. ## Solution Enable experimental rustdoc feature "scrape examples". See <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> for official docs. ## Example screenshots of examples :) <img width="1013" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/7abc8baa-3149-476f-b2f2-ce7693758bee"> <img width="1033" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/163e7e22-c55e-46ab-8f3d-75fb97c3ad7a"> <img width="1009" alt="image" src="https://github.com/bevyengine/bevy/assets/20063/a50b1147-e252-43f3-9adb-81960b8aa6c3"> ## Limitations - Only methods seem to show examples so far - It may be confusing to have curated examples from doc comments followed by snippets from `examples/` --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-08-10 00:27:39 +00:00
[package.metadata.docs.rs]
Use `#[doc(fake_variadic)]` to improve docs readability (#14703) # Objective - Fixes #14697 ## Solution This PR modifies the existing `all_tuples!` macro to optionally accept a `#[doc(fake_variadic)]` attribute in its input. If the attribute is present, each invocation of the impl macro gets the correct attributes (i.e. the first impl receives `#[doc(fake_variadic)]` while the other impls are hidden using `#[doc(hidden)]`. Impls for the empty tuple (unit type) are left untouched (that's what the [standard library](https://doc.rust-lang.org/std/cmp/trait.PartialEq.html#impl-PartialEq-for-()) and [serde](https://docs.rs/serde/latest/serde/trait.Serialize.html#impl-Serialize-for-()) do). To work around https://github.com/rust-lang/cargo/issues/8811 and to get impls on re-exports to correctly show up as variadic, `--cfg docsrs_dep` is passed when building the docs for the toplevel `bevy` crate. `#[doc(fake_variadic)]` only works on tuples and fn pointers, so impls for structs like `AnyOf<(T1, T2, ..., Tn)>` are unchanged. ## Testing I built the docs locally using `RUSTDOCFLAGS='--cfg docsrs' RUSTFLAGS='--cfg docsrs_dep' cargo +nightly doc --no-deps --workspace` and checked the documentation page of a trait both in its original crate and the re-exported version in `bevy`. The description should correctly mention for how many tuple items the trait is implemented. I added `rustc-args` for docs.rs to the `bevy` crate, I hope there aren't any other notable crates that re-export `#[doc(fake_variadic)]` traits. --- ## Showcase `bevy_ecs::query::QueryData`: <img width="1015" alt="Screenshot 2024-08-12 at 16 41 28" src="https://github.com/user-attachments/assets/d40136ed-6731-475f-91a0-9df255cd24e3"> `bevy::ecs::query::QueryData` (re-export): <img width="1005" alt="Screenshot 2024-08-12 at 16 42 57" src="https://github.com/user-attachments/assets/71d44cf0-0ab0-48b0-9a51-5ce332594e12"> ## Original Description <details> Resolves #14697 Submitting as a draft for now, very WIP. Unfortunately, the docs don't show the variadics nicely when looking at reexported items. For example: `bevy_ecs::bundle::Bundle` correctly shows the variadic impl: ![image](https://github.com/user-attachments/assets/90bf8af1-1d1f-4714-9143-cdd3d0199998) while `bevy::ecs::bundle::Bundle` (the reexport) shows all the impls (not good): ![image](https://github.com/user-attachments/assets/439c428e-f712-465b-bec2-481f7bf5870b) Built using `RUSTDOCFLAGS='--cfg docsrs' cargo +nightly doc --workspace --no-deps` (`--no-deps` because of wgpu-core). Maybe I missed something or this is a limitation in the *totally not private* `#[doc(fake_variadic)]` thingy. In any case I desperately need some sleep now :)) </details>
2024-08-12 18:54:33 +00:00
# This cfg is needed so that #[doc(fake_variadic)] is correctly propagated for
# impls for re-exported traits. See https://github.com/rust-lang/cargo/issues/8811
# for details on why this is needed. Since dependencies don't expect to be built
# with `--cfg docsrs` (and thus fail to compile) we use a different cfg.
Sync flags in docs.yml with `package.metadata.docs.rs` (#14734) # Objective This PR is a follow-up to #14703. I forgot to also add the flags from `package.metadata.docs.rs` to the docs build. ## Solution As [discussed on Discord](https://discord.com/channels/691052431525675048/1272629407659589663/1272643734260940940), I added the missing flags to `docs.yml`. I also updated `rustc-args` to properly make use of the array (I think the value has to be either a space-separated string *or* an array of strings but not an array of space-separated strings 😆)
2024-08-14 13:30:45 +00:00
rustc-args = ["--cfg", "docsrs_dep"]
Generate links to definition in source code pages on docs.rs and dev-docs.bevyengine.org (#12965) # Objective - Fix issue #2611 ## Solution - Add `--generate-link-to-definition` to all the `rustdoc-args` arrays in the `Cargo.toml`s (for docs.rs) - Add `--generate-link-to-definition` to the `RUSTDOCFLAGS` environment variable in the docs workflow (for dev-docs.bevyengine.org) - Document all the workspace crates in the docs workflow (needed because otherwise only the source code of the `bevy` package will be included, making the argument useless) - I think this also fixes #3662, since it fixes the bug on dev-docs.bevyengine.org, while on docs.rs it has been fixed for a while on their side. --- ## Changelog - The source code viewer on docs.rs now includes links to the definitions.
2024-07-29 23:10:16 +00:00
rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
Add "all-features = true" to docs.rs metadata for most crates (#12366) # Objective Fix missing `TextBundle` (and many others) which are present in the main crate as default features but optional in the sub-crate. See: - https://docs.rs/bevy/0.13.0/bevy/ui/node_bundles/index.html - https://docs.rs/bevy_ui/0.13.0/bevy_ui/node_bundles/index.html ~~There are probably other instances in other crates that I could track down, but maybe "all-features = true" should be used by default in all sub-crates? Not sure.~~ (There were many.) I only noticed this because rust-analyzer's "open docs" features takes me to the sub-crate, not the main one. ## Solution Add "all-features = true" to docs.rs metadata for crates that use features. ## Changelog ### Changed - Unified features documented on docs.rs between main crate and sub-crates
2024-03-08 20:03:09 +00:00
all-features = true
Make `feature(doc_auto_cfg)` work (#12642) # Objective - In #12366 `![cfg_attr(docsrs, feature(doc_auto_cfg))] `was added. But to apply it it needs `--cfg=docsrs` in rustdoc-args. ## Solution - Apply `--cfg=docsrs` to all crates and CI. I also added `[package.metadata.docs.rs]` to all crates to avoid adding code behind a feature and forget adding the metadata. Before: ![Screenshot 2024-03-22 at 00 51 57](https://github.com/bevyengine/bevy/assets/104745335/6a9dfdaa-8710-4784-852b-5f9b74e3522c) After: ![Screenshot 2024-03-22 at 00 51 32](https://github.com/bevyengine/bevy/assets/104745335/c5bd6d8e-8ddb-45b3-b844-5ecf9f88961c)
2024-03-23 02:22:52 +00:00
cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
Expose winit's `MonitorHandle` (#13669) # Objective Adds a new `Monitor` component representing a winit `MonitorHandle` that can be used to spawn new windows and check for system monitor information. Closes #12955. ## Solution For every winit event, check available monitors and spawn them into the world as components. ## Testing TODO: - [x] Test plugging in and unplugging monitor during app runtime - [x] Test spawning a window on a second monitor by entity id - [ ] Since this touches winit, test all platforms --- ## Changelog - Adds a new `Monitor` component that can be queried for information about available system monitors. ## Migration Guide - `WindowMode` variants now take a `MonitorSelection`, which can be set to `MonitorSelection::Primary` to mirror the old behavior. --------- Co-authored-by: Pascal Hertleif <pascal@technocreatives.com> Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Pascal Hertleif <killercup@gmail.com>
2024-08-06 10:54:37 +00:00
[[example]]
name = "monitor_info"
path = "examples/window/monitor_info.rs"
doc-scrape-examples = true
[package.metadata.example.monitor_info]
name = "Monitor info"
description = "Displays information about available monitors (displays)."
category = "Window"
wasm = false
Introduce testbed examples starting with 2d (#15954) # Objective - Make progress for #15918 - Start with 2d ## Solution - Remove screenshots for existing examples as they're not deterministic - Create new "testbed" example category, with a 2d one to start ## Testing - Run `CI_TESTING_CONFIG=.github/example-run/testbed_2d.ron cargo run --example testbed_2d --features "bevy_ci_testing"` - ??? - Check the screenshots
2024-10-16 17:37:47 +00:00
# Testbed
[[example]]
name = "testbed_2d"
path = "examples/testbed/2d.rs"
doc-scrape-examples = true
[package.metadata.example.testbed_2d]
hidden = true
Testbed for 3d (#15993) # Objective - Progress towards #15918 - Add tests for 3d ## Solution - Add tests that cover lights, bloom, gltf and animation - Removed examples `contributors` and `load_gltf` as they don't contribute additional checks to CI ## Testing - `CI_TESTING_CONFIG=.github/example-run/testbed_3d.ron cargo run --example testbed_3d --features "bevy_ci_testing"`
2024-10-19 19:32:03 +00:00
[[example]]
name = "testbed_3d"
path = "examples/testbed/3d.rs"
doc-scrape-examples = true
[package.metadata.example.testbed_3d]
hidden = true
Layout rounding debug example (#16096) # Objective Simple example for debugging layout rounding errors. <img width="1039" height="752" alt="layout_rounding_debug" src="https://github.com/user-attachments/assets/12673000-e267-467e-b25b-3f8001c1347c"> Any white lines are gaps in the layout caused by coordinate rounding errors.
2024-10-27 20:08:51 +00:00
Move UI example to testbed (#16241) # Objective UI example is quite extensive, probably not the best teaching example anymore. Closes #16230.
2024-11-07 20:57:45 +00:00
[[example]]
name = "testbed_ui"
path = "examples/testbed/ui.rs"
doc-scrape-examples = true
[package.metadata.example.testbed_ui]
hidden = true
Layout rounding debug example (#16096) # Objective Simple example for debugging layout rounding errors. <img width="1039" height="752" alt="layout_rounding_debug" src="https://github.com/user-attachments/assets/12673000-e267-467e-b25b-3f8001c1347c"> Any white lines are gaps in the layout caused by coordinate rounding errors.
2024-10-27 20:08:51 +00:00
[[example]]
name = "testbed_ui_layout_rounding"
path = "examples/testbed/ui_layout_rounding.rs"
doc-scrape-examples = true
[package.metadata.example.testbed_ui_layout_rounding]
hidden = true
Reference in a new issue Copy permalink