Add volumetric fog support for clustered omni and spot lights

[mvaligursky]

Extends the volumetric fog of CameraFrame, which so far was lit by a single directional light, to also be lit by the clustered omni and spot lights. Spot lights form visible beams and omni lights glow through gaps in the geometry, both correctly shadowed and cookie modulated.

Each local light is rendered as its own additive volume pass, marching only the part of the view rays that is inside the light, rather than being folded into the existing full screen march. A single uniform march over the whole view distance cannot resolve local lights - a step size sized for a 300 unit view range simply misses a light of range 10 - while a per light pass keeps the samples where the light actually is. The volume is bound by the screen space rectangle of the light's bounding sphere, and for a spot light the ray interval is further clipped analytically against the cone, so nearly all the samples land inside the beam. The shadow and the cookie atlas of the clustered lighting are sampled directly, so no additional shadow rendering is needed and the passes work on both WebGL2 and WebGPU.

Changes:

• Volumetric fog is no longer limited to a directional light. volumetricFog.light may now be null, in which case the fog is lit by the local lights and the ambient term alone.
• Omni and spot lights are enabled separately, as an omni light fills its whole bounding sphere and is therefore typically far more expensive on screen than a spot light.
• Individual lights can scatter more or less light than the others, or none at all, using LightComponent#volumetricScattering. This matters in practice because an omni light spreads its energy over every direction rather than into a cone, and so usually needs a fraction of the scattering of a spot light in the same scene.
• New extinction property, decoupling how quickly the fog absorbs light from how much it scatters. Previously density drove both, so making distant shafts brighter also made them fade out faster. A value of 1 keeps the previous, physically consistent behaviour.
• Fixed Light#getBoundingSphere aliasing the light node's position vector for omni lights instead of copying it, which allowed a later call to write into a scene node's cached position.

API Changes:

• CameraFrame#volumetricFog gains localOmniLights, localSpotLights, localIntensity, localSteps and extinction.
• CameraFrame#volumetricFog.light accepts null.
• Added LightComponent#volumetricScattering.
• Added WorldClusters#usedLights.

Examples:

• New Volumetric Fog Local Lights: sweeping spot lights and drifting omni lanterns over a terrain, with the two light types toggled independently.
• New Volumetric Fog Shafts: two spot lights orbiting a carbon 60 sphere and shining through its cage, and an omni light at its centre radiating out through the holes.

Performance:

• Off by default, and unchanged for the directional light only case apart from one extra multiply for the extinction.
• Cost scales with the screen space area of the light volumes rather than with the light count, so a few large omni lights cost far more than many small spot lights. Lights whose volume is off screen are skipped entirely.

[github-actions]

Build size report

This PR changes the size of the minified bundles.

Bundle	Minified	Gzip	Brotli
playcanvas.min.js	2351.7 KB (+23.7 KB, +1.02%)	603.8 KB (+4.8 KB, +0.80%)	469.1 KB (+3.7 KB, +0.79%)
playcanvas.min.mjs	2349.1 KB (+23.7 KB, +1.02%)	602.7 KB (+4.8 KB, +0.80%)	468.6 KB (+3.7 KB, +0.80%)

[github-actions]

Public API report

This PR changes the public API surface (+7 / −0), per the docs' rules (@ignore / @Private / undocumented are excluded).

Show API diff

+LightComponent.get volumetricScattering(): number
+LightComponent.set volumetricScattering(value: number)
+VolumetricFog.extinction: number
+VolumetricFog.localIntensity: number
+VolumetricFog.localOmniLights: boolean
+VolumetricFog.localSpotLights: boolean
+VolumetricFog.localSteps: number

Informational only — this never fails the build.

[Copilot]

Pull request overview

This PR extends the existing volumetric fog implementation (previously lit by a single directional light) to support additive volumetric scattering from clustered omni and spot lights, and introduces an extinction control to decouple absorption from scattering.

Changes:

• Adds a per-local-light volumetric fog pass (one clipped raymarch per clustered omni/spot light) with optional shadow and cookie atlas sampling (WebGL2 + WebGPU).
• Introduces an extinction scalar into the directional volumetric fog shaders and render pass plumbing to scale Beer–Lambert absorption independently of scattering.
• Adds LightComponent#volumetricScattering, exposes WorldClusters#usedLights, and fixes Light#getBoundingSphere to avoid aliasing a node position vector for omni lights.

Reviewed changes

Copilot reviewed 17 out of 22 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/scene/shader-lib/wgsl/chunks/render-pass/vert/volumetricFogLocal.js	New WGSL vertex chunk for drawing a clipped quad per local light volume.
src/scene/shader-lib/wgsl/chunks/render-pass/frag/volumetricFogLocal.js	New WGSL fragment chunk implementing clipped raymarch inside local light volumes, with optional shadows/cookies.
src/scene/shader-lib/wgsl/chunks/render-pass/frag/volumetricFog.js	Adds uFogExtinction uniform and applies it to transmittance update in the directional fog pass.
src/scene/shader-lib/glsl/chunks/render-pass/vert/volumetricFogLocal.js	New GLSL vertex chunk for the local lights volumetric fog pass.
src/scene/shader-lib/glsl/chunks/render-pass/frag/volumetricFogLocal.js	New GLSL fragment chunk for local lights volumetric scattering.
src/scene/shader-lib/glsl/chunks/render-pass/frag/volumetricFog.js	Adds uFogExtinction uniform and uses it in Beer–Lambert attenuation.
src/scene/lighting/world-clusters.js	Exposes usedLights list for iterating clustered lights (index aligned with light textures).
src/scene/light.js	Adds volumetricScattering to Light, clones it, and fixes omni bounding sphere center copying.
src/framework/components/light/component.js	Plumbs volumetricScattering through LightComponent as a new public property.
src/extras/render-passes/frame-pass-volumetric-fog.js	Integrates extinction + adds a new local-lights fog pass wired to clustered-light data/atlases.
src/extras/render-passes/frame-pass-camera-frame.js	Passes the scene forward pass into volumetric fog so local pass can access cluster data.
src/extras/render-passes/camera-frame.js	Extends CameraFrame volumetric fog options/API (local lights toggles/intensity/steps + extinction) and updates support checks.
examples/src/examples/graphics/volumetric-fog-shafts.example.mjs	New example showcasing spot beams + omni glow through geometry using local volumetric lights.
examples/src/examples/graphics/volumetric-fog-shafts.controls.jsx	UI controls for the “Volumetric Fog Shafts” example.
examples/src/examples/graphics/volumetric-fog-local-lights.example.mjs	New example combining directional shafts with clustered local volumetric scattering.
examples/src/examples/graphics/volumetric-fog-local-lights.controls.jsx	UI controls for the “Volumetric Fog Local Lights” example.
examples/assets/models/carbon-sphere.txt	Attribution/license info for the new carbon sphere example asset.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.