scenarios.module

Several baked lighting states per probe volume, blended at runtime.

A volume holds one bake, so a scene lit for noon cannot become a scene lit for dusk without baking again — which takes far longer than a transition is allowed to. Capturing each bake under a name turns that into an interpolation the frame can afford.

local scenarios = require("@builtin::systems.globalIllumination.scenarios")

scenarios.capture(volId, "noon")     -- after baking under one lighting setup
scenarios.capture(volId, "dusk")     -- after baking under another
scenarios.blend(volId, { noon = 0.25, dusk = 0.75 })

Weights are normalised, so any positive scale expresses the same blend. A name with no capture is an error rather than a silent omission, so a typo does not quietly become a blend of everything else.

mix(fields, weights) is the blend itself and is pure — the same fields and weights give the same array, so what a blend does to a field can be checked without a volume or a GPU.

field(volId, name) hands back a capture for inspection or a blend of your own. list / forget / clear manage what a volume carries, and stats() reports how many volumes hold scenarios and how much they hold between them.

What gets blended

Irradiance adds, so blending the spherical-harmonic coefficients is the same as blending the light that produced them.

Each coefficient's fourth lane is not light: it carries the probe's per-axis visibility reach and the markers the sampler reads. Those describe the geometry the volume sits in, which every scenario shares, so they are carried from the heaviest-weighted scenario rather than averaged — the mean of two distances describes no wall that exists.

Carrying them from the heaviest contributor also makes the ends of a transition exact: a blend naming one scenario at full weight reproduces that scenario's field lane for lane.