本页目录

Bevy Hanabi:Bevy 引擎 GPU 粒子系统插件

bevy_hanabi · djeedai/bevy_hanabi

Hanabi 是面向 Bevy 游戏引擎的 GPU 粒子系统插件,用 Rust 编写。项目自述为「现代 GPU 粒子系统」,重点放在把大部分粒子计算交给 GPU,以支持实时生成大规模视觉特效(VFX)。仓库主题标签包含 bevy、gamedev、gpu-particles、particl...

其他 Three.js PixiJS JavaScript 动画系统 UI 系统 渲染技术 中级
★ Stars 1,453 Forks 136 License Apache-2.0 更新 2026-11-15

国内开发环境适配

Windows
未知
Linux
官方声明支持
macOS
未知
引擎 / 框架:Three.js 暂无中文教程标记 未标记站长实测
依赖 crates.io,国内建议配置 cargo 镜像源以加速拉取 bevy 与 bevy_hanabi;构建示例时 Bevy 首次编译耗时较长,需预留磁盘与内存。README 只给出 X11/Wayland 等 Linux 显示服务器相关的 feature 说明,其他国内网络限制待核验。

中文项目介绍

Hanabi(日语「花火」)是面向 Bevy 游戏引擎 的 GPU 粒子系统插件,使用 Rust 编写。它的定位是「现代 GPU 粒子系统」:把绝大部分粒子模拟工作下放到 GPU,CPU 只做尽可能少的干预,从而在实时场景里生成大规模的视觉特效(VFX)。README 说明其设计参考了业界主流引擎中的现代粒子系统实现思路。

作者在文档中明确标注:项目仍处于高强度开发阶段,功能覆盖面以及性能、易用性方面都还在打磨;不过对于中等规模的粒子特效,已经可以放进实际项目使用,并且欢迎社区在设计层面与功能层面提出反馈与贡献。

核心功能

Spawn(生成)

固定速率、一次性爆发、重复爆发、生成器重置、生成器启用/停用、随机化生成参数。

Initialize(初始化)

固定位置、在形状上分布位置(圆、球、圆锥/截锥体已支持;立方体、平面、通用网格/点云未支持)、随机位置偏移、按形状的速度(圆、球、切向,含随机速率)、每粒子颜色/大小/年龄与寿命的常量或随机取值。

Update(更新)

模拟条件(始终模拟或仅可见时模拟)、欧拉运动积分、力与加速度(常量重力、径向加速度、切向加速度、力场、线性阻力)、允许/禁止消失盒(despawn box)、生命周期、随寿命改变大小与颜色;碰撞与形状碰撞、深度缓冲碰撞尚未实现。

Render(渲染)

四边形(支持贴图)、通用 3D 网格、形变(沿速度拉伸、拖尾/丝带)、相机支持(渲染层、仅 2D 相机、仅 3D 相机、2D/3D 双相机同时、多视口分屏、HDR 与泛光)、粒子尺寸与朝向(面向相机 Billboard、固定方向、沿速度定向、屏幕空间尺寸)。

Debug(调试)

GPU 调试标签/分组已支持;位置、速度、年龄等调试可视化尚未提供。

Cargo features 与相机支持

插件提供两个默认开启的 cargo feature:2d(通过 Camera2d 渲染)与 3d(通过 Camera3d 渲染)。若项目只使用一种相机类型,可按 README 建议关闭默认 feature 以削减开销,例如仅用 3D:bevy_hanabi = { version = "0.20", default-features = false, features = ["3d"] }。

技术架构分析

技术要点

  • 计算着色器驱动:Hanabi 大量使用 compute shader 把粒子计算卸载到 GPU,以获得更好的并行性能。
  • WebAssembly 支持:自 v0.13(对应 Bevy 0.14)起支持 wasm 目标上的 compute shader,但仅限 WebGPU 后端,细节见仓库 docs/wasm.md。
  • 表达式 API(Expressions API):除了固定的内置修饰器外,特效作者可以通过表达式为单个粒子属性(位置、颜色等)做更细粒度的自定义。
  • 资源化组织:特效以 EffectAsset 资源形式存入 Bevy 的 Assets 系统,运行时用 ParticleEffect 组件实例化,符合 Bevy 的 ECS 使用习惯。

补充说明

安装与基本用法

README 给出的接入流程分为三步。

  1. 添加依赖:在 Cargo.toml 中加入 bevy_hanabi = "0.20"。
  2. 注册插件:在 App 中与 DefaultPlugins 一起添加 HanabiPlugin,并引入 bevy_hanabi::prelude::*。
  3. 创建与生成特效:在系统里通过 ResMut<Assets<EffectAsset>> 构造 EffectAsset,描述粒子数量上限、生成速率(SpawnerSettings)以及一组修饰器,例如:
    • 初始化:SetPositionSphereModifier(在球面上随机初始化位置)、SetVelocitySphereModifier(球心向外的初速度)、SetAttributeModifier 设置 Attribute::LIFETIME;
    • 每帧更新:AccelModifier 施加类似重力的加速度;
    • 渲染:ColorOverLifetimeModifier 配合 Gradient,让颜色随粒子生命周期从红渐变到透明。

随后用 commands.spawn((ParticleEffect::new(effect_handle), Transform::...)) 即可在场景中生成该特效实例。README 特别提醒:生命周期的初始化修饰器几乎总是必需的,否则粒子不会被显示。

示例与调试工具

仓库的 examples/ 目录提供了一组示例,并且全部通过同一个可执行程序运行:

  • cargo run --example demo 打开交互式菜单选择演示;
  • cargo run --example demo -- --demo firework 直接打开指定演示(如烟花);
  • WebAssembly 平台可用 build_examples_wasm.sh(或 .bat)构建后托管 examples/wasm/,在浏览器中同样通过菜单选择演示;
  • examples/effects/ 下的源码生成特效文件可用 --write-effects 重新生成,用 --check-effects 在不修改文件的前提下做校验,这也演示了特效的序列化与反序列化流程。

Linux 用户注意:示例默认启用 bevy/x11 feature 以支持 X11 显示服务器;若想改用 Wayland,需要额外添加 bevy/wayland feature。

与 Bevy 的版本对应

仓库 main 分支跟随最新 Bevy 发行版,README 标注当前跟踪 Bevy v0.20。插件自述与 Bevy >= 0.6 兼容,并在文档中给出对照表(节选):bevy_hanabi 0.17→bevy 0.17、0.16→0.16、0.14–0.15→0.15、0.12–0.13→0.14、0.10–0.11→0.13、0.8–0.9→0.12、0.7→0.11、0.6→0.10、0.5→0.9、0.3–0.4→0.8、0.2→0.7、0.1→0.6。项目也提供 crates.io 包与 docs.rs 文档,选型前建议核对版本匹配关系。

许可

Hanabi 采用 MIT 或 Apache 2.0 双许可,使用者可按需选择其一,SPDX 标识为 MIT OR Apache-2.0。

开源许可证与版权说明

许可证标识:Apache-2.0。源码、资源与依赖许可可能不同,请以官方仓库为准。本站仅做索引,不托管源码。

相似项目