From 3bd3a4c6b8305611433dbfd9d93b4ffa9326ed53 Mon Sep 17 00:00:00 2001 From: MiniaczQ Date: Thu, 31 Oct 2024 17:43:19 +0100 Subject: [PATCH] Fallible param notes (#1729) Co-authored-by: Alice Cecile --- ...e_panics_through_SystemParam_validation.md | 57 ++++++++++++++++++- ...476_QuerySingle_family_of_system_params.md | 4 -- .../15488_Populated_query_system_param.md | 4 -- .../0.15/release-notes/_release-notes.toml | 20 +------ 4 files changed, 59 insertions(+), 26 deletions(-) delete mode 100644 release-content/0.15/release-notes/15476_QuerySingle_family_of_system_params.md delete mode 100644 release-content/0.15/release-notes/15488_Populated_query_system_param.md diff --git a/release-content/0.15/release-notes/15276_Reduce_runtime_panics_through_SystemParam_validation.md b/release-content/0.15/release-notes/15276_Reduce_runtime_panics_through_SystemParam_validation.md index 833bc8962f..b0ccedb251 100644 --- a/release-content/0.15/release-notes/15276_Reduce_runtime_panics_through_SystemParam_validation.md +++ b/release-content/0.15/release-notes/15276_Reduce_runtime_panics_through_SystemParam_validation.md @@ -1,4 +1,59 @@ - + + + + + + + +In Bevy 0.14 and prior, the following code would panic: +```rust +#[derive(Resource)] +struct MyResource; + +fn my_system(my_resource: Res) {} + +fn main() { + let mut app = App::new(); + app.add_plugins(DefaultPlugins) + app.add_systems(my_system); + // Panic here: `my_system` cannot fetch `MyResource`, because it was never added. + app.run(); +} +``` +but in Bevy 0.15, `my_system` simply won't be executed. + +This works for all system-based features: +- Systems & Observers - will be skipped, +- Run conditions - will be skipped and return `false`. + +Compound systems, like `system_a.pipe(system_b)`, are currently skipped if any required data is missing. + +Pre-existing parameters which now benefit from this feature are: `Res` and `ResMut` as well as their siblings `NonSend` and `NonSendMut`. +Parameters that build on top of other parameters: tuples, `DynSystemParam` and `ParamSet` are considered present if and only if all of their system parameters are present. + +Additionally, few new system params were introduced to simplify existing code: +- `Single` - Works like `Query::single`, fails if query contains 0 or more than 1 match, +- `Option>` - Works like `Query::single`, fails if query contains more than 1 match, +- `Populated` - Works like a `Query`, fails if query contains no matches. + +## Warnings + +Fallible system params come with a primitive warning mechanic. +Currently, systems can behave in one of two ways: +- (default) warn exactly once, +- never warn. + +The default can be changed as following: +```rust +// For systems +app.add_systems(my_system.never_param_warn()); +// For observers +app.add_observer(my_observer.never_param_warn()); +// For run conditions +app.add_systems(my_system.run_if(my_condition.never_param_warn())); +``` + +Let us know what other warning strategies you'd like! diff --git a/release-content/0.15/release-notes/15476_QuerySingle_family_of_system_params.md b/release-content/0.15/release-notes/15476_QuerySingle_family_of_system_params.md deleted file mode 100644 index cf42ae0270..0000000000 --- a/release-content/0.15/release-notes/15476_QuerySingle_family_of_system_params.md +++ /dev/null @@ -1,4 +0,0 @@ - - - - diff --git a/release-content/0.15/release-notes/15488_Populated_query_system_param.md b/release-content/0.15/release-notes/15488_Populated_query_system_param.md deleted file mode 100644 index bf214c2db8..0000000000 --- a/release-content/0.15/release-notes/15488_Populated_query_system_param.md +++ /dev/null @@ -1,4 +0,0 @@ - - - - diff --git a/release-content/0.15/release-notes/_release-notes.toml b/release-content/0.15/release-notes/_release-notes.toml index e81d202c68..970748dc08 100644 --- a/release-content/0.15/release-notes/_release-notes.toml +++ b/release-content/0.15/release-notes/_release-notes.toml @@ -244,10 +244,10 @@ prs = [14920] file_name = "14920_Add_cached_run_system_API.md" [[release_notes]] -title = "Reduce runtime panics through `SystemParam` validation" +title = "Fallible system parameters" authors = ["@MiniaczQ"] -contributors = [] -prs = [15276] +contributors = ["@alice-i-cecile"] +prs = [15276, 15476, 15488] file_name = "15276_Reduce_runtime_panics_through_SystemParam_validation.md" [[release_notes]] @@ -311,13 +311,6 @@ contributors = ["@cart"] prs = [12770] file_name = "12770_Implement_gamepads_as_entities.md" -[[release_notes]] -title = "`QuerySingle` family of system params" -authors = ["@MiniaczQ"] -contributors = [] -prs = [15476] -file_name = "15476_QuerySingle_family_of_system_params.md" - [[release_notes]] title = "Implement volumetric fog support for both point lights and spotlights" authors = ["@Soulghost"] @@ -353,13 +346,6 @@ contributors = [] prs = [14838] file_name = "14838_bevy_reflect_add_Type_type.md" -[[release_notes]] -title = "`Populated` (query) system param" -authors = ["@MiniaczQ"] -contributors = ["@alice-i-cecile"] -prs = [15488] -file_name = "15488_Populated_query_system_param.md" - [[release_notes]] title = "Runtime required components" authors = ["@Jondolf"]