🎆 Bevy Hanabi

License: MIT or Apache 2.0 Doc Crate Build Status Coverage Status Bevy tracking

🎆 Hanabi — a GPU particle system for the Bevy game engine.

Overview

The Hanabi particle system is a modern GPU-based particle system for the Bevy game engine. It focuses on scale to produce stunning visual effects (VFX) in real time, offloading most of the work to the GPU, with minimal CPU intervention. The design is inspired by modern particle systems found in other industry-leading game engines.

🚧 This project is under heavy development, and is currently lacking both features and performance / usability polish. However, for moderate-size effects, it can already be used in your project. Feedback and contributions on both design and features are very much welcome.

Usage

The 🎆 Bevy Hanabi plugin is compatible with Bevy versions >= 0.6; see Compatible Bevy versions.

Add the dependency

Add the bevy_hanabi dependency to Cargo.toml:

toml [dependencies] bevy_hanabi = "0.4"

See also Features below for the list of supported features.

System setup

Add the HanabiPlugin to your app:

```rust use bevy_hanabi::prelude::*;

App::default() .addplugins(DefaultPlugins) .addplugin(HanabiPlugin) .run(); ```

Create a particle effect

Create an EffectAsset describing a visual effect:

```rust fn setup(mut effects: ResMut>) { // Define a color gradient let mut gradient = Gradient::new(); gradient.addkey(0.0, Vec4::new(1., 0., 0., 1.)); // Red gradient.addkey(1.0, Vec4::ZERO); // Transparent black

// Create the effect asset
let effect = effects.add(EffectAsset {
        name: "MyEffect".to_string(),
        // Maximum number of particles alive at a time
        capacity: 32768,
        // Spawn at a rate of 5 particles per second
        spawner: Spawner::rate(5.0.into()),
        ..Default::default()
    }
    // On spawn, randomly initialize the position and velocity
    // of the particle over a sphere of radius 2 units, with a
    // radial initial velocity of 6 units/sec away from the
    // sphere center.
    .init(PositionSphereModifier {
        center: Vec3::ZERO,
        radius: 2.,
        dimension: ShapeDimension::Surface,
        speed: 6.0.into(),
    })
    // Every frame, add a gravity-like acceleration downward
    .update(AccelModifier {
        accel: Vec3::new(0., -3., 0.),
    })
    // Render the particles with a color gradient over their
    // lifetime.
    .render(ColorOverLifetimeModifier { gradient })
);

} ```

Add a particle effect

Use a ParticleEffectBundle to create an effect instance from an existing asset:

rust commands .spawn_bundle(ParticleEffectBundle { effect: ParticleEffect::new(effect), transform: Transform::from_translation(Vec3::new(0., 1., 0.)), ..Default::default() });

Examples

See the examples/ folder.

Gradient

Animate an emitter by moving its Transform component, and emit textured quad particles with a ColorOverLifetimeModifier.

shell cargo run --example gradient --features="bevy/bevy_winit bevy/bevy_pbr bevy/png 3d"

gradient

Force Field

This example demonstrates the force field modifier ForceFieldModifier, which allows creating some attraction and repulsion sources affecting the motion of the particles.

shell cargo run --example force_field --features="bevy/bevy_winit bevy/bevy_pbr 3d"

force_field

2D

This example shows how to use 🎆 Hanabi with a 2D camera.

shell cargo run --example 2d --features="bevy/bevy_winit bevy/bevy_sprite 2d"

Activate

This example demonstrates manual activation and deactivation of a spawner, from code (CPU). The circle bobs up and down in the water, spawning square bubbles when in the water only.

shell cargo run --example activate --features="bevy/bevy_winit bevy/bevy_pbr 3d"

activate

Spawn

This example demonstrates three spawn modes:

It also shows the applying of constant force (downward gravity-like, or upward smoke-style).

shell cargo run --example spawn --features="bevy/bevy_winit bevy/bevy_pbr 3d"

spawn

Spawn on Command

This example demonstrates how to emit a burst of particles when an event occurs. This gives total control of the spawning to the user code.

shell cargo run --example spawn_on_command --features="bevy/bevy_winit bevy/bevy_pbr 3d"

spawn

Circle

This example demonstrates the circle spawner type, which emits particles along a circle perimeter or a disk surface. This allows for example simulating a dust ring around an object colliding with the ground.

shell cargo run --example circle --features="bevy/bevy_winit bevy/bevy_pbr bevy/png 3d"

circle

Random

This example spawns particles with randomized parameters.

shell cargo run --example random --features="bevy/bevy_winit bevy/bevy_pbr 3d"

spawn

Lifetime

This example demonstrates particle effects with different lifetimes.

shell cargo run --example lifetime --features="bevy/bevy_winit bevy/bevy_pbr 3d" lifetime

Billboard

This example demonstrates particles with the billboard render modifier, making them always face the camera.

shell cargo run --example billboard --features="bevy/bevy_winit bevy/bevy_pbr bevy/png 3d" The image on the left has the BillboardModifier enabled. billboard

Feature List

Features

🎆 Bevy Hanabi supports the following cargo features:

| Feature | Default | Description | |---|:-:|---| | 2d | ✔ | Enable rendering through 2D cameras (Camera2dBundle) | | 3d | ✔ | Enable rendering through 3D cameras (Camera3dBundle) |

For optimization purpose, users of a single type of camera can disable the other type by skipping default features in their Cargo.toml. For example to use only the 3D mode:

toml bevy_hanabi = { version = "0.4", default-features = false, features = [ "3d" ] }

Compatible Bevy versions

The main branch is compatible with the latest Bevy release.

Compatibility of bevy_hanabi versions:

| bevy_hanabi | bevy | | :-- | :-- | | 0.3-0.4 | 0.8 | | 0.2 | 0.7 | | 0.1 | 0.6 |