Lights
Light a 3D scene with point, spot, directional, area and ambient lights, using real-world units, and how many lights each platform supports.
On this page
Lights are components. Spawn one with a Transform to place and aim it. The renderer uses real-world units (lumens for lamps, lux for the sun), so a light's brightness only looks right together with the camera's exposure.
Light types#
| Component | What it is | Brightness |
|---|---|---|
PointLight | A bulb: light in every direction from a point. | intensity in lumens. Default 1,000,000 (a very large cinema light). |
SpotLight | A cone of light, aimed along the entity's −Z axis. inner_angle and outer_angle (radians) set the cone and its soft edge. | intensity in lumens. |
DirectionalLight | The sun or moon: parallel rays along the entity's −Z axis, everywhere at once. Only its rotation matters. | illuminance in lux. |
RectLight | A rectangular area light, such as a window or a screen. Needs the area_light_luts cargo feature, which NEO's builds don't turn on, and casts no shadows. | intensity. |
GlobalAmbientLight (resource) | A flat amount of light everywhere, standing in for bounced light. | brightness in cd/m². Default 80. |
AmbientLight (on a camera) | Overrides GlobalAmbientLight for that camera. | brightness. |
use std::f32::consts::PI;
fn setup(mut commands: Commands) {
// the sun
commands.spawn((
DirectionalLight {
illuminance: light_consts::lux::OVERCAST_DAY,
shadow_maps_enabled: true,
..default()
},
Transform::from_rotation(Quat::from_rotation_x(-PI / 4.0)),
));
// a red lamp
commands.spawn((
PointLight {
intensity: 100_000.0,
color: Color::srgb(1.0, 0.2, 0.2),
range: 10.0,
shadow_maps_enabled: true,
..default()
},
Transform::from_xyz(1.0, 2.0, 0.0),
));
// a spotlight looking down at the origin
commands.spawn((
SpotLight {
intensity: 100_000.0,
inner_angle: 0.6,
outer_angle: 0.8,
..default()
},
Transform::from_xyz(-1.0, 4.0, 0.0).looking_at(Vec3::ZERO, Vec3::Z),
));
// a little ambient light
commands.insert_resource(GlobalAmbientLight {
brightness: 200.0,
..default()
});
}Example: cargo run --example lighting; spotlight for spot lights.
Common fields#
| Field | Lights | What it does |
|---|---|---|
color | all | The light's colour. |
range | point, spot | Beyond this distance the light has no effect. Smaller ranges are cheaper. Default 20.0. |
radius | point, spot | The size of the bulb. Bigger values give softer, broader highlights. Example: spherical_area_lights. |
shadow_maps_enabled | point, spot, directional | Casts shadows. Off by default. See Shadows. |
contact_shadows_enabled | point, spot, directional | Adds screen-space contact shadows; see Shadows. |
affects_lightmapped_mesh_diffuse | point, spot, directional | Turn off if this light is already baked into a lightmap. |
Light units#
The constants in light_consts (in the prelude) give typical values:
light_consts::lux | Lux | Scene |
|---|---|---|
MOONLESS_NIGHT | 0.0001 | Starlight. |
FULL_MOON_NIGHT | 0.05 | Moonlight. |
LIVING_ROOM | 50 | Indoor lamps. |
OFFICE | 320 | Office lighting. |
OVERCAST_DAY | 1,000 | A grey day. |
AMBIENT_DAYLIGHT | 10,000 | Daylight, not direct sun. |
FULL_DAYLIGHT | 20,000 | Bright daylight. |
DIRECT_SUNLIGHT | 100,000 | Direct sun. |
For point and spot lights, light_consts::lumens has LUMENS_PER_LED_WATTS (90), LUMENS_PER_INCANDESCENT_WATTS (13.8) and LUMENS_PER_HALOGEN_WATTS (19.8): a 60 W incandescent bulb is about 800 lumens.
Glowing objects#
A light doesn't make a visible bulb. Give the lamp a small mesh as a child with an emissive material, and add bloom to the camera if you want it to glow:
commands.spawn((
PointLight { intensity: 100_000.0, ..default() },
Transform::from_xyz(0.0, 3.0, 0.0),
children![(
Mesh3d(meshes.add(Sphere::new(0.1))),
MeshMaterial3d(materials.add(StandardMaterial {
emissive: LinearRgba::rgb(4.0, 4.0, 4.0),
..default()
})),
)],
));How many lights#
Point lights, spot lights, light probes and decals are sorted into clusters on the screen, so each pixel only evaluates the lights near it. Many lights are fine on the desktop, as long as their ranges are kept small.
| Desktop | Web (WebGL 2) | |
|---|---|---|
| Directional lights per view | 10 | 1 |
| Shadow cascades per directional light | 4 | 1 |
| Point and spot lights and light probes per view | Limited by GPU memory | 204 in total |
Light textures and volumetric lights#
- Light textures (
PointLightTexture,SpotLightTexture,DirectionalLightTexture) shape a light with an image, like a projector or a cookie. They need thepbr_light_texturescargo feature, which NEO's builds don't turn on. - Volumetric light: add
VolumetricLight(inneo::light) to a light to make it shine through volumetric fog. - Sun disk:
SunDisk(inneo::light) on a directional light draws the sun in the atmosphere.
Debugging lights#
ShowLightGizmo on a light, or LightGizmoConfigGroup for all lights, draws each light's position, range and direction with gizmos.