🎆 Bevy Hanabi

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 only compatible with Bevy v0.6.

System setup

Add the HanabiPlugin to your app:

use bevy_hanabi::*;

App::default()
    .add_plugins(DefaultPlugins)
    .add_plugin(HanabiPlugin)
    .run();

Create a particle effect

Create an EffectAsset describing a visual effect:

fn setup(mut effects: ResMut<Assets<EffectAsset>>) {
    // Define a color gradient from red to transparent black
    let mut gradient = Gradient::new();
    gradient.add_key(0.0, Vec4::new(1., 0., 0., 1.));
    gradient.add_key(1.0, Vec4::splat(0.)

    // 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:

commands
    .spawn()
    .insert(Name::new("MyEffectInstance"))
    .insert_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.

cargo run --example gradient --features="bevy/bevy_winit bevy/png"

Spawn

This example demonstrates three spawn modes:

• Left: Continuous emission with a fixed rate (particles/second).
• Center: One-shot burst emission of a fixed count of particles.
• Right: Continuous bursts of particles, an hybrid between the previous two.

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

cargo run --example spawn --features="bevy/bevy_winit"

Feature List

• Spawn
  • Constant rate
  • One-time burst
  • Repeated burst
  • Spawner resetting
  • Spawner activation/deactivation
  • Randomized spawning parameters
• Initialize
  • Constant position
  • Position over shape
    • cube
    • circle
    • sphere
    • cone
    • plane
    • generic mesh / point cloud (?)
  • Random position offset
  • Constant velocity
  • Random velocity
  • Constant color
  • Random color
• Update
  • Motion integration
  • Apply forces
    • Constant (gravity)
    • Force field
  • Collision
    • Shape
      • plane
      • cube
      • sphere
    • Depth buffer
  • Lifetime
  • Size change over lifetime
  • Color change over lifetime
  • Face camera
  • Face constant direction
• Render
  • Quad (sprite)
    • Textured
  • Generic 3D mesh
  • Deformation
    • Velocity (trail)
• Debug
  • GPU debug labels / groups
  • Debug visualization
    • Position magnitude
    • Velocity magnitude
    • Age / lifetime

Compatible Bevy versions

The main branch is compatible with the latest Bevy release.

Compatibility of bevy_hanabi versions:

bevy_hanabi	bevy
0.1	0.6