Skip to content

sparten11740/bevy_health_bar3d

Repository files navigation

Checks Release

bevy_health_bar3d

Health Bar plugin for Bevy 3D. Despite its name, this plugin is universally applicable. It can be used to render a bar for any value that can be represented as percentage. Can be freely sized, supports horizontal or vertical orientation, custom fore- and background colors, and an optional border with configurable thickness and color. Works with split-screens or layered cameras out of the box.

Bevy Compatibility

Bevy Version Crate Version
0.14 >= 3.3.0
0.13 3.2.0
0.12 2.0.0
0.11 1.2.0
0.10 1.1.0
0.9 1.0.0

Usage

Implement the Percentage trait for the component you want to track and pass the type of your component to the plugin on instantiation:

use bevy_health_bar3d::prelude::{HealthBarPlugin, Percentage};

#[derive(Component, Reflect)]
struct Health {
    max: f32,
    current: f32,
}

impl Percentage for Health {
    fn value(&self) -> f32 {
        self.current / self.max
    }
}

fn main() {
    App::new()
        // add multiple times to track further component types
        .add_plugins((HealthBarPlugin::<Health>::default(), HealthBarPlugin::<Mana>::default()))
        // set a different color for the Mana bar
        .insert_resource(ColorScheme::<Mana>::new().foreground_color(ForegroundColor::Static(Color::BLUE)))
        .run();
}

Spawn a mesh, the component to be tracked, and a BarSettings component to configure the look & feel of your bar.

fn setup(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<StandardMaterial>>,
) {
    commands.spawn((
        PbrBundle {
            mesh: meshes.add(Sphere { radius }),
            // ...
        },
        Health {
            max: 10.,
            current: 2.,
        },
        BarSettings::<Health> {
            width: 5.,
            offset: 2.,
            orientation: BarOrientation::Vertical, // default is horizontal
            ..default()
        },
    ));
}

Note the generic parameter of BarBundle. It is used to associate the configuration with the component it is tracking and necessary to support multiple bars per entity.

That's it! Updates to the values of your component will be automatically propagated through to the bar.

Examples

Examples can be found here. To run an example for web, first install cargo-make (cargo install cargo-make) and then call cargo make web <name-of-the-example, such as cargo make web dinosaurs