NEOLearn

Shadows

Turn on shadows for lights, tune cascades, resolution and biases, stop meshes casting or receiving them, and add contact shadows.

Updated October 20, 2026

On this page

Shadows come from shadow maps: the renderer draws the scene from each shadow-casting light and checks every pixel against that picture. They're off by default because each shadow-casting light costs extra rendering. Turn them on for the lights that matter, usually the sun and a few nearby lamps.

Turn shadows on#

Set shadow_maps_enabled on the light:

Rust
commands.spawn((
    DirectionalLight {
        illuminance: light_consts::lux::AMBIENT_DAYLIGHT,
        shadow_maps_enabled: true,
        ..default()
    },
    Transform::from_xyz(4.0, 8.0, 4.0).looking_at(Vec3::ZERO, Vec3::Y),
));

PointLight and SpotLight have the same field. Point lights render six views (a cube map), so they're the most expensive shadow casters. Area lights (RectLight) never cast shadows.

Choose what casts and receives#

Two marker components in neo::light opt a mesh out:

ComponentEffect
NotShadowCasterThe mesh casts no shadow. Use it for small props, particles and anything the player won't miss.
NotShadowReceiverNo shadows fall on the mesh.
TransmittedShadowReceiverShadows also fall on the back of a mesh with diffuse_transmission, such as a leaf.
Rust
use neo::light::NotShadowCaster;

commands.spawn((
    Mesh3d(meshes.add(Sphere::new(0.1))),
    MeshMaterial3d(materials.add(Color::WHITE)),
    NotShadowCaster,
));

Materials with AlphaMode::Mask cast cut-out shadows, so foliage shadows have holes where the texture is transparent. Example: cargo run --example shadow_caster_receiver.

Directional light cascades#

A directional light covers the whole world, so its shadow map is split into cascades: a detailed one near the camera and coarser ones further away. CascadeShadowConfig on the light controls them; build one with CascadeShadowConfigBuilder:

Rust
use neo::light::CascadeShadowConfigBuilder;

commands.spawn((
    DirectionalLight { shadow_maps_enabled: true, ..default() },
    Transform::from_rotation(Quat::from_rotation_x(-0.8)),
    CascadeShadowConfigBuilder {
        num_cascades: 3,
        first_cascade_far_bound: 4.0,
        maximum_distance: 40.0,
        ..default()
    }
    .build(),
));
FieldDefaultWhat it does
num_cascades4 (1 on the web)How many slices. More slices give better detail at a distance and cost more.
minimum_distance0.1Where shadows start.
first_cascade_far_bound10.0The end of the sharpest cascade. Smaller gives crisper shadows near the camera.
maximum_distance150.0No shadows beyond this. Keep it as small as your scene allows.
overlap_proportion0.2How much neighbouring cascades overlap, to hide the seams.

Web builds support one cascade per light and one directional light per view.

Resolution#

Two resources set the shadow map size in texels. Bigger is sharper and uses more memory:

ResourceUsed byDefault
DirectionalLightShadowMap { size }Directional lights (each cascade) and spot lights2048
PointLightShadowMap { size }Point lights (each cube face)1024
Rust
use neo::light::DirectionalLightShadowMap;

app.insert_resource(DirectionalLightShadowMap { size: 4096 });

The directional size must be a power of two.

Biases#

Shadow maps have limited precision. Two biases on each light fix the usual artefacts:

FieldFixesToo high causes
shadow_depth_bias"Shadow acne": stripes of false shadow on lit surfaces.Shadows detaching from their objects ("peter-panning").
shadow_normal_biasAcne on surfaces at a steep angle to the light.Shadows shrinking or leaking at contact points.

Defaults are 0.02 and 1.8 for directional and spot lights, and 0.08 and 0.6 for point lights. Point and spot lights also have shadow_map_near_z: nothing closer to the light than this casts a shadow. Example: cargo run --example shadow_biases --features free_camera.

Filtering#

ShadowFilteringMethod on the camera (in neo::light) chooses how shadow edges are softened:

VariantWhen to use it
Hardware2x2Cheapest, with visibly jagged edges.
GaussianThe default. Smooth edges at a good price.
TemporalNoisy on its own; use it together with TAA, which smooths the noise over frames.

Soft shadows#

Soft shadows that blur with distance from the caster (percentage-closer soft shadows) use the light's soft_shadows_enabled (point and spot) or soft_shadow_size (directional) field. Those fields only exist with the experimental_pbr_pcss cargo feature, which NEO's builds don't turn on. Example: pcss.

Contact shadows#

Shadow maps miss small details where objects touch the ground. Contact shadows add them by ray marching the depth buffer:

Rust
use neo::pbr::ContactShadows;

commands.spawn((Camera3d::default(), ContactShadows::default()));
// and on each light that should produce them:
// PointLight { contact_shadows_enabled: true, .. }
FieldDefaultWhat it does
linear_steps16Ray-march steps; more is more accurate and slower.
thickness0.1How thick surfaces are assumed to be.
length0.3How far the ray goes, in world units.

ContactShadows adds a depth prepass to the camera. WebGL 2 can't read the depth prepass, so contact shadows don't work in web builds.

Performance#

  • Enable shadows on as few lights as possible, and prefer spot lights to point lights for local shadow casters.
  • Tighten maximum_distance and first_cascade_far_bound to your scene's scale instead of raising the map size.
  • Mark small and distant meshes NotShadowCaster.
  • NEO's console lighting path skips shadows entirely; see Materials.

Next steps#