NEOLearn

Lights

Light a 3D scene with point, spot, directional, area and ambient lights, using real-world units, and how many lights each platform supports.

Updated October 20, 2026

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#

ComponentWhat it isBrightness
PointLightA bulb: light in every direction from a point.intensity in lumens. Default 1,000,000 (a very large cinema light).
SpotLightA 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.
DirectionalLightThe sun or moon: parallel rays along the entity's −Z axis, everywhere at once. Only its rotation matters.illuminance in lux.
RectLightA 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.
Rust
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#

FieldLightsWhat it does
colorallThe light's colour.
rangepoint, spotBeyond this distance the light has no effect. Smaller ranges are cheaper. Default 20.0.
radiuspoint, spotThe size of the bulb. Bigger values give softer, broader highlights. Example: spherical_area_lights.
shadow_maps_enabledpoint, spot, directionalCasts shadows. Off by default. See Shadows.
contact_shadows_enabledpoint, spot, directionalAdds screen-space contact shadows; see Shadows.
affects_lightmapped_mesh_diffusepoint, spot, directionalTurn 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::luxLuxScene
MOONLESS_NIGHT0.0001Starlight.
FULL_MOON_NIGHT0.05Moonlight.
LIVING_ROOM50Indoor lamps.
OFFICE320Office lighting.
OVERCAST_DAY1,000A grey day.
AMBIENT_DAYLIGHT10,000Daylight, not direct sun.
FULL_DAYLIGHT20,000Bright daylight.
DIRECT_SUNLIGHT100,000Direct 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:

Rust
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.

DesktopWeb (WebGL 2)
Directional lights per view101
Shadow cascades per directional light41
Point and spot lights and light probes per viewLimited by GPU memory204 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 the pbr_light_textures cargo feature, which NEO's builds don't turn on.
  • Volumetric light: add VolumetricLight (in neo::light) to a light to make it shine through volumetric fog.
  • Sun disk: SunDisk (in neo::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.

Next steps#