Skip to content

3D engine that AI agents drive

66.3 KB
Raw Blame

Depth-clipped volume fog

Available from version 0.4.0.

The fog code is an addon: import '@codepawlhq/crucible/addons/fog-shader' before the first frame that draws a fog, or a renderer that draws one throws and names this import. Recipes load it by themselves (await loadAgentSceneModules(recipe)), and the MCP server and the film player already do.

Enable { hdr: true, depth: true } when constructing an opaque, non-benchmark CrucibleRenderer. Active fog requires WebGL 2 EXT_color_buffer_float. Unsupported HDR negotiation rejects active fog. The depth option retains a resolved depth texture across frames and includes it in memoryPlan.

const renderer = new CrucibleRenderer(canvas, parts, {
  hdr: true,
  depth: true,
  ground: false,
  environment: {
    lightDirection: [-0.35, 0.55, -0.85],
    volumeFog: {
      density: 0.065,
      minimum: [-5.7, 0.03, -4.7],
      maximum: [5.7, 4.5, 5.5],
      color: [0.9, 0.83, 0.7],
      steps: 24,
      maxDistance: 15,
    },
  },
});
renderer.render({ eye: [0, 2, 5], target: [0, 1, 0], time: 0 });

Controls

environment.volumeFog defines one axis-aligned world-space volume. frame.environment.volumeFog replaces the whole constructor fog object for that frame. Omitted fields use the following defaults. Set density: 0 to disable it.

Field Default Accepted range
density 0 0…10, extinction per scene unit
minimum [-100, 0, -100] Three components within ±100,000
maximum [100, 20, 100] Three components within ±100,000; greater than minimum after Float32 rounding
color [0.8, 0.85, 0.9] Linear RGB, 0…1
ambient [0.03, 0.035, 0.04] Linear RGB, 0…10
steps 16 Integer 8…48
anisotropy 0.3 -0.9…0.9; positive favors forward scattering
noiseAmount 0.5 0…1; zero gives uniform density
noiseScale 0.3 0.001…100, inverse scene units
drift [0.03, 0, 0] Three components within ±100, scene units per second
maxDistance 100 0.01…10,000, ray distance in scene units
shadowAmbient derived 0…1; the share of ambient the fog keeps where the sun's shadow covers it. Left unset, 32 upward rays from the middle of the fog box decide: a closed room keeps 0.15, open ground under a sky keeps 1, and a partly covered scene lands between. Set it to override
field none A fog field, see below
profile 'exponential' 'exponential' or 'smoothstep'; the vertical shape of a layer when a field is set
flowStrength 1 0…100; how far the noise travels along the field's velocity, as a share of velocity times flowPeriod
flowPeriod 2 0.01…1,000 seconds; how often a noise lookup restarts
detailOctaves 1 Integer 1…3; noise octaves at 1x, 2x and 4x noiseScale. Above 1 the frame compiles the detail step in
detailAmount 0.5 0…1; weight of the extra octaves against the base noise, which keeps its own weight
warp 0 0…4; domain warp strength in noise cells, for wisps and curls
contrast 1 0…4; stretches the noise around its middle, so thin gaps sit next to thick patches
profileSoftness 0.5 0…0.95; where the 'smoothstep' layer top starts to fade, as a share of the layer height. Lower tapers from nearer the floor
keyScattering 1 0…10; scales the key light's in-scattering (the shadow-mapped god rays) and leaves ambient alone
scatterOctaves 1 Integer 1…4; above 1 the key light's in-scatter sums octaves that approximate multiple scattering (Wrenninge et al. 2015). Octave n scatters multiScatter^n as much, sees multiExtinction^n of the extinction and has multiAnisotropy^n of the anisotropy. Each octave needs the optical depth to the sun, three extra density taps per step
multiScatter, multiExtinction, multiAnisotropy 0.5, 0.5, 0.5 0…1 each; the octave factors above. They act only with scatterOctaves above 1
keyTransmittance 0 0…1; how much of the fog between a point and the sun dims the key light scattered there (three taps along the light, to the box exit). 0 keeps today's look
surfaceTransmittance 0 0…1; the same dimming for the key light on a lit surface inside the box, so a dense haze dims a sunlit floor. 0 keeps today's look
beamRadius 0 0…20 metres; above 0 the octaves beyond the first count only as far as the sun reaches around the point: four shadow-map taps this far off, across the sun's direction, give the lit share that scales them. A narrow shaft keeps a narrow glow and a wide beam keeps all of it. 0 keeps every octave as is. Acts only with scatterOctaves above 1

Values must be finite numbers, and the detail fields are checked with the rest when the scene or a set-environment edit is built. Active volume fog accepts finite frame time within ±1,000,000 seconds and a nonzero light direction with components within ±1,000,000. Noise samples absolute time, so backward seeks reproduce earlier density.

Fog field: density and velocity per footprint cell

volumeFog.field is a 2D texture over the box's x/z footprint that the caller fills each frame, for fog that reacts to things (a character walks through it, a slam pushes it away). Crucible only samples it; the simulation is the caller's.

const data = new Float32Array(160 * 160 * 4); // RGBA, row 0 at the box's minimum z, column 0 at its minimum x
// r: density multiplier (1 = the fog as is, 0 = a hole), g: layer height in metres, b: velocity x, a: velocity z (metres per second)
renderer.setFogField({ width: 160, height: 160, data }); // stays until replaced; setFogField(null) clears it
// or per frame: environment: { volumeFog: { density: 1.2, minimum, maximum, profile: 'smoothstep', field: { width: 160, height: 160, data } } }
  • Density at a point is density * field.r * profile(y / field.g) * noise, with y measured from minimum[1]. profile is exp(-y / g) for 'exponential' and 1 - smoothstep(0.5, 1, y / g) for 'smoothstep', a flat body with a soft, readable top. With a field, heightFalloff is not used: the field's layer height replaces it.
  • The texture is RGBA16F, linear filtered and clamped at the edges, so the field may be coarse. data is a Float32Array of width * height * 4 finite values; width and height are integers within 1…2048. Anything else throws and names what it wanted.
  • A frame with a field uploads it, so rewriting the same Float32Array between frames is enough. The same size writes into the existing texture (texSubImage2D); a new size allocates a new one. setFogField wins over a field in the frame or constructor environment.
  • Flow: the noise lookup is carried along the field's velocity by two lookups that restart half a flowPeriod apart and cross-fade (Vlachos, "Water Flow in Portal 2", 2010), so detail swirls with the flow instead of drifting one way. It depends on frame time and the field only, so the same time and field give the same pixels after any seek. The constant drift still applies. Noise contrast dips slightly mid-fade, as in any flow map.
  • A fog without a field is drawn by the program it had before, pixel for pixel. The first frame with a field or a light compiles its program before drawing.

Point and spot lights in the fog

Every point and spot light of the frame (environment.pointLights, spotLights) scatters in the march: points first, then spots, at most 8. Each uses the light's range window and inverse square (the same as lit surfaces, with the light's radius floored at 0.1 m so the glow has no spike), the spot cone, its colour times intensity and the fog's Henyey-Greenstein phase. There are no shadows and no light linking in the fog. Light beyond the eighth is left out.

Sky visibility of the fog

Pass fogSkyVisibility from src/fog-sky-visibility.js to CrucibleRenderer (the agent preview and the reference harness do) and the fog's ambient follows a per-point sky visibility instead of one share for the whole box. skyVisibilityGrid in src/closed-room.js shoots 24 fixed upward rays from the centre of each cell of a grid over the fog box (at most 2,048 cells and 32 along an axis), once per scene and fog box, and the result is uploaded as one 8-bit 3D texture. The post shader samples it with trilinear filtering in the shadowed fog: a point that sees any sky keeps all of the ambient, a point that sees none keeps 0.1 of it, and fog the sun reaches keeps all of it as before. Without the option, or when volume fog is off, the sampling is compiled out of the post shader and the frame is drawn by the program it had before. A scene of more than 150,000 triangles has no grid and draws as before. The rays run on the CPU: 0.03 s for dark-shaft (1,120 triangles) and 1.7 s for temple-hall (11,892 triangles) at scene build. A recipe that sets shadowAmbient keeps it and gets no grid.

The same option carries a second term, the light that surfaces give the fog. The renderer passes its frame environment to the option, and fogBounceGrid (src/fog-bounce.js) shoots 64 fixed rays from the centre of each cell of the same grid, takes the nearest surface each ray hits, and sums what that surface sends back: its emission plus the point lights that reach it times its albedo over pi (the light bake's createDirectIrradiance, with shadow rays). The mean over the rays is the radiance isotropic scattering at the cell sends to the eye. The grid is one RGBA16F texture, sky visibility in red and the bounce in green, blue and alpha, and the shader adds 0.6 of the bounce to the fog's scattering. A glowing window or a lamp therefore lights the fog around it, which the sky grid could not. Parts with an emissive map (a baked part carries its lightmap there) and the sun add nothing: the sun's bounce made dark-shaft worse (fog region 0.1282 to 0.1764 against Cycles), because the fog's ambient already stands in for it in a lit room. The scalar grid is isotropic, so it cannot follow the forward-scattering lobe (anisotropy) toward a window the camera looks at; that is why the weight is below 1. A scene with no emissive part and no point light builds an all-zero bounce and draws as before. Building it costs 0.3 s for temple-hall (11,892 triangles) and 0.07 s for dark-shaft, on top of the sky rays.

Lighting and depth

The fullscreen march clips against resolved opaque depth, supports perspective and orthographic cameras, and stops at the volume boundary or maximum distance. It integrates Beer-Lambert extinction and directional single scattering with a Henyey-Greenstein phase function. It uses the existing directional shadow map and key-light color. Keep authored shadow bounds aligned with the light direction and covering the medium.

Parts also take receiveShadow, holdout, shadowCatcher and visible; see agent-scene.md. part.castShadow: false excludes a mesh from shadow rendering while keeping it visible and opaque in the color/depth pass. The flag defaults to true and must be boolean. Shadow-casting groups use separate batches. Changing a part's casting regime requires a new renderer. updateParts() rejects that change. A luminous window can omit its shadow, but remains an opaque emissive surface rather than transparent glass.

Cost and limits

Resolved depth adds four estimated bytes per rendered pixel, or 2,073,600 bytes at 960 × 540. The planner reduces render dimensions when needed. The target is allocated at construction/resize, reused across frames and released by dispose(). The march adds no additional volume textures or geometry, but shading cost grows with covered pixels and step count.

This implements one bounded medium, a directional source with shadows and up to 8 unshadowed point and spot lights. Multiple scattering, attenuation toward the source, transparent depth, volume grids in the fog itself (local volumes take grids, below), particles, temporal accumulation and half-resolution rendering remain unfinished. The legacy film explosion is separate and does not use this depth-clipped medium. Fog runs after bloom extraction, so scattering itself does not feed bloom (a glowing local volume does, see below).

Measured at 1920 × 1080 with 24 steps on an RTX 3060 shared with other jobs, whole frame (a small scene, fog and read-back): the fog as before 3.6 to 3.7 ms; with a field 4.8 to 5.1 ms (about 1.3 ms more); with 8 point lights 7.3 to 7.4 ms (about 0.46 ms per light); both 8.6 to 8.8 ms. Numbers move with other jobs on the card.

Run node scripts/smoke-volumetric.mjs with the development server running for native GPU extinction, foreground clipping, directional shadow, long-distance ray, resource reuse and disposal checks. Run node scripts/benchmark-volumetric.mjs for a fixed laboratory comparison and deterministic noise seeking. These fixtures establish behavior, not cinematic trailer quality.

In a scene with an irradiance grid (bake.irradianceGrid) the bounce term is the grid's mean light at the cell instead of the fog's own 64 rays: the grid already holds the sun's bounce, the lights and the emission over several bounces, so the sun is not left out there. The fog's ambient then stands for the sky only (it follows the cell's sky visibility, with no floor for the sun's shadow), because the grid replaces what the ambient stood in for. Measured on the reference halls (FLIP against Cycles, lower is better): temple-hall-a 0.1454 to 0.1323, temple-hall-b 0.1211 to 0.1085, temple-hall-c 0.1078 to 0.0874, temple-hall 0.0576 to 0.0513. dark-shaft, a small room with dense fog, goes from 0.0569 to 0.0732: the grid's light in its shade is about three times the fog's old stand-in, and Cycles draws that shade darker still.

Local volumes

environment.localVolumes holds up to 8 boxes, spheres or parts that absorb and emit light: candle haze, a smoke puff, a glowing cloud in one place. They need no volumeFog. With scatter at its default 0 they do not scatter, so the sun and the sky do not light them; they only dim what is behind them and add their own glow. Raise scatter to light them (see "Lit volumes"). A scene without localVolumes draws exactly as before and compiles nothing extra. At most one of them takes shape: "grid"; a second one is refused when the scene or set-environment is built, with the same message as the render.

{ "environment": { "localVolumes": [
  { "shape": "sphere", "center": [0, 1.2, 0], "radius": 0.8, "density": 3, "absorption": [1, 1, 1], "emission": [1, 0.45, 0.1], "emissionStrength": 4, "noiseAmount": 0.6, "noiseScale": 2 }
] } }
Field Default Meaning
shape box box takes size: [width, height, depth], sphere takes radius, mesh takes part
center required for box and sphere World position
part, fit required, bounds mesh only. part names a part of the scene (a node ID with geometry, checked when the scene or set-environment is built); fit is bounds or mesh (see below)
density 1 0 to 100. Extinction per unit length at the core
absorption [1, 1, 1] Per colour channel share of the density, 0 to 1. A larger value dims that channel more, so [0.1, 0.6, 1] removes blue first and leaves a warm tint
emission, emissionStrength [0, 0, 0], 1 Glow colour and its radiance per unit length at the core, 0 to 1000. Emission does not depend on density, so density: 0 is a pure glow
emissionRamp none A glow that grades with the density, from a blackbody curve or a colour ramp (see "Emission ramp"). Not for mesh
falloff 0.5 0 to 1. The outer share of the volume over which the density fades to zero (0 is a hard edge)
blur 1 0 to 1. How much the light seen through the volume is blurred, by its optical depth (see Thick smoke and thin haze). 0 keeps it sharp
shadowDetail false true makes the key light's shadow inside a scattering volume follow its density: 8 taps along the light that read the noise instead of 3 that read the smooth profile, so a noisy smoke is dark where its own puffs stand between a point and the sun and bright through its gaps. Costs five more profile reads per step. A box or a sphere; not for shape: "grid" or a mesh volume. false draws as before
castShadow false true makes a box, sphere or grid dim the key light on the opaque surfaces under it: 8 taps along the sun read the noisy profile (a grid takes 16 taps of its simulated density as it is, with no saturation and no extra strength, so the shadow follows the sim and matches Cycles' floor under the same smoke), so the floor under a smoke puff is darker where the puff is thick and open where the sun slips past. The CPU path tracer scales the sun's direct light by it; the rasterizer's post pass scales the surface colour by it where the shadow map leaves the surface lit, and the sky and fill light stay as they were. The post pass cannot tell a lit surface from a glowing one, so it dims a glowing surface under the smoke too; it does nothing when the key light is off. Emissive caveat: do not turn it on for a scene with glowing surfaces (a lit lamp, a screen, a window) under a volume, because they are dimmed with the rest. false draws as before, bit for bit, which is why it is the default. Not for a mesh volume yet
shadowDetail false true makes the key light's shadow inside a scattering volume follow its density: 8 taps along the light that read the noise instead of 3 that read the smooth profile, so a noisy smoke is dark where its own puffs stand between a point and the sun and bright through its gaps. Costs five more profile reads per step: four noisy scattering boxes at 1080p took 13.1 ms a frame on an RTX 3060 and 19.4 ms with it on, while castShadow and scatterOctaves added nothing measurable. A box or a sphere; not for shape: "grid" or a mesh volume. false draws as before
scatterOctaves 1 A whole number from 1 to 4: the octave sum of volumeFog (scatterOctaves) for the key light of a scattering volume, so a thick smoke is lit in its shade the way the many scatters of a real smoke fill it. Octave n scatters half^n as much, sees half^n of the light's optical depth and has half^n of the anisotropy (a grid volume's anisotropy). Three octaves roughly triple the key light a thick box returns. 1 is the single scatter and draws exactly as before
lightsScene false true adds one point light for the volume, so its glow lights the floor, the props and the smoke around it (see "Fire lights the set"). A box or sphere counts its emission times emissionStrength over its volume at its centre; a grid sums its flame and blackbody light and puts the light at the flame's centre of light. The light follows the animated frame. At most as many lights as the scene has room for (MAX_POINT_LIGHTS). Not for shape: "mesh". false draws as before
scatter 0 0 to 1. The share of the light the volume extinguishes that it scatters back instead of absorbing, lit by the key light and the sky (see "Lit volumes"). 0 draws exactly as before. Not allowed with fit: "mesh"
noiseAmount, noiseScale 0, 1 noiseAmount 0 to 1 breaks the density up with value noise at noiseScale cells per unit: the profile is multiplied by mix(1, 2 * noise, noiseAmount), and the noise also pushes the faded edge in and out (by up to half the fade width times noiseAmount, zero at the core and at the outer face), so a box or a sphere with a wide falloff such as 0.85 reads as a cloud and not as a rounded rectangle. The rasterizer and the CPU path tracer read the same field. A fit: "mesh" volume ignores it
noiseOctaves 1 A whole number from 1 to 5. With more than one, the noise is a fractal sum: each octave is the same value noise at twice the scale and half the weight of the one before (lacunarity 2, gain 0.5), divided by the weights so the mean stays near 0.5. One octave gives a lumpy blob; four put small detail on top of the large shapes, the ragged edge of smoke and fire. It needs noiseAmount above 0. The rasterizer and the CPU path tracer sample the finest octave at two samples per cell, up to 96 steps along a ray, whatever steps says (plain noise stays capped at 32). The WebGPU path tracer draws it too (its kernel splices the octave loop in only for a scene that uses it); a grid volume rejects it. A volume without the field compiles to the same shader text and renders as before
steps 16 4 to 32 samples through the volume. With noiseAmount above 0 the count is raised to two samples per noise cell along the ray (ceil(length * noiseScale * 2), at most 32), because fewer samples than that skip whole cells and a fine pixel-pitch dither of the start offset shows in dense smoke (8 steps measured); a volume without noise takes exactly steps

Inside one step the glow is weighted by the exact integral over the step, not by the transmittance at its start (#1894). A step of optical depth tau (its extinction times its width, per colour channel) adds emission * width * (1 - exp(-tau)) / tau of light, then dims what lies behind by exp(-tau); with the start-of-step weight every step counted its light too bright, by about 25 percent at tau 0.44, which is a dense box or sphere at 32 steps. Below tau 0.001 the weight uses its series. The rasterizer's shape and grid marches, the CPU path tracer's shape, grid and mesh marches and the WebGPU tracer's shape and grid marches all use it (src/volume-step-integral.js), so a dense volume is dimmer than it was and a thin one, whose weight is near 1, is unchanged. On the 1-octave sphere of bench/cycles-parity/capture-volume-edge.mjs (density 7, 32 steps) the edge width went from 0.2926 to 0.2295 sphere radii and the core from 0.697 to 0.618, against Cycles' 0.2330 and 0.619. The scatter term already used 1 - exp(-extinction) and is unchanged.

Each volume is marched between its entry and its exit, cut at the first surface, and the volumes are composited nearest entry first. Two boxes or spheres that share a stretch of the ray are marched together over it: the volume that starts where the nearest one starts joins its march, which stops where another volume starts or one of the two ends, and at every step the glow and the dimming of both add. A soft edge therefore stays soft where another volume's entry plane lies in front of it; before this, the nearer volume was marched whole and dimmed the farther one's glow in front of it, which drew a hard slab. The CPU path tracer marches them the same way (the WebGPU kernel still composites nearest entry first). Three or more volumes that overlap are joined in pairs, nearest first, and a mesh volume or a grid volume is still marched whole, so those overlaps stay an approximation. A scene whose volumes do not overlap, and a scene with one volume, draws bit for bit as before. A frame that overlaps volumes keeps the cost of the marches (a stretch costs the larger step count of its two volumes) and splits a long volume into at most a few stretches. Local volumes are drawn before volumeFog, so a fog in front of a puff also dims it. They need the same renderer as the fog (hdr: true, depth: true, an opaque canvas) and are drawn in the post pass, so they are not in the lightmap bake: a scene bake (bake in a recipe) leaves them out, an emissive volume lights no baked surface and no volume dims the baked light, and the bake report names them in skippedLocalVolumes (index, shape, whether emissive) with a warnings line. A scene without local volumes bakes and reports exactly as before. Add a point light or an emissive part where the volume's glow should reach a wall. The path tracer traces them on backend: "cpu" with the same fields, noise included, and on backend: "webgpu" (the megakernel) for box, sphere, mesh and grid volumes: the WGSL march repeats the CPU one (same step count, jittered midpoints, falloff, noise, sun and sky light of a scattering volume), compiled in only for a scene that has volumes, and on the 480 by 300 reference scene at 32 samples it differs from the CPU frame by a mean FLIP of 0.0011. A mesh volume (#2004) is drawn there too, with the CPU tracer's model: its part's triangles and their own BVH sit in a block at the end of the volume buffer, the ray is walked from surface crossing to surface crossing, the parity of the crossings says where it is inside, and the inside segments share the volume's steps by length, with absorption and emission and a profile of 1. The WebGPU walk steps 1e-5 of the volume's diagonal past a crossing where the CPU walk steps 1e-6, because it works in 32 bit. The mesh block is compiled and uploaded only for a scene that has a mesh volume, a scene may hold at most 262144 triangles across its mesh volumes (the error says to simplify the parts or use backend "cpu"), and on the L-shaped room scene of tests/helpers/mesh-volume-render.js at 32 samples the WebGPU frame differs from the CPU frame by a mean FLIP of 0.0020. Backend native still refuses a mesh volume. A grid volume (#1785) is drawn there too: its voxels follow the volume table in the same storage buffer (the megakernel binds storage buffers only, so no 3D texture), read with the same trilinear weights as the CPU tracer, with one velocity tap per step for volumeShutter and the baked blackbody emission; a 128 cubed grid with blackbody and shutter is about 100 MB of float vectors, so lower --max-resolution for a device with a smaller storage buffer; the WebGPU wavefront kernel and the realtime WebGPU tracer refuse every local volume. Backend native (Cook) draws grid volumes, see "Grid volumes in Cook" below; a box, sphere or mesh volume there throws an error that names its kind. Every other tracer entry point (backend gpu, the progressive and both realtime tracers, the GPU light bake) throws environment.localVolumes is traced by the CPU path tracer only instead of leaving them out. Cost grows with the covered pixels times steps times the number of volumes that the pixel's ray crosses; a ray that misses every volume pays only the interval test.

Thick smoke and thin haze

density is the extinction per metre at the core, times each channel of absorption. The light behind a ray that crosses length metres of core is multiplied by exp(-density * absorption * length) (Beer-Lambert), in the rasterizer and the CPU path tracer alike. Scattering is not a second loss: scatter only returns that share of what the extinction took, so a lit volume never adds more than its lights give. The faded skin and the noise lower the mean along a ray (a 3.2 m box with falloff 0.7 crosses about 2 m of core density), so pick by the transmittance you want:

Look density (3.2 m box) Light left behind the core Use
Thin haze or wisp 0.3 (falloff 0.5) 50 to 65 percent The background shows, blurred
Medium smoke 1.5 (falloff 0.7) 6 to 25 percent Shapes behind are faint ghosts
Thick smoke 3 (falloff 0.6) under 3 percent The core hides the background

Measured on the 2.4 m high, 3.2 m wide box of the smoke still, from rays through its middle (noise 0.5): density 0.3 let 50 to 64 percent of the green channel through, 1.5 let 6 to 25 percent and 3 let 0.2 to 2.7 percent. A uniform slab of 1 m (falloff: 0) of density 3.5 let 0.0303 through in the rasterizer and 0.0302 in the tracer against exp(-3.5) = 0.0302; density 0.7 gave 0.4978 and 0.4965 against 0.4966 (tests/local-volume-blur.test.js; worst 8 by 8 region differed by 0.0013).

Thin smoke also blurs what is behind it. The rasterizer averages 12 taps of the frame over a disc of radius 24 * (1 - exp(-1.5 * opticalDepth)) pixels of a 540 row frame (it scales with the frame height), where the optical depth is the mean of the extinction along the ray, times blur. It is zero at zero depth and never passes 24 px, only runs on pixels whose ray meets a volume, and a tap counts only where its surface lies at or past the ray's first volume entry, so an object in front of the volume is not smeared into it (the depth is also read one filter footprint to each side of the tap, so the filter does not carry the colour of an object's edge into the volume). It reads the frame's mip chain, so a frame with a blurring volume generates mips like a frame with volumeFog. The CPU path tracer marches straight through a local volume and does not scatter the background, so it draws the same dimming but no blur: set blur: 0 to compare the two.

Lit volumes

A volume with scatter above 0 returns, in each step, scatter * (1 - exp(-extinction * step)) of the light it dims, per colour channel, times the light that arrives at that point: the sky term plus the key light. Smoke or haze in sun then reads bright on the side toward the sun and grey in shade, where a scatter: 0 volume draws as a dark stain.

  • The key light uses the same shadow map lookup (keyVisibility) and phase function (henyeyGreenstein, isotropic here) as volumeFog, times exp(-depth * 5) where depth is the volume's own optical depth between the point and the volume's far side toward the sun (three midpoint taps of its smooth profile, without the noise, so the noise does not speckle the shading). The direction of those taps is the sun's with its elevation cut to a tenth (LOCAL_VOLUME_SUN_FLATTEN): a low sun reaches a smoke box through its top face as fast as through its side, which made the top edge glow as bright as the sunward edge and hid the gradient across the form, and the many scatters of a real smoke spread the light sideways anyway. The factor 5 (LOCAL_VOLUME_SHADOW_STRENGTH in src/local-volumes.js) counts the depth more than once so the shaded side stays dark; the key light is also scaled by LOCAL_VOLUME_KEY_GAIN (8), the many scatters of a thick smoke that one isotropic scatter leaves far dimmer. Together they make the sunward side clearly brighter than the shaded side. Only the key light and the sky light a volume: point, spot and area lights do not.
  • The sky term is the mean of skyTop and skyBottom times ambientIntensity in the rasterizer, and the mean radiance of environment.map in the CPU path tracer. With an environment map the rasterizer still reads skyTop and skyBottom. It passes through the volume's own depth too: the mean of exp(-depth) over the up direction and the four horizontal directions, one midpoint tap each of the smooth profile, so the middle of a thick smoke is darker than its rim instead of glowing as evenly as the edge. It is then scaled by LOCAL_VOLUME_SKY_GAIN (0.2): the sky lights the whole volume evenly, so a larger share veils the form the sun gives it and washes out what sits inside.
  • The CPU path tracer uses the same model on backend: "cpu": the sky term, a shadow ray toward the sun, and the same three taps. The sun's colour is keyColor there.
  • A scene with a lit volume draws the key light's shadow map for the post pass, as a fog does. A volume with scatter: 0 pays nothing extra per step.
  • Measured (tests/local-volume-scatter.test.js, a density 1.2 smoke box under a side sun over an even grey sky, seen from above; 64 px rasterizer on SwiftShader against the 32 px, 16 sample CPU tracer): the worst of 64 regions differed by 0.0001 of linear radiance and the whole frame matched to four places (0.3351 both), inside the 0.01 and 0.005 tolerances. The half toward the sun read 0.341 and the shaded half 0.329 in both renderers. On the 960 x 540 smoke still (sun from the right, a 3.2 x 2.4 x 3.2 box) the right third of the smoke is about 14 to 17 percent brighter than the left third in displayed luma; the sun sits in front of the box, so no setting of the two factors takes that far past 20 percent without clipping the sunlit side. The volume pass costs about 2 ms a frame at scatter 0.8 against 0.7 ms at scatter 0. Round 3 (#859): the depth the light crosses counts the faded skin at up to three times its density (LOCAL_VOLUME_LIGHT_DEPTH_SATURATION), because a sun ray running along the faded top skin met almost no density and lit it far above the core, which drew a bright rim; the key gain is 3 (a thin smoke returns at most what a sunlit surface of the same albedo does), the shadow strength 3 and the sky gain 0.5. The fade of a box is measured past its core box, so it is round at the corners; the largest-ratio fade drew mitred creases along the box diagonals. A smoke with falloff 0.7 and noiseAmount 0.5 has no visible box outline.

Emission ramp

emission is one colour. emissionRamp makes the glow depend on how much of a source is at each point, so one volume grades from a white-hot core to an orange edge, as a fireball does.

{ "shape": "sphere", "center": [0, 1.2, 0], "radius": 1.2, "falloff": 0.9, "density": 1, "absorption": [0.2, 0.3, 0.4], "emissionRamp": { "kelvin": [1000, 3000], "exposure": 6 } }
Field Default Meaning
kelvin one of kelvin or stops [cool, hot], 300 to 30000. The blackbody temperatures at the low and high end of the source. The colour is the hue of a blackbody at that temperature (Planck's law against the CIE 1931 colour matching functions; 1000 K to 3000 K stays within 2 percent of full scale of Mitchell Charity's blackbody table, tests/local-volume-ramp.test.js), and the brightness falls with (kelvin / hot)^4
stops one of kelvin or stops 2 to 8 colours [red, green, blue] (each 0 to 100) spaced evenly from the low end of the source to the high end
source density density for every shape. A grid volume can also read its temperature or flame channel
range [0, 1] [low, high], the source values that map to the two ends of the ramp; values outside are clamped
exposure 1 Multiplies the ramp colours, 0 to 1000. 0 gives no light

At each step the light added per unit length is ramp(t) * exposure * emissionStrength * t, where t is the source value mapped by range and clamped to 0 to 1: it fades to nothing where the source is zero, so a cold cell gives none. It adds to the constant emission; the two can be used together. The ramp is baked to 8 colours for a blackbody (the stops themselves otherwise) and read by linear blending between them, the same bake in the rasterizer and the CPU path tracer, which agree to a relative RMSE of 0.009 on a graded sphere (64 px rasterizer on SwiftShader against the 32 px, 8 sample tracer). A volume without emissionRamp draws exactly as before. The grid volume's blackbodyIntensity (above) lights the temperature channel with the physical brightness of Blender's Principled Volume and the same Planck hue, while emissionRamp with source: "temperature" and kelvin maps the channel through a chosen temperature range. The ramp does not light the scene and does not feed bloom. The WebGPU path tracer draws it too (#1785): the baked stops ride in a block after the volume table and the grid block of the same storage buffer, a grid with a ramp also packs its temperature channel, and a box or sphere reads the ramp at its profile, as the CPU tracer does. Backend native (Cook) does not.

Mesh volumes

shape: "mesh" takes its place and size from a part, so smoke can fill a room or a modelled shape without writing its numbers twice.

{ "environment": { "localVolumes": [ { "shape": "mesh", "part": "hall", "fit": "mesh", "density": 1.5, "falloff": 0 } ] } }
  • fit: "bounds" (the default) uses the part's bounding box in its own frame, carried through its matrix: an oriented box, tight for a rotated or scaled part. It draws in the rasterizer and the CPU path tracer, and falloff fades its edges as for a box.
  • fit: "mesh" uses the closed mesh itself. The CPU path tracer walks the ray from crossing to crossing, so an L-shaped room or two separate shells are filled exactly, and a ray that leaves the mesh and returns crosses both pieces. The mesh has no distance field, so falloff is ignored (the density is the same everywhere inside), and so is noiseAmount.
  • The rasterizer draws the closed mesh in a mesh pass before the post pass: each fit: "mesh" part is drawn without culling into a float buffer, adding the distance of every back face and subtracting that of every front face along each pixel's ray, each clamped to the first opaque surface. That sum is the length of the ray inside the mesh, exact for any number of shells and any shape, so there is no shell limit; the post shader then integrates the volume over that length in closed form (the light behind is dimmed by exp(-density * absorption * length), the emission adds emission * (1 - exp(-k * length)) / k). steps has no effect on a mesh fit, because nothing is stepped. A mesh volume is still composited whole, nearest entry first. On the L-room test (tests/local-volume-mesh-raster.test.js, density 1) the rasterizer's transmittance stays within 0.03 of the CPU tracer's (the test tolerance; measured differences were 0.0014 or less) and the notch of the L is exactly clear.
  • The rasterizer needs the mesh to be closed and every face to wind the same way (either outward or inward; it detects which): an open mesh throws environment.localVolumes[n].part "x" is not a closed mesh (k open edges), and faces wound against each other throw ... has faces wound against each other (k edges). It needs EXT_float_blend and a buffer as wide as the canvas and as tall as the canvas times the number of fit: "mesh" volumes (RG32F, 8 bytes per pixel each; at 1920 x 1080 that is 16.6 MB per volume), and throws with the limit when the device cannot make it. Geometry nearer than the camera's near plane is clipped, so a ray loses the stretch between the eye and the near plane; the automatic near plane counts only visible parts, so a hidden volume part that sits nearer the camera than everything visible needs an explicit camera near. A mesh that crosses the far plane keeps the stretch up to it (the missing back face is made up from the surface or far distance), so smoke fades at the far plane like any other volume. A scene with no fit: "mesh" volume allocates nothing and draws nothing extra.
  • A part that is visible: false is not drawn by the rasterizer and is left out of the traced geometry in every scene, with or without local volumes, so a hidden part casts no shadow and is not a wall in the path tracers (#1793, #1806). A volume that names a hidden part still takes its shape from it.
  • The part must be rigid (not skinned) and have volume. A mesh with open edges has no inside: fit: "mesh" throws an error with the part name and the number of open edges. A part that names nothing throws environment.localVolumes[n].part "x" names no part in the scene with the part names.
  • The mesh walk follows at most 64 surface crossings per ray (32 segments inside), so the cost stays bounded; the steps of the volume are shared between its segments by length.

Reference render and frame time

node bench/reference/local-volumes.mjs gpu draws a smoky room (a haze box with noise and a glowing noisy puff, bench/reference/images/local-volumes.png) and the same room without volumes (local-volumes-plain.png), and times both: 960 x 540, 4x MSAA, median of 200 frames with readback, three rounds with the order alternating. On the RTX 3060 shared with other jobs (2026-11-10) the room without volumes took 1.34, 1.25 and 1.07 ms, and with the two volumes 2.13, 2.11 and 1.54 ms, so the pair costs about 0.5 to 0.9 ms at this size (noisy; treat it as a range).

Grid volumes

A simulated explosion, fire or smoke plume is a grid of numbers, not a noise box. shape: "grid" fills a box with a 3D texture of density and, optionally, temperature and flame, so a frame exported from EmberGen, Houdini or Blender draws in the rasterizer and the CPU path tracer. node bench/reference/volume-grid.mjs <grid file> <png> draws one converted frame of the CC0 "Ground Explosion" by JangaFX over a sandy ground and prints the frame time.

{ "environment": { "localVolumes": [
  { "shape": "grid", "grid": "blast.67vg", "center": [0, 2.2, 0], "density": 4, "emission": [1, 0.45, 0.12], "emissionStrength": 14, "temperatureScale": 1000, "blackbodyIntensity": 0.3 }
] } }
Field Default Meaning
grid required The name of a grid: registerVolumeGrid(name, bytes) registers one in a page or a script, and in the MCP server a name ending in .67vg loads from the working directory (or JS67_GRID_DIRECTORY), never from a path
frames none Instead of grid: a list of up to 512 grid names, one per animation frame (below)
fps, loop 24, true With frames: frames per second (0.01 to 240), and whether the sequence wraps (true) or holds its last frame (false)
center, size required, the grid file's own size The box the grid fills. A grid never extends past it
density 1 Density scale, 0 to 100: extinction per unit length is the grid's density times this times absorption (Blender's Density)
absorption [1, 1, 1] The colour the smoke absorbs (Blender's Absorption Color, the same field as other volumes)
emission, emissionStrength [0, 0, 0], 1 Light given off per unit length times the flame channel (the density when the grid has no flame channel)
temperatureScale 1 Kelvin per unit of the temperature channel
flameTemperature none { ignition, maximum } in temperature units (Blender's fire: { ignition: 1.5, maximum: 3 }, 1500 K to 3000 K at temperatureScale 1000). The blackbody then comes from the flame channel, not the temperature channel: flame > 0.01 ? ignition + flame * (maximum - ignition) : 0, the remap Blender applies to a fire simulation (rna_fluid.cc). The light is added per step length and does not depend on the smoke density, so thin smoke with a little flame glows orange at its edge, as in Cycles. A grid without a flame channel gives no blackbody under it. The native path tracer gets the remapped flame as its temperature channel
blackbodyIntensity 0 0 to 1. Adds the blackbody light of the temperature, times emissionStrength. 0 ignores the temperature channel (Blender's Blackbody Intensity). The light is physical, as in Blender: Stefan-Boltzmann 5.670373e-8 * 1e-6 / pi * kelvin^4 (0.09 at 1500 K, 1.5 at 3000 K) in a colour of luminance 1 whose hue is the Planck curve (the same table as emissionRamp). Before 0.21.0 it was a Tanner Helland fit times (kelvin / 1500)^4, 3 to 4 times too bright against Cycles, so a scene tuned to that needs a smaller emissionStrength or blackbodyIntensity
anisotropy 0 -0.9 to 0.9. The Henyey-Greenstein asymmetry of the key light's scatter when scatter is above 0
steps 64 4 to 128 samples through the box
scatter, blur as other volumes The same lit-volume and blur behaviour. falloff, noiseAmount and noiseScale do not apply: the grid has its own detail

One grid volume per scene for now. The rasterizer samples two RGBA16F 3D textures, each padded with one empty voxel on every face: r density, g temperature, b flame, and the blackbody radiance of each voxel's temperature, baked once on the CPU when the grid or temperatureScale changes. The CPU path tracer reads the same half floats and the same bake, so the two agree to filtering. All of them are trilinear. The interpolation runs after the blackbody, so the glow is the linear mix of per-voxel emission that Cycles' single linear tap averages to; interpolating the temperature first and raising it to the fourth power afterwards puts a crease at every voxel face and shows as a bright line on a fire only a few voxels wide (#1752). blackbodyIntensity and emissionStrength stay uniforms. The temperature texture stays for an emissionRamp whose source is the temperature. Both read 0 beyond the faces and ramp to it across the outer half voxel, as an OpenVDB grid and Cycles do, so a grid fills its box less its outer half voxel. The bake adds one more 3D texture of the grid's size and costs about 0.3 ms per 480 x 270 frame on a 3060 and nothing measurable per 1080p frame, and doubles the grid texture memory (the radiance is clamped to the half float limit of 65504, which a fire never reaches: sigma * T^4 / pi passes it near 35,000 K); the CPU path tracer is a little faster on a grid frame, because it no longer evaluates the blackbody table at every step. Without a grid volume, local volumes draw exactly as before.

Grid volumes in Cook. backend: "native" path traces a grid volume (#1789): src/path-tracer-native-volumes.js maps the bound volume, the frame at the render time, to Cook's gridVolumes entry (center, size, density, absorption, scatter as [scatter, scatter, scatter], anisotropy, emission, emissionStrength, temperatureScale, blackbodyIntensity * emissionStrength; density, temperature and flame channels, velocity skipped) and appends the packed grids to the texel pool of the FORMAT-v2 input, the same words Cook's buildNativeInputV2 writes for scene.gridVolumes. The terms are Principled Volume's, as in the Cycles reference below, so Cook and Cycles agree without a fudge factor. Not in Cook: emissionRamp (throws), a motion blur from the velocity channel (environment.volumeShutter is ignored and the job report says so), box, sphere and mesh volumes (throw), and castShadow and lightsScene (no effect, the kernel shades the grid with the real lights). A scene without local volumes exports the same tables as before.

Animated grids. frames replaces grid with a list of grid files, one per frame, played at fps: { "shape": "grid", "frames": ["blast_0000.67vg", "blast_0001.67vg"], "fps": 24 }. The frame is floor(time * fps), wrapped over the list when loop is true (the default) and held on the last frame when it is false; a time before 0 reads the first frame. The time is the scene's motion time (environment.volumeTime, which scene.environment fills in after sampleMotion), or the frame's time in a bare CrucibleRenderer, so the preview, the film player, the render jobs and the CPU path tracer all draw the frame a given time selects, and the same time gives the same pixels (a test traces it twice). Every frame has one resolution and one size, and the whole list has one budget: 256 MiB of half floats (VOLUME_GRID_SEQUENCE_MAX_BYTES), checked as each frame loads. That is 64 frames of 128 cubed with one channel, 32 with density and flame, or 8 frames of 256 cubed with one channel; a sequence over it throws an error that names the byte count, the frame it crossed at and the limit. The rasterizer keeps one 3D texture and overwrites it with texSubImage3D when the selected frame changes, so a frame costs one upload only on the draw where the frame changes. Every frame also has the same channels, which the loader checks. A scene whose only animation is a grid sequence still has a clock: sampleMotion and a film timeline accept it. In the MCP server, every name ending in .67vg loads from the grid folder as for a still grid.

In the MCP server. The preview page has no file access, so scene_create, scene_apply and the render jobs (scene_render_submit) read the grid files a recipe or an edit names on the server and pass their bytes to the page by name, the way catalog images reach a map sequence. A volume's grid or each of its frames must be a plain file name ending in .67vg in the grid folder (the server's working directory, or the folder JS67_GRID_DIRECTORY names); a path, a URL or a name with no such file is refused with an error that says what to pass. The limits hold on the server before any byte is sent: 64 MiB per grid file and 64 MiB in all for one call, because the grid bytes cross to the page in one browser message together with any catalog assets the call places (a sequence of frames over that is refused with advice to use fewer frames or a lower --max-resolution; a sequence loaded in code, outside the MCP server, keeps its 256 MiB budget), then the page checks the decoded grids again. A job with motion.start seeks a grid sequence like a map sequence, so scene_render_submit accepts motion for a recipe whose only animation is a grid sequence, and the frame drawn is the one floor(time * fps) selects. Every create, apply and job sends the files again, so a file you changed shows on the next one.

uv run --no-project scripts/vdb-to-grid.py "sim/smoke_*.vdb" blast --sequence --max-resolution 128 converts a numbered VDB sequence in one run: the files are sorted by their numbers (smoke_2 before smoke_10), every frame is put on the union of all the frames' boxes so the resolution is the same, and the files blast_0000.67vg, blast_0001.67vg and so on are written, each with every channel any frame has (zero where a frame has none, so the shader never reads the density as flame there). A frame with an empty density grid is written empty with a warning that names the file. The byte budget is checked after the first pass and before anything is written. The script prints the frames list to paste into the volume.

Playback cost of a real sequence. node bench/reference/volume-grid-vdb-sequence.mjs <grid folder> <output folder> [--width 1920] [--height 1080] [--clip] plays a converted VDB sequence on a round diorama (a slab on a plinth, a high oblique camera, no sky) and prints milliseconds per frame over the whole sequence, with the frame changing on every draw (one upload each) and with a held frame. Measured on the CC0 "Ground Explosion" by JangaFX (EmberGen), 90 frames converted with --max-resolution 96 to 82 x 93 x 96 voxels with density and flame, on an RTX 3060 shared with other jobs, 1920 x 1080, five runs: the median of a changing frame was 20.5 to 29.1 ms (30 fps is 33.3 ms), its 95th percentile 30 to 44 ms and its worst frame 40 to 58 ms, and a held frame took a median of 6.8 to 11.0 ms. Before #1045 stopped rebuilding the half float table for every frame, walking the fire light's emission with an array per cell and uploading a zero emission texture for a grid with no temperature, the same sequence took a median of 180 ms a frame at 960 x 540. The 95th percentile is above 33 ms, so a frame now and then misses 30 fps. The padded texel buffer is now kept between frames of one resolution instead of allocated for each: on a 72 frame sequence of 0.4 m grids (the same bench, three runs) a changing frame went from a median of 11.1 to 17.7 ms (95th percentile 17 to 27 ms) to 9.2 to 11.7 ms (11.5 to 13.5 ms).

Grid file. "67VG", a uint32 version (1), a uint32 header length, a JSON header { "resolution": [x, y, z], "channels": ["density", "flame"], "size": [x, y, z] } padded to 4 bytes, then each channel as half floats, x fastest, then y, then z, y up. Each axis is 1 to 256 and the data at most 64 MiB; anything past that is refused with the limit and the --max-resolution to use.

From a VDB. uv run --no-project scripts/vdb-to-grid.py frame.vdb blast.67vg --max-resolution 128 reads OpenVDB float grids by their usual names (density; temperature or heat; flame, flames or fire), turns a z-up file to y up, box-averages down to the resolution and writes the file. --map flame=burn reads a channel from another grid name and --up y leaves the axes alone. The reader is in the script (OpenVDB file version 222 or later, float grids, none, zip or Blosc compression; Blosc, openvdb's default, needs uv run --no-project --with blosc scripts/vdb-to-grid.py ..., and without it the error prints that command), so it needs numpy only: no OpenVDB wheel exists for Windows, and pyopenvdb on PyPI is a 2020 Python 3.7 build.

Bytes per frame, two bytes per voxel per channel (measured on the "Ground Explosion" frames, which are 144 x 88 x 136 voxels at most):

Resolution density density + flame density + temperature + flame
128 x 128 x 128 4.2 MB 8.4 MB 12.6 MB
256 x 256 x 256 33.6 MB 67.1 MB (the limit is 64 MiB, so 256 cubed fits two channels) over the limit

The 3D texture on the GPU is RGBA16F, 8 bytes per voxel whatever the channels: 16.8 MB at 128 cubed, 134 MB at 256 cubed.

Baking a gas sim

src/gas-sim.js bakes an explosion from a real grid simulation instead of a noise shape, into the grid files above: no dependency, plain JS, the same options and seed give the same bytes. It is the solver of Stam's "Stable Fluids" (semi-Lagrangian advection, pressure projection), with the smoke buoyancy and vorticity confinement of Fedkiw, Stam and Jensen, MacCormack advection with its limiter (Selle et al.), and a fuel that burns where it is hot into flame, heat and smoke.

It is not a package export or an MCP tool yet, so it runs from a checkout of the repository, where src/gas-sim.js exports bakeGasSimToGrids and GAS_SIM_TEMPERATURE_UNIT:

const frames = bakeGasSimToGrids({ resolution: 64, frames: 72, fps: 24, seed: 3 }, 'blast');
// { shape: 'grid', frames, fps: 24, center: [0, 4, 0], size: [8, 8, 8], temperatureScale: GAS_SIM_TEMPERATURE_UNIT, blackbodyIntensity: 0.3 }

bakeGasSim(options) returns { frames: [{ density, temperature, flame }], resolution, size, fps } as Float32Arrays; bakeGasSimToGrids(options, namePrefix) encodes and registers each frame as <namePrefix>_0000.67vg and returns the names for frames. The defaults are a 3 s ground blast: a 0.9 m burst on the floor of a 64 cubed grid of 0.125 m cells (an 8 m box), 72 frames at 24 fps, 2 solver steps per frame. The floor is a wall, the sides and the top are open, y is up.

Option Range Default
resolution one integer or [x, y, z], each 8 to 96 64
frames, fps, substeps 1 to 240, 1 to 120, 1 to 8 72, 24, 2
seed integer 0 to 4294967295; shapes the burst 1
maxSeconds 0.1 to 3600; the bake throws when the wall clock passes it 120
cellSize metres, 0.005 to 2 0.125
advection maccormack or semi-lagrangian maccormack
pressureIterations, vorticity 4 to 100 red-black sweeps, confinement 0 to 40 20, 8
burstPosition, burstRadius, burstFuel, burstSmoke, burstTemperature, burstSpeed, burstSeconds, turbulence the source: metres from the corner, metres, fuel and smoke at the core, kelvin, m/s, seconds, 0 to 1 middle of the floor, 0.9, 1, 0.8, 2400, 6, 0.2, 0.35
temperatureLift, densityWeight, ambientTemperature, cooling, dissipation, flameDecay, burnRate, ignitionTemperature, heatRelease, smokeYield the physics, each bounded; see NUMBER_OPTIONS in the source tuned for a ground blast
detail noise upres of the smoke density in every baked frame, 0 to 1: the density is multiplied by 1 + 4 * detail * noise (two octaves of value noise about 5 and 2.5 cells wide, rising with the frame), so thin smoke breaks into puffs and gaps smaller than the grid resolves and empty cells stay empty. The solver never reads it back, and 0 leaves the bake byte for byte as it was. Flame, temperature and velocity are not touched, and add-explosion does not use it yet 0

Every option is checked, and an error names the field, its range and what to pass. The temperature channel holds the kelvin above the ambient air in units of GAS_SIM_TEMPERATURE_UNIT (1000 K): pass it as temperatureScale, and cold air reads 0 so the blackbody adds no glow there. flame is 0 to 1 per cell. A bake of 64 cubed with three channels is 1.5 MiB a frame, so 72 frames are 108 MiB of the 256 MiB sequence limit; bakeGasSim and bakeGasSimToGrids refuse a bake that would pass it before it starts. Smoke and fuel are conserved: each solver step scales the advected field back to its total before the step, less what the step carries out through the open sides and the top, so with no source and no dissipation the smoke mass stays within 2% over 72 frames at 32 cubed, and dissipation lowers it by exactly its own factor. Burning adds smoke and dissipation removes it as separate terms. Heat and flame are not mass and are advected without that correction.

Motion blur of a grid volume

Object motion blur moves rigid parts by their transform, which does nothing for gas that moves inside a still box. A grid that carries the gas velocity blurs along it instead, and a fireball or smoke column smears along its expansion the way a Cycles render with motion blur does. It is off unless you ask twice: bake with velocity: true (bakeGasSim and bakeGasSimToGrids then add velocityX, velocityY and velocityZ to every frame, in metres per second) and set the scene's effects.motionBlur.shutter above 0, in seconds. A grid without those channels, and a scene with a shutter of 0, draw exactly as before: the blur is a separate shader variant, so a frame with the shutter off compiles the same grid march source as without the feature, binds no velocity texture and draws the same pixels (tests/volume-grid-motion-blur.test.js compares the generated source); old .67vg files load as they did. The three channels go together (a file with only some is refused) and cost three more half floats a voxel: a 64 cubed frame is 3 MiB with them, so a 72 frame sequence is 216 MiB of the 256 MiB limit.

const frames = bakeGasSimToGrids({ resolution: 64, frames: 72, fps: 24, velocity: true }, 'blast');
// environment.localVolumes: [{ shape: 'grid', frames, fps: 24, temperatureScale: GAS_SIM_TEMPERATURE_UNIT, ... }], effects: { motionBlur: { shutter: 0.04 } }

The frame's grid is the gas as the shutter opens, and the gas moves on by its velocity. Each march step reads the grid back along the velocity at its own time in the shutter, so a point sees the gas that is on its way in over the shutter. One time per step, spread over the ray by the golden ratio, means the blur costs one extra velocity tap per step and no extra density taps; a ray of 96 steps covers the shutter in 96 times. The CPU path tracer draws the same blur from environment.volumeShutter (the shutter in seconds; the preview and render jobs set it from the scene's effects.motionBlur.shutter), at each sample's own jitter. The shadow a grid casts on surfaces (castShadow) blurs the same way: each of its 16 taps reads the grid at its own time in the shutter, spread by the golden ratio from the pixel's jitter, so a blurred blast casts a smeared shadow and not a sharp one. The tap noise shows as a fine dither at a long shutter (0.25 s); at one frame the change is below a pixel. The sun's depth through the gas, which lights the gas itself, still reads the sharp grid. A frame with the shutter off compiles the shadow taps it always had (a test pins the source, and the three #1735 stills render pixel for pixel the same as before). The WebGPU path tracer does not draw grid volumes at all (it throws and names backend "cpu", above), so there is nothing there to blur; backend "cpu" draws the blur.

Two cheaper ideas were reasoned through and not built: blending the previous and the current grid frame cross-fades two sharp copies, which leaves a ghost, not a smear, once the move passes a feature's width, and it needs two frames resident; marching a few shutter-time offsets needs a grid read per offset (3 or 4 times the march). Reading the grid back along the velocity matches what Cycles does with a velocity grid: on the 64 cubed blast of #1735 with a shutter of one frame (1/24 s) the change it makes to the image correlates with Cycles' change at 0.96 on the early frame and 0.94 at the peak (measured, luminance change after a 7 pixel box blur, 32 samples of Cycles), and it adds one tap per step. scripts/cycles-volume-reference.py takes "motionBlur": { "shutter": 0.0417, "fps": 24 } and grid-to-vdb.py writes the three velocity grids Blender reads, so the two renders share a shutter. Measured there: Cycles moves the frame's gas on over the shutter whatever shutter position is set.

Cycles reference for grid volumes

To put a number on the gap between Glaze, Cook and a production renderer, the same grid is rendered in Blender Cycles with Principled Volume from one JSON spec (the spec format is at the top of scripts/cycles-volume-reference.py; Glaze and Cook renders of the same scene read the same fields). Three scripts, no dependency beyond Blender 5.x, whose Python ships openvdb:

blender -b --factory-startup --python scripts/grid-to-vdb.py -- tests/fixtures/explosion-32.67vg out/
blender -b --factory-startup --python scripts/cycles-volume-reference.py -- spec.json out/frame
node scripts/compare-volume-render.mjs out/frame.png candidate.png

grid-to-vdb.py writes density, temperature and flame FloatGrids with the voxel size that makes the world size equal the header size (or --size), the box centred on the VDB origin and each voxel centred half a voxel in, as sampleVolumeGrid reads texels; Crucible (x, y, z) becomes Blender (x, -z, y). The render script moves the box to volume.center, scales it to volume.size, builds the camera from eye, target, up and a vertical fov, adds the sun (direction points toward the sun, strength * color is the irradiance) and an optional floor, renders with no denoising, and writes .exr (linear), .png (Standard view transform) and a .json sidecar with the spec, Blender version, samples, device and render seconds. Principled Volume's density is the grid density times density, its absorption colour is (1 - absorption)^2 (measured: extinction is density times 1 - sqrt(colour)), the flame channel drives Emission Strength (per unit length, not scaled by density, as in Crucible) and the temperature channel drives Blackbody Intensity. Cycles' blackbody is physical and normalised where Crucible's is Tanner Helland's fit with a (kelvin / 1500)^4 gain, so a grid with temperature will differ in brightness by design.

compare-volume-render.mjs reference.png candidate.png [--mask mask.png] [--threshold 0.05] prints JSON: RMSE and relative RMSE in linear light, and the mean absolute luminance difference inside the volume (a mask image, or the reference pixels above the threshold) against outside it. It always exits 0.

Linear output addon. The shader code for linearOutput (below) is an addon, exported as ./addons/linear-output-shader: import '@codepawlhq/crucible/addons/linear-output-shader' before the first frame drawn with linearOutput: true, or render() throws and names that import. Nothing else loads it, so a renderer that never draws a linear frame does not carry it. The import has no functions to call: it only makes the linearOutput option available, so put it in the code that sets the option.

Linear output (#1749). The display frame holds ACES and the display encoding, clipped at 1, even in a float outputFramebuffer. A frame drawn with linearOutput: true (a render() field next to outputFramebuffer) writes the scene radiance as it stands after bloom, fog and local volumes, with no view transform, look, grade, vignette, grain, fade or explosion, and no clamp, so a glowing volume reads above 1. It needs a renderer made with hdr: true and a float outputFramebuffer from src/float-output.js; without them render() throws an error that says so. The option is a separate post program, so a frame without it draws the program and the pixels it had before (tests/linear-output.test.js draws a glowing grid volume both ways: the linear peak is 24.4, and the ACES curve and display encoding of the linear frame match the display frame to 0.0003). Write readFloatPixels output (rows bottom to top) as raw little-endian float32 RGBA to a file ending in .f32 and pass it as the candidate: compare-volume-render.mjs reads it as linear radiance, flips it to picture order and compares it without decoding sRGB or clamping, against a reference PNG or one decoded the same way. It is not wired into the render job tools.

npm test runs tests/grid-to-vdb.test.js when Blender is installed (BLENDER_PATH, blender on the PATH or the default Windows install) and skips it otherwise. Blender's Python writes Blosc VDBs, which vdb-to-grid.py reads when run with --with blosc; the round trip test reads the VDB back with Blender's own openvdb.

Not covered yet

The noise is localVolumeNoise in src/fog-shader.js and src/local-volume-noise.js: trilinear value noise on a hash made of multiplies, adds and fract only, which rounded the same way on SwiftShader, where it was measured; it is unchecked on hardware GPUs. The fog's cloudNoise hashes with sin, whose error grows with its argument: on SwiftShader its lattice values differed from a 32-bit JavaScript port by up to 0.3, so the two renderers drew different clouds. The JavaScript port rounds every step to 32 bits. tests/local-volume-noise.test.js draws a noisy box (density 1.2, falloff 0.3, noiseAmount 0.9, noiseScale 3) in both renderers and compares the light let through in 8 by 8 regions: on SwiftShader the worst region differed by 0.003 and the mean of the whole frame by 0.0008, and the test allows 0.01 and 0.005. The rasterizer starts each pixel's march at an interleaved gradient noise offset (localVolumeJitter; a sine hash left clumps of error that read as grain at 8 steps, measured: mid-frequency energy 1.06 with the hash against 0.42 with the gradient noise, 0.41 with no jitter at all, and no grain left at 16 steps or more; the dither that remained at 8 steps went away by raising the count to two samples per noise cell: high-pass grain in the core 3.47 to 1.47 against 1.40 in the clear frame, mid-band 0.418 to 0.404 against 0.352, at 1.4 to 2.4 ms per 960 x 540 frame on a shared GPU against 1.6 before) and the tracer with its sampler, so single pixels differ by a few percent. Volumes with noiseAmount drew with the fog's sine noise before this change, so their pattern moved; the mean density is unchanged. Lighting baked surfaces from a volume's emission is not planned (#809): the bake reports the limit instead.

Fire lights the set

A fireball is light, but a volume's emission only shows in the volume itself. With lightsScene: true the rasterizer adds one point light per volume before it writes the frame's lights: intensity is the emission integrated over the volume (emission * emissionStrength * volume for a box or sphere; the sum of the flame channel and, with blackbodyIntensity, the blackbody of the temperature channel, times each cell's volume, for a grid), colour is that sum's hue, and the position is the centre of the emission, so a flame that rises moves its light. The light has no shadow and no range window. A glowing volume also feeds bloom: when the frame has bloom and a volume emits, the rasterizer draws the local volumes over the frame before bloom extraction, so the glow spills past the volume. That costs one more full-frame pass for such a frame and nothing for any other. The CPU path tracer needs no light because it traces into the volume itself.