Cargo.lock

@@ -3022,6 +3022,26 @@ dependencies = [
  "bevy_sprite",
  "bevy_text",
  "bevy_ui",
+ "weirdboi_tween",
+]
+
+[[package]]
+name = "weirdboi_tween"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "427af3fddbb65e5d6dba9114f65faf5cf9f2848eed42af44477dabd260499264"
+dependencies = [
+ "bevy_app",
+ "bevy_color",
+ "bevy_derive",
+ "bevy_ecs",
+ "bevy_math",
+ "bevy_sprite",
+ "bevy_text",
+ "bevy_time",
+ "bevy_transform",
+ "bevy_ui",
+ "log",
 ]
 
 [[package]]

Cargo.toml

@@ -2,19 +2,25 @@
 name = "weirdboi_opacity_tree"
 version = "0.1.0"
 edition = "2024"
+license = "Apache-2.0"
+description = "Adds push down opacity hierarchy to Bevy entities"
 
 [features]
 default = ["reflect", "ui", "sprite"]
 reflect = ["dep:bevy_reflect"]
 ui = ["dep:bevy_ui", "dep:bevy_text", "dep:bevy_color"]
 sprite = ["dep:bevy_sprite", "dep:bevy_color"]
+tween = ["dep:weirdboi_tween"]
 
 [dependencies]
 bevy_ecs = "0.16"
 bevy_app = "0.16"
 bevy_math = "0.16"
+
 bevy_reflect = { version = "0.16", optional = true }
 bevy_ui = { version = "0.16", optional = true }
 bevy_text = { version = "0.16", optional = true }
 bevy_sprite = { version = "0.16", optional = true }
-bevy_color = { version = "0.16", optional = true }
\ No newline at end of file
+bevy_color = { version = "0.16", optional = true }
+
+weirdboi_tween = { version = "0.1.0", optional = true }
\ No newline at end of file

README.md

+# Opacity Tree
+
+Adds hierarchical inheritance of opacity to Bevy entities.
+
+## Usage
+
+1. Add weirdboi_opacity_tree to you Cargo.toml
+2. Include the plugin in your app
+3. Add the `TreeOpacity` component to any supported node whose children should inherit its opacity
+4. In any system, set the value of the `TreeOpacity` component
+
+ ```toml
+ # There is no current crates release
+ weirdboi_opacity_tree = { git = "https://weirdboi.dev/libraries/weirdboi-opacity-tree.git" }
+ ```
+
+```rust
+//! Entry point for your game, main.rs
+use weirdboi_opacity_tree::TreeOpacityPlugin;
+
+fn main() {
+   // Create your app, then..
+   
+   app.add_plugins(TreeOpacityPlugin);
+}
+```
+
+```rust
+//! Some gameplay code, where a window has to fade out
+pub fn spawn_entity(mut commands: Commands) {
+   commands.spawn((
+      Node::default(),
+      ImageNode::default(),
+      TreeOpacity::default(), // Default value is 1, full opacity
+   )).with_children(|children| {
+      children.spawn(Text::new("Some value")); // The opacity of the text will sync with the parent node
+   });
+}
+
+pub fn alter_entity(mut query: Query<&mut TreeOpacity>) {
+   for mut root in &mut query {
+       root.set_opacity(0.0); // Hide the entire tree of elements
+   }
+}
+```
+
+## Supported Components
+
+This library add component support for built in Bevy components by default, although this can be disabled by turning off
+default features when adding to you Cargo.toml. The following feature flags will enable different sets of components:
+
+- `ui`: Enables support for `TextColor`, `TextShadow`, `ImageNode`, `BackgroundColor`, and `BorderColor`
+- `sprite`: Enables support for `Sprite`
+
+## Ignoring Changes
+
+If a particular component `C` should not have its opacity modified as part of a tree, you can add the `IgnoreOpacity<C>` 
+component to its entity. This is typically desirable for things like Text nodes, where the required components will add
+elements that you don't want to change.
+
+This use case is also supported by the `presets` module, which exports utility functions for common bundles of ignored
+changes - e.g. `presets::text_node_opacity_preset()` will return a bundle that ignores changes for Background and Border
+color. Without these `IgnoreOpacity` components, the background of a text node would become black when setting the opacity
+of a parent to 1
+
+## Custom Components
+
+Any **mutable** component can be included in the opacity tree calculations by implementing `HandlesTreeOpacity` and then registering
+it with your app. Immutable components cannot be registered for handling by the opacity tree.
+
+```rust
+#[derive(Component)]
+struct MyCustomRenderable {
+    alpha: f32,
+}
+
+impl HandlesTreeOpacity for MyCustomRenderable {
+    fn on_change_opacity(&mut self, opacity: f32) {
+        self.alpha = opacity;
+    }
+}
+
+pub fn my_plugin(app: &mut App) {
+    app.register_opacity_type::<MyCustomRenderable>();
+}
+```
+
+## `weirdboi_tween`
+
+Enabling the optional feature `tween` allows this library to integrate with `weirdboi_tween`'s "tween anything" system 
+using the `TweenTreeOpacity` zst.
+
+For use with other methods of tweening, animation, etc - TreeOpacity implements `Ease` from `bevy_math`, which should ease
+integration
\ No newline at end of file

src/lib.rs

@@ -7,10 +7,14 @@ pub mod presets;
 mod bevy_ui_ext;
 #[cfg(feature = "sprite")]
 mod bevy_sprite_ext;
+#[cfg(feature = "tween")]
+mod weirdboi_tween_ext;
 
 pub use opacity_tree::{
 	HandlesTreeOpacity, IgnoreOpacity, ObserveOpacityTreeExt, OpacityChanged, TreeOpacity,
 };
+#[cfg(feature = "tween")]
+pub use weirdboi_tween_ext::TweenTreeOpacity;
 
 #[derive(Copy, Clone, Debug, Eq, PartialEq, Hash, SystemSet)]
 #[non_exhaustive]
@@ -45,5 +49,10 @@ impl Plugin for TreeOpacityPlugin {
 		{
 			app.register_type::<TreeOpacity>();
 		}
+		
+		#[cfg(feature = "tween")]
+		{
+			weirdboi_tween::RegisterTweenableExt::register_tweenable::<TweenTreeOpacity>(app);
+		}
 	}
 }

src/opacity_tree.rs

@@ -17,6 +17,19 @@ impl Default for TreeOpacity {
 		Self(1.0)
 	}
 }
+impl From<f32> for TreeOpacity {
+	fn from(value: f32) -> Self {
+		Self(value)
+	}
+}
+impl TreeOpacity {
+	pub fn opacity(&self) -> f32 {
+		self.0
+	}
+	pub fn set_opacity(&mut self, opacity: f32) {
+        self.0 = opacity;
+}
+    }
 
 pub trait HandlesTreeOpacity: Component<Mutability = Mutable> {
 	fn on_change_opacity(&mut self, opacity: f32);

src/weirdboi_tween_ext.rs

+use weirdboi_tween::Tweenable;
+use crate::TreeOpacity;
+
+pub struct TweenTreeOpacity;
+
+impl Tweenable for TweenTreeOpacity {
+    type Comp = TreeOpacity;
+    type Data = f32;
+
+    fn current_value(cmp: &Self::Comp) -> Self::Data {
+        cmp.opacity()
+    }
+
+    fn update_component(cmp: &mut Self::Comp, value: Self::Data) {
+        cmp.set_opacity(value);
+    }
+}
\ No newline at end of file