Contact Shadows

[aevyrie]

Objective

• Implement contact shadows to add fine shadow detail where shadow cascades cannot.

Solution

• Extend our existing pbr implementation using our existing raymarching functions.

---

Showcase

Screen.Recording.2026-01-07.at.11.18.18.PM.mp4

Screen.Recording.2026-01-04.at.7.19.25.PM.mp4

Screen.Recording.2026-01-04.at.7.36.03.PM.mp4

[tychedelia]

Would you mind adding or updating an existing example?

[aevyrie]

Sure, I was going to ask the crowd where it would make sense to add to an example.

[github-actions]

It looks like your PR has been selected for a highlight in the next release blog post, but you didn't provide a release note.

Please review the instructions for writing release notes, then expand or revise the content in the release notes directory to showcase your changes.

[JMS55]

Closes #16164

[JMS55]

Does it make sense to do the raymarching directly in the material shader? It might give better perf to pull it out to its own pass.

Also MeshletMesh needs testing with this feature (and in the various forward/deferref/prepass modes).

[pcwalton]

I have an example for contact shadows that I made in my old branch: https://github.com/pcwalton/bevy/blob/contact-shadows/examples/3d/contact_shadows.rs

Feel free to steal it if you want, or not (it's rather old and would need to be updated). Up to you :)

[pcwalton]

@JMS55 I don't think the raymarching can really be done anywhere else, because in forward you need to know what's in shadow right then. You can't really subtract a light after the fact. (Well, maybe you technically could make it work, but that'd be a huge can of worms.)

[github-actions]

The generated examples/README.md is out of sync with the example metadata in Cargo.toml or the example readme template. Please run cargo run -p build-templated-pages -- update examples to update it, and commit the file change.

[aevyrie]

This 07f2b89 commit adds a bunch of diffs from renaming the shadow map setting, per discord.

[IceSentry]

The blast radius of the shadow_maps_enabled was bigger than I expected.

[IceSentry]

Couple of minor notes but other than that LGTM. Massive visual improvements, thank you!

[github-actions]

It looks like your PR is a breaking change, but you didn't provide a migration guide.

Please review the instructions for writing migration guides, then expand or revise the content in the migration guides directory to reflect your changes.

[JMS55]

@aevyrie can we break the shadow map renaming code out into a new PR?

[aevyrie]

Sure, would that add any value? shadows_enabled is a bit misleading without a rename.

[JMS55]

It would help for review, but also e.g. Solari has shadows, but dosen't use shadow maps, so it's already misleading as-is.