Shadows
Turn on shadows for lights, tune cascades, resolution and biases, stop meshes casting or receiving them, and add contact shadows.
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:
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:
| Component | Effect |
|---|---|
NotShadowCaster | The mesh casts no shadow. Use it for small props, particles and anything the player won't miss. |
NotShadowReceiver | No shadows fall on the mesh. |
TransmittedShadowReceiver | Shadows also fall on the back of a mesh with diffuse_transmission, such as a leaf. |
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:
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(),
));| Field | Default | What it does |
|---|---|---|
num_cascades | 4 (1 on the web) | How many slices. More slices give better detail at a distance and cost more. |
minimum_distance | 0.1 | Where shadows start. |
first_cascade_far_bound | 10.0 | The end of the sharpest cascade. Smaller gives crisper shadows near the camera. |
maximum_distance | 150.0 | No shadows beyond this. Keep it as small as your scene allows. |
overlap_proportion | 0.2 | How 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:
| Resource | Used by | Default |
|---|---|---|
DirectionalLightShadowMap { size } | Directional lights (each cascade) and spot lights | 2048 |
PointLightShadowMap { size } | Point lights (each cube face) | 1024 |
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:
| Field | Fixes | Too high causes |
|---|---|---|
shadow_depth_bias | "Shadow acne": stripes of false shadow on lit surfaces. | Shadows detaching from their objects ("peter-panning"). |
shadow_normal_bias | Acne 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:
| Variant | When to use it |
|---|---|
Hardware2x2 | Cheapest, with visibly jagged edges. |
Gaussian | The default. Smooth edges at a good price. |
Temporal | Noisy 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:
use neo::pbr::ContactShadows;
commands.spawn((Camera3d::default(), ContactShadows::default()));
// and on each light that should produce them:
// PointLight { contact_shadows_enabled: true, .. }| Field | Default | What it does |
|---|---|---|
linear_steps | 16 | Ray-march steps; more is more accurate and slower. |
thickness | 0.1 | How thick surfaces are assumed to be. |
length | 0.3 | How 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_distanceandfirst_cascade_far_boundto 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.