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

# There is no current crates release
weirdboi_opacity_tree = { git = "https://weirdboi.dev/libraries/weirdboi-opacity-tree.git" }

//! Entry point for your game, main.rs
use weirdboi_opacity_tree::TreeOpacityPlugin;

fn main() {
   // Create your app, then..
   
   app.add_plugins(TreeOpacityPlugin);
}

//! 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.

#[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