Firefly is an open-source, 2d lighting crate for the Bevy game engine.
HDR support is planned as being part of the next big update that I'm working on, 0.18.1. However, mainly due to the Bevy Jam having started and the full update still being far from done, I've released a 0.18.1-alpha version
which just adds HDR support and a couple of other things. Check out the release notes for more details. I'm adding this here because cargo seems to still default to
0.18.0 as the newest version, so you'll need to manually change it to have access to HDR. It is a pretty huge visual improvement with almost no performance cost!
When I was working on a Bevy project, I found myself needing features that other 2d lighting crates did not yet provide. I needed an accessible 2d lighting solution that offers the same capabilities as engines such as Unity and Godot. So, as part of my bachelor thesis, I began work on Firely.
My main objectives while making and maintaining Firefly are:
- Minimal Setup. this crate should be extremely easy to plug into any existing bevy app, and the API should feel minimal and intuitive.
- Consistent Maintenance. I will keep this crate up-to-date with all new bevy versions and changes, until it is inevitably deprectated by another solution or upstreamed into Bevy itself.
- Community Feedback. I'm eagerly accepting any feature requests and bug reports. I do have my own backlog but any features requested by users will be prioritized.
- Power. While Bevy has never had a proper 2d lighting solution similar to other game engines, I am dedicated to changing that. Firefly should offer users all the features that those engines do and more!
Here are some videos showcasing various features of Firefly. Credit for the character and assets goes to Kimberly and her upcoming game, Starlight!
Soft shadows and z-sorting.
2025-11-19_03-44-04.mp4
Same scene but with light banding and hard shadows.
Screencast.From.2025-11-24.00-50-49.mp4
Video of the crates example, showcasing normal maps and z-sorting.
crates_example.mp4
Video of the stress example.
2026-01-01.03-47-55.mp4
To use this crate, simply run cargo add bevy_firefly or add Firefly to your Cargo.toml file.
You can see all the Firefly versions here.
Here is a basic example of integrating Firefly into a bevy app:
use bevy::prelude::*;
use bevy_firefly::prelude::*;
fn main() {
App:new()
.add_plugins((DefaultPlugins, FireflyPlugin))
.add_systems(Startup, setup)
.run();
}
fn setup(mut commands: Commands) {
commands.spawn((
Camera2d,
FireflyConfig::default()
));
commands.spawn((
PointLight2d {
color: Color::srgb(1.0, 0.0, 0.0),
range: 100.0,
..default()
},
));
commands.spawn((
Occluder2d::circle(10.0),
Transform::from_translation(vec3(0.0, 50.0, 0.0)),
));
}Check out the examples and the crate documentation to learn more about using it.
Some of the existing features are:
- Point lights
- Round and polygonal occluders
- Soft shadows
- Occlusion z-sorting
- Normal maps
- Transparent & colored occluders
- Light banding
Some of the currently planned features are:
- Occluders casting sprite-based shadows
- Mulitple lightmaps
- Dithering
- Light textures
Check out my milestone goals to see what features are currently planned based on the Bevy release cycle.
Feel free to open an issue if you want to request any specific features or report any bugs!
Also you can ask any questions over on discord! You can also follow the thread to be kept up-to-date with new features.
| bevy | bevy_firefly |
|---|---|
| 0.18 | 0.18 |
| 0.17 | 0.17 |
| 0.16 | 0.16 |
Each minor Firefly version is compatible with that specific Bevy version (e.g. Firefly 0.18.x should work with Bevy 0.18.0, 0.18.1, and so on).
The Firefly patch version is unrelated to Bevy's (e.g. Firefly 0.18.1 is not related to Bevy 0.18.1 and still works with any Bevy 0.18 version).
Unlike Bevy, Firefly can have breaking API changes in every release.
Some notable limitations that Firefly currently has:
- Currently the
FireflyConfigcomponent can only be added to a single camera at one time. Having multiple cameras in your app is fine, but only one of them can render lights for now. - WebGPU only. I've chosen to drop WebGL2 support in favor of WebGPU and the many possibilities it offers, which means Firefly might not run on specific browsers / devices yet (although WebGPU support is rapidly growing). I am willing to add and maintain a WebGL2 compatibility mode if there's a significant need for it though.
- Firefly was mostly designed to work with Sprites, which means there is limited compatibility with 2d Meshes. While lights can be cast over them, they don't yet support normal maps or occlusion z-sorting. This will be changed very soon as Bevy's Sprite backend is being migrated to the mesh one.
- Occluder scaling isn't supported yet.
These aren't hard limitations though, and can be overcome with some effort. I just didn't have the time yet. If you want me to prioritize fixing any of them, feel free to open an issue.
There are a few other 2d lighting solutions for Bevy that I'm aware of: