Crate bevy_firefly 

Firefly is an open-source 2d lighting crate made for the Bevy game engine.

Feel free to create an issue if you want to request a specific feature or report a bug.

Example

Here is a basic example of implementing Firefly into a Bevy game.

use bevy::prelude::*;
use bevy_firefly::prelude::*;

fn main() {
    App:new()
        // add FireflyPlugin to your app
        .add_plugins((DefaultPlugins, FireflyPlugin))
        .add_systems(Startup, setup)
        .run();
}

fn setup(mut commands: Commands) {
    commands.spawn((
        Camera2d,
        // make sure to also have the FireflyConfig component on your camera
        FireflyConfig::default()
    ));
     
    // spawn a simple red light
    commands.spawn((
        PointLight2d {
            color: Color::srgb(1.0, 0.0, 0.0),
            range: 100.0,
            ..default()
        },
        Transform::default()
    ));
     
    // spawn a circle occluder
    commands.spawn((
        Occluder2d::circle(10.0),
        Transform::from_translation(vec3(0.0, 50.0, 0.0)),
    ));
}

Occluders

Occluders are shapes that block light and cast shadows.

Current supported shapes include:

• Polylines.
• Polygons (concave and convex).
• Round shapes such as circles, capsules, round rectangles.

Occluders have an opacity, ranging from transprent to fully opaque, and can cast colored shadows.

Occluders can be moved and rotated via the Transform component.

Lights

You can create lights by spawning entities with the PointLight2d component.

Lights have adjustable range, falloff mode and a variety of other features.

Features

Here are some of the main features currently implemented :

• Soft Shadows: FireflyConfig has a Softness field that can be adjusted to disable / enable soft shadows, as well as give it a value (0 to 1) to set how soft the shadows should be.

• Occlusion Z-Sorting: You can enable z-sorting on FireflyConfig to have shadows only render over sprites with a lower z position than the occluder that cast them. This is extremely useful for certain 2d games, such as top-down games.

• Normal maps: You can enable normal maps by changing the normal mode field. You can then add the NormalMap component to sprites. Normal maps need to have the same exact layout as their entity’s sprite image. If normal mode is set to top down, you can use LightHeight and SpriteHeight to emulate 3d dimensions for the normal maps.

• Light Banding: You can enable light bands on FireflyConfig to reduce the lightmap to a certain number of ‘bands’, creating a stylized look.

Upcoming Features

Here are some of the features that are currently planned:

• Multiple lightmaps.
• Sprite-based shadows.
• Light textures.

Modules

app

Module containing core plugins and logic to be added to a bevy app.

buffers

This module contains structs and functions that create and manage render-world entities and GPU buffers.

change

Module containing logic for change detection.

data

extract

This module extracts data from the Main World to the Render World.

lights

nodes

Module containg Render Graph Nodes used by Firefly.

occluders

Module containing structs and functions relevant to Occluders.

phases

Module containing custom render phases.

pipelines

Module containing the custom Render Pipelines used by Firefly.

prelude

prepare

Module that prepares BindGroups for GPU use.

sprites

Module containing structs and functions relevant to sprites and normal maps.

visibility

Module with logic for determining whether entities (lights, occluders) are visibile or not. Visibility is based on whether they can affect what is rendered on-screen or not, for instance occluders can be off-screen and still visible because they can block light that would be otherwise visible on-screen.

Structs

ApplyLightmapLabel

Render graph label for when the lightmap is applied over the view texture and fed to the camera.

CreateLightmapLabel

Render graph label for creating the lightmap.

LightMapTexture

Camera component that stores the texture of the lightmap.

NormalMapTexture

Camera component that stores the normal map texture.

SpriteLabel

Render graph label for when the normal maps and sprite stencils are created.

SpriteStencilTexture

Camera component that stores the sprite stencil.