🎆 Bevy Hanabi

🎆 Hanabi — 适用于Bevy游戏引擎的GPU粒子系统。

概述

Hanabi粒子系统是适用于Bevy游戏引擎的现代GPU粒子系统。它专注于规模，以实时产生惊人的视觉效果（VFX），将大部分工作卸载到GPU上，CPU干预最小。设计灵感来源于其他行业领先游戏引擎中的现代粒子系统。

🚧 该项目正在积极开发中，目前功能和性能/可用性方面仍需完善。然而，对于中等规模的效果，它已可以在您的项目中使用。对设计和功能的反馈和贡献非常欢迎。

🎆 Hanabi大量使用计算着色器以高效地将工作卸载到GPU上。通过WebGPU支持在wasm目标（WebAssembly）上的计算着色器，仅从Bevy v0.11版本开始可用，且在🎆 Hanabi中尚未提供。有关进度的详细信息，请参阅#41。

使用方法

🎆 Bevy Hanabi插件与Bevy版本 >= 0.6 兼容；请参阅兼容的Bevy版本。

添加依赖

将 bevy_hanabi 依赖项添加到 Cargo.toml

[dependencies]
bevy_hanabi = "0.12"

有关支持的特性列表，请参阅下面的特性。

系统设置

将 HanabiPlugin 添加到您的应用程序

use bevy_hanabi::prelude::*;

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

创建效果资产

创建一个 EffectAsset，描述一个视觉效果

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 a new expression module
  let mut module = Module::default();

  // On spawn, randomly initialize the position of the particle
  // to be over the surface of a sphere of radius 2 units.
  let init_pos = SetPositionSphereModifier {
      center: module.lit(Vec3::ZERO),
      radius: module.lit(0.05),
      dimension: ShapeDimension::Surface,
  };

  // Also initialize a radial initial velocity to 6 units/sec
  // away from the (same) sphere center.
  let init_vel = SetVelocitySphereModifier {
      center: module.lit(Vec3::ZERO),
      speed: module.lit(6.),
  };

  // Initialize the total lifetime of the particle, that is
  // the time for which it's simulated and rendered. This modifier
  // is almost always required, otherwise the particles won't show.
  let lifetime = module.lit(10.); // literal value "10.0"
  let init_lifetime = SetAttributeModifier::new(
      Attribute::LIFETIME, lifetime);

  // Every frame, add a gravity-like acceleration downward
  let accel = module.lit(Vec3::new(0., -3., 0.));
  let update_accel = AccelModifier::new(accel);

  // Create the effect asset
  let effect = EffectAsset::new(
    // Maximum number of particles alive at a time
    vec![32768],
    // Spawn at a rate of 5 particles per second
    Spawner::rate(5.0.into()),
    // Move the expression module into the asset
    module
  )
  .with_name("MyEffect")
  .init(init_pos)
  .init(init_vel)
  .init(init_lifetime)
  .update(update_accel)
  // Render the particles with a color gradient over their
  // lifetime. This maps the gradient key 0 to the particle spawn
  // time, and the gradient key 1 to the particle death (10s).
  .render(ColorOverLifetimeModifier { gradient });

  // Insert into the asset system
  let effect_handle = effects.add(effect);
}

生成粒子效果

使用 ParticleEffect 从现有资产创建效果实例。最简单的方法是使用 ParticleEffectBundle 确保所有必需的组件一起生成。

commands
    .spawn(ParticleEffectBundle {
        effect: ParticleEffect::new(effect_handle),
        transform: Transform::from_translation(Vec3::Y),
        ..Default::default()
    });

示例

请参阅 examples/ 文件夹。

Linux用户注意：默认情况下，示例使用bevy/x11功能进行构建，以启用对X11显示服务器的支持。如果您想使用Wayland显示服务器，请添加bevy/wayland功能。

烟花

通过组合用于生成的SetPositionSphereModifier和用于减速粒子的LinearDragModifier来创建烟花效果。此示例使用具有Bloom功能的HDR相机。有关效果设计细节，请参阅示例文件。

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

传送门

通过组合用于粒子围绕圆圈进行切向旋转的SetVelocityTangentModifier和用于创建细长火花的OrientAlongVelocityModifier，产生一种“魔法传送门”效果。此示例使用具有Bloom功能的HDR相机。有关效果设计细节，请参阅示例文件。

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

表达式

演示使用表达式API构建完全在GPU上模拟和动画的视觉效果。动画是硬编码到由🎆 Hanabi根据效果作者设计的表达式生成的计算着色器中的。

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

渐变

通过移动其Transform组件来动画发射器，并使用ColorOverLifetimeModifier发射带有纹理的四边形粒子。

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

力场

此示例演示了力场修饰符ForceFieldModifier，它允许创建一些吸引和排斥源，影响粒子的运动。它还演示了使用AabbKillModifier来杀死退出“允许”空间（绿色框）或进入“禁止”空间（红色框）的粒子。

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

2D

此示例展示了如何使用🎆 Hanabi与2D相机一起使用。

白色正方形网格沿相机深度前后移动。2D效果本身保持在恒定位置。当正方形网格移动到效果后面时，粒子被渲染在其前面，反之亦然。

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

多摄像头

此示例演示了使用多个摄像头和渲染层来选择性地渲染效果。每个摄像头使用不同的图层组合，每个效果分配给不同的图层。

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

激活

此示例演示了从代码（CPU）手动激活和禁用Spawner。圆圈在水中上下跳动，仅在水中时生成气泡。气泡粒子通过KillAabbModifier被限制在水中，并通过微小的垂直加速度模拟一些伪浮力。

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

生成

此示例演示了三种生成模式

• 左侧：以固定速率（粒子/秒）连续发射。
• 中间：一次性的固定数量粒子爆发发射。
• 右侧：连续的粒子爆发，介于前两者之间。此效果还使用一个随时间改变所有粒子加速度方向的属性。

它还展示了将恒定加速度应用于所有粒子的方法。右侧生成器的加速度（重力）由一个自定义属性控制，该属性由Bevy系统（CPU端）缓慢旋转。

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

按命令生成

此示例演示了当发生事件时如何发射一串粒子。还使用一个属性来修改生成粒子的颜色。这使用户代码完全控制生成。

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

圆圈

本例演示了circle发射器类型，它沿圆形周长或圆盘表面发射粒子。例如，可以模拟物体与地面碰撞时周围的尘埃环。

此示例还使用FlipbookModifier通过精灵图纹理来动画化粒子。

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

可见性

本例演示了默认的SimulationCondition::WhenVisible（仅在可见时模拟效果）和SimulationCondition::Always（即使实体被隐藏也始终模拟效果）之间的差异。

• 顶部效果使用SimulationCondition::Always，即使在隐藏时也继续模拟，并向右移动。
• 底部效果使用SimulationCondition::WhenVisible，在隐藏时暂停模拟，一旦再次可见，就从这个最后一次可见的位置恢复运动。

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

随机

本例使用随机参数发射粒子。

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

生命周期

本例演示了具有不同生命周期的粒子效果。每个效果每3秒发射一次粒子，粒子的生命周期为

• 左侧：12秒，比发射率长，因此多个爆发累积。
• 中心：3秒，与发射率相同，因此粒子在新的粒子发射时死亡。
• 右侧：0.75秒，比发射率短，因此粒子在下一个爆发之前就死亡。

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

告示牌

本例演示了具有告示牌渲染修改器的粒子，使它们始终面向摄像机。它还演示了使用alpha截止值来过滤掉低于一定阈值的纹理样本，这个阈值在0和1之间来回变化。最后，示例使用属性来存储每个粒子的数据，如颜色或平面内旋转。

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

特性列表

此列表包含🎆 Hanabi提供的重大固定功能。除此之外，借助表达式API的力量，视觉效果作者可以通过分配单个粒子属性（位置、颜色等）来进一步自定义他们的效果。

• 生成
  • 恒定速率
  • 一次性爆发
  • 重复爆发
  • 发射器重置
  • 发射器激活/去激活
  • 随机化发射参数
• 初始化
  • 恒定位置
  • 形状上的位置
    • 立方体
    • 圆形
    • 球体
    • 圆锥体/截头圆锥体（3D）
    • 平面
    • 通用网格/点云 (?)
  • 随机位置偏移
  • 形状上的速度（带随机速度）
    • 圆形
    • 球体
    • 切线
  • 恒定/随机每个粒子的颜色
  • 恒定/随机每个粒子的尺寸
  • 恒定/随机每个粒子的年龄和生命周期
• 更新
  • 模拟条件
    • 始终，即使隐藏
    • 仅当可见时
  • 运动积分（欧拉）
  • 应用力和加速度
    • 恒定加速度（重力）
    • 径向加速度
    • 切线加速度
    • 力场
    • 线性阻力
  • 碰撞
    • 形状
      • 平面
      • 立方体
      • 球体
    • 深度缓冲区
  • 允许/拒绝销毁框
  • 生命周期
  • 生命周期内尺寸变化
  • 生命周期内颜色变化
• 渲染
  • 四边形
    • 纹理
  • 通用3D网格
  • 变形
    • 沿速度拉伸
    • 尾巴/条带
  • 摄像机支持
    • 渲染层
    • 仅2D摄像机（Camera2dBundle）
    • 3D摄像机（Camera3dBundle仅限）
    • 同时双2D/3D摄像机
    • 多个视图（分割屏幕）
    • HDR摄像机和光晕效果
  • 调整粒子大小和方向
    • 面向摄像机（Billboard）
    • 面向固定方向
    • 与速度方向对齐
    • 屏幕空间大小（投影独立）
• 调试
  • GPU调试标签/组
  • 调试可视化
    • 位置大小
    • 速度大小
    • 年龄/寿命

功能

🎆 Bevy Hanabi支持以下Cargo功能

为了优化，可以使用单种类型摄像机的用户通过跳过他们的Cargo.toml中的默认功能来禁用其他类型。例如，要仅使用3D模式

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

兼容的Bevy版本

main分支与最新的Bevy版本兼容。

bevy_hanabi版本兼容性

许可证

🎆 Hanabi可以在以下任一许可证下双许可

• MIT许可证（LICENSE-MIT或http://opensource.org/licenses/MIT）
• Apache许可证，版本2.0（LICENSE-APACHE2或http://www.apache.org/licenses/LICENSE-2.0）

任选其一。

SPDX-许可证-标识符: MIT 或Apache-2.0