Skip to content
Snippets Groups Projects
README.md 3.12 KiB
Newer Older
Louis's avatar
Louis committed
# 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>();
}
Louis's avatar
Louis committed
```

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