From aaa3a5b9282eeb25c5a324ba2d582de7e929e6eb Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Thu, 31 Jul 2025 11:53:35 -0700 Subject: [PATCH 1/3] Release notes for generic component propagation --- .../generic_component_propagation.md | 34 +++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 release-content/release-notes/generic_component_propagation.md diff --git a/release-content/release-notes/generic_component_propagation.md b/release-content/release-notes/generic_component_propagation.md new file mode 100644 index 0000000000000..156b4152896eb --- /dev/null +++ b/release-content/release-notes/generic_component_propagation.md @@ -0,0 +1,34 @@ +--- +title: Generic component propagation +authors: ["@robtfm"] +pull_requests: [17575] +--- + +When working with large hierarchies of game objects, coordinating the state of the entire tree can be frustrating. +Bevy uses this pattern when working with transforms and visibility internally, +but users have had to reinvent the wheel every time they wanted to use similar patterns. + +While this pain was most acute when working with [`RenderLayers`], this pattern is more broadly useful, +and has been exposed to end users in the form of the [`HierarchyPropagatePlugin`]. +You might use this for synchronizing color and alpha values for "ghost" versions of previewed buildings, +ensuring that all of the parts of a model are on the same render layer, +or ensuring that all members of a village share the same goals in your simulation game. + +This plugin has three generics: + +- `C: Component`: the type of component that should be propagated +- `F: QueryFilter=()`: if set, only entities which match this filter will be affected by propagation +- `R: Relationship = ChildOf`: the type of tree-like relationship to propagate down + +Each copy of this plugin will propagate components of type `C` down the hierarchy, along all entities which match the +query filter of type `F`. +With this plugin enabled for `C`, you can add a [`Propagate`] component to add new components to all children, +add a [`PropagateStop`] component to stop propagation, or even use [`PropagateOver`] to skip this entity during propagation. + +This is a very general tool: please let us know what you're using it for and we can continue to add examples to the docs! + +[`RenderLayers`]: https://dev-docs.bevy.org/bevy/camera/visibility/struct.RenderLayers.html +[`HierarchyPropagatePlugin`]: https://dev-docs.bevy.org/bevy/app/struct.HierarchyPropagatePlugin.html +[`Propagate`]: https://dev-docs.bevy.org/bevy/app/struct.Propagate.html +[`PropagateStop`]: https://dev-docs.bevy.org/bevy/app/struct.PropagateStop.html +[`PropagateOver`]: https://dev-docs.bevy.org/bevy/app/struct.PropagateOver.html From eb130f4fe9fb7a5256f5096027358e965b1b9c23 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Thu, 31 Jul 2025 17:15:55 -0400 Subject: [PATCH 2/3] Font style usage suggestion --- release-content/release-notes/generic_component_propagation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/release-content/release-notes/generic_component_propagation.md b/release-content/release-notes/generic_component_propagation.md index 156b4152896eb..4a13508ffbf05 100644 --- a/release-content/release-notes/generic_component_propagation.md +++ b/release-content/release-notes/generic_component_propagation.md @@ -12,7 +12,7 @@ While this pain was most acute when working with [`RenderLayers`], this pattern and has been exposed to end users in the form of the [`HierarchyPropagatePlugin`]. You might use this for synchronizing color and alpha values for "ghost" versions of previewed buildings, ensuring that all of the parts of a model are on the same render layer, -or ensuring that all members of a village share the same goals in your simulation game. +or propagating font styles. This plugin has three generics: From bee1d2dda2e9180e7543542904e1e309228934e4 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Thu, 31 Jul 2025 14:18:27 -0700 Subject: [PATCH 3/3] Add note on system sets and ordering --- crates/bevy_app/src/propagate.rs | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/crates/bevy_app/src/propagate.rs b/crates/bevy_app/src/propagate.rs index 2cfaf6bda767e..4c130df21a882 100644 --- a/crates/bevy_app/src/propagate.rs +++ b/crates/bevy_app/src/propagate.rs @@ -30,6 +30,11 @@ use bevy_reflect::Reflect; /// to reach a given target. /// Individual entities can be skipped or terminate the propagation with the [`PropagateOver`] /// and [`PropagateStop`] components. +/// +/// Propagation occurs during [`Update`] in the [`PropagateSet`] system set. +/// You should be sure to schedule your logic relative to this set: making changes +/// that modify component values before this logic, and reading the propagated +/// values after it. pub struct HierarchyPropagatePlugin< C: Component + Clone + PartialEq, F: QueryFilter = (),