bevy_firefly 0.17.1

2d lighting crate for the Bevy game engine
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158

//! **Firefly** is an open-source **2d lighting** crate made for the [Bevy](https://bevy.org/) game engine.
//!
//! Feel free to [create an issue](https://github.com/PVDoriginal/firefly/issues) 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](crate::occluders::Occluder2d) are shapes that block light and cast shadows.
//!
//! Current supported shapes include:
//! - [Polylines](crate::occluders::Occluder2d::polyline).
//! - [Polygons](crate::occluders::Occluder2d::polygon) (concave and convex).
//! - Round shapes such as [circles](crate::occluders::Occluder2d::circle), [capsules](crate::occluders::Occluder2d::capsule), [round rectangles](crate::occluders::Occluder2d::round_rectangle).
//!
//! Occluders have an [opacity](crate::occluders::Occluder2d::opacity), ranging from transprent to fully opaque, and can cast [colored shadows](crate::occluders::Occluder2d::opacity).   
//!
//! Occluders can be moved and rotated via the [Transform] component.   
//!
//! # Lights
//!
//! You can create lights by spawning entities with the [PointLight2d](crate::prelude::PointLight2d) component.
//!
//! Lights have adjustable [range](crate::prelude::PointLight2d::range), [falloff mode](crate::prelude::PointLight2d::falloff) and a variety of other features.
//!
//! # Features
//!
//! Here are some of the main features currently implemented :
//!
//! - **Soft Shadows**:
//! [FireflyConfig](crate::prelude::FireflyConfig) has a [Softness](crate::prelude::FireflyConfig::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](crate::prelude::FireflyConfig::z_sorting) on [FireflyConfig](crate::prelude::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](crate::prelude::FireflyConfig::normal_mode) field. You can then
//! add the [NormalMap](crate::prelude::NormalMap) component to sprites. Normal maps need to have the same exact layout as their entity's sprite image.
//! If [normal mode](crate::prelude::FireflyConfig::normal_mode) is set to [top down](crate::prelude::NormalMode::TopDown),
//! you can use [LightHeight](crate::prelude::LightHeight) and [SpriteHeight](crate::prelude::SpriteHeight) to emulate 3d dimensions for the normal maps.  
//!
//! - **Light Banding**: You can enable [light bands](crate::prelude::FireflyConfig::light_bands) on [FireflyConfig](crate::prelude::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.

use bevy::{
    asset::uuid_handle,
    prelude::*,
    render::{render_graph::RenderLabel, texture::CachedTexture},
};

pub mod app;
pub mod buffers;
pub mod change;
pub mod data;
pub mod lights;
pub mod occluders;
pub mod visibility;

pub mod extract;
pub mod nodes;
pub mod phases;
pub mod pipelines;
pub mod prepare;
pub mod sprites;

mod utils;

pub(crate) use phases::*;

pub mod prelude {
    pub use crate::app::{FireflyGizmosPlugin, FireflyPlugin};
    pub use crate::data::{FireflyConfig, NormalMode};
    pub use crate::lights::{Falloff, LightHeight, PointLight2d};
    pub use crate::occluders::Occluder2d;
    pub use crate::sprites::{NormalMap, SpriteHeight};
    pub use crate::{ApplyLightmapLabel, CreateLightmapLabel};
}

/// Camera component that stores the texture of the lightmap.
#[derive(Component)]
pub struct LightMapTexture(pub CachedTexture);

/// Camera component that stores the sprite stencil.
#[derive(Component)]
pub struct SpriteStencilTexture(pub CachedTexture);

/// Camera component that stores the normal map texture.  
#[derive(Component)]
pub struct NormalMapTexture(pub CachedTexture);

/// Render graph label for creating the lightmap.
///
/// Useful if you want to add your own render passes before / after it.   
#[derive(Debug, Hash, PartialEq, Eq, Clone, RenderLabel)]
pub struct CreateLightmapLabel;

/// Render graph label for when the lightmap is applied over the view texture and fed to the camera.
///
/// Useful if you want to add your own render passes before / after it.
#[derive(Debug, Hash, PartialEq, Eq, Clone, RenderLabel)]
pub struct ApplyLightmapLabel;

/// Render graph label for when the normal maps and sprite stencils are created.
///
/// Useful if you want to add your own render passes before / after it.
#[derive(RenderLabel, Debug, Clone, Hash, PartialEq, Eq)]
pub struct SpriteLabel;

const CREATE_LIGHTMAP_SHADER: Handle<Shader> = uuid_handle!("6e9647ff-b9f8-41ce-8d83-9bd91ae31898");
const APPLY_LIGHTMAP_SHADER: Handle<Shader> = uuid_handle!("72c4f582-83b6-47b6-a200-b9f0e408df72");
const TYPES_SHADER: Handle<Shader> = uuid_handle!("dac0fb7e-a64f-4923-8e31-6912f3fc8551");
const UTILS_SHADER: Handle<Shader> = uuid_handle!("1471f256-f404-4388-bb2f-ca6b8047ef7e");
const SPRITE_SHADER: Handle<Shader> = uuid_handle!("00f40f01-5069-4f1c-a69c-a6bd5ca3983e");