@driftengine/core 4.2.1 → 4.4.0

package/dist/render/driftLight/uniforms.d.ts

@@ -0,0 +1,28 @@
+/**
+ * What the lit shader is told about a DriftLight field this pass, decided once for both backends.
+ *
+ * **Decided here and bound there**, by the 2026-08-13 rule: each backend only uploads these numbers
+ * to the names `driftLight.ts` declares, so the two cannot come to disagree about when the field is
+ * on or what radius a pass uses. Off, which the shader reads as `light.x` of zero, until a field is
+ * whole; and during a probe bake the radius is zero, because the exact lights were chosen for the
+ * camera and a probe stands somewhere else: a probe sees every fixed light through the volume.
+ *
+ * **The radius is handed over measured from the eye**, because the shader measures from the
+ * `uCameraPos` it already has rather than spending a uniform on the choice's centre. A point within
+ * `r − |eye − centre|` of the eye is within `r` of the centre, so taking the offset off keeps every
+ * pixel the shader shades exactly inside the radius the selection promised. A mirror's camera, far
+ * from the centre, gets a smaller radius and more of the volume, which is the safe direction.
+ */
+import type { LightField } from './lightField.ts';
+export interface DriftLightUniforms {
+    /** How much of the summed light is in, the radius, the band, the scale. */
+    readonly light: Float32Array;
+    /** The first brick's first sample, and the metres between samples. */
+    readonly origin: Float32Array;
+}
+export declare function createDriftLightUniforms(): DriftLightUniforms;
+/**
+ * Fill `out` for `field`, or for no field, seen from `eye`; `probePass` while a probe's faces are
+ * being drawn.
+ */
+export declare function resolveDriftLight(field: LightField | null, probePass: boolean, eye: ArrayLike<number>, out: DriftLightUniforms): void;

package/dist/render/driftLight/uniforms.js

@@ -0,0 +1,41 @@
+/**
+ * What the lit shader is told about a DriftLight field this pass, decided once for both backends.
+ *
+ * **Decided here and bound there**, by the 2026-08-13 rule: each backend only uploads these numbers
+ * to the names `driftLight.ts` declares, so the two cannot come to disagree about when the field is
+ * on or what radius a pass uses. Off, which the shader reads as `light.x` of zero, until a field is
+ * whole; and during a probe bake the radius is zero, because the exact lights were chosen for the
+ * camera and a probe stands somewhere else: a probe sees every fixed light through the volume.
+ *
+ * **The radius is handed over measured from the eye**, because the shader measures from the
+ * `uCameraPos` it already has rather than spending a uniform on the choice's centre. A point within
+ * `r − |eye − centre|` of the eye is within `r` of the centre, so taking the offset off keeps every
+ * pixel the shader shades exactly inside the radius the selection promised. A mirror's camera, far
+ * from the centre, gets a smaller radius and more of the volume, which is the safe direction.
+ */
+export function createDriftLightUniforms() {
+    return {
+        light: new Float32Array(4),
+        origin: new Float32Array(4),
+    };
+}
+/**
+ * Fill `out` for `field`, or for no field, seen from `eye`; `probePass` while a probe's faces are
+ * being drawn.
+ */
+export function resolveDriftLight(field, probePass, eye, out) {
+    if (field === null || !field.ready || field.presence <= 0 || field.layout.count === 0) {
+        out.light.fill(0);
+        return;
+    }
+    const { layout } = field;
+    const offset = Math.hypot((eye[0] ?? 0) - field.centre[0], (eye[1] ?? 0) - field.centre[1], (eye[2] ?? 0) - field.centre[2]);
+    out.light[0] = field.presence;
+    out.light[1] = probePass ? 0 : Math.max(0, field.radius - offset);
+    out.light[2] = field.band;
+    out.light[3] = field.scale;
+    out.origin[0] = layout.origin[0];
+    out.origin[1] = layout.origin[1];
+    out.origin[2] = layout.origin[2];
+    out.origin[3] = layout.spacing;
+}

package/dist/render/driftLight/visibility.d.ts

@@ -0,0 +1,18 @@
+/**
+ * How much of a light a point sees, through a signed distance field: DriftLight's occlusion.
+ *
+ * **Sphere-traced, with a penumbra from the light's own size.** A spherical light of radius R seen
+ * from a distance L fills a cone that is R * t / L across at a distance t along the way, so a surface
+ * a clearance h from the ray covers the fraction of it that h falls short of that radius. The least
+ * such ratio along the ray is the visibility: 1 in open air, 0 behind a wall, and a soft ramp at an
+ * edge that widens with the light, which is what `AGENTS.md` asks of a light with a physical size.
+ *
+ * The trace stops before the light by its own radius, or 5 cm where that is smaller, so a candle's
+ * wax does not shadow the flame sitting on it. What it gives up is exactness at a grazing corner,
+ * where one ratio stands for an area the cone only partly crosses; what would make it wrong is a
+ * field coarser than the lights it shadows, which blurs every occluder smaller than a cell.
+ */
+/** A signed distance: metres to the nearest surface, negative inside. */
+export type DistanceAt = (x: number, y: number, z: number) => number;
+/** The visibility, 0 to 1, of a light of radius `sourceRadius` at `to` from the point `from`. */
+export declare function softVisibility(distance: DistanceAt, fx: number, fy: number, fz: number, tx: number, ty: number, tz: number, sourceRadius: number): number;

package/dist/render/driftLight/visibility.js

@@ -0,0 +1,47 @@
+/**
+ * How much of a light a point sees, through a signed distance field: DriftLight's occlusion.
+ *
+ * **Sphere-traced, with a penumbra from the light's own size.** A spherical light of radius R seen
+ * from a distance L fills a cone that is R * t / L across at a distance t along the way, so a surface
+ * a clearance h from the ray covers the fraction of it that h falls short of that radius. The least
+ * such ratio along the ray is the visibility: 1 in open air, 0 behind a wall, and a soft ramp at an
+ * edge that widens with the light, which is what `AGENTS.md` asks of a light with a physical size.
+ *
+ * The trace stops before the light by its own radius, or 5 cm where that is smaller, so a candle's
+ * wax does not shadow the flame sitting on it. What it gives up is exactness at a grazing corner,
+ * where one ratio stands for an area the cone only partly crosses; what would make it wrong is a
+ * field coarser than the lights it shadows, which blurs every occluder smaller than a cell.
+ */
+/** Steps before the trace gives up and answers what it has; a light a metre off needs a dozen. */
+const MAX_STEPS = 64;
+/** The least a step advances, so a ray grazing a surface still reaches the light. */
+const MIN_STEP_M = 0.01;
+/** Where the trace starts, clear of the surface the point may be lying on. */
+const START_M = 0.02;
+/** The visibility, 0 to 1, of a light of radius `sourceRadius` at `to` from the point `from`. */
+export function softVisibility(distance, fx, fy, fz, tx, ty, tz, sourceRadius) {
+    const dx = tx - fx;
+    const dy = ty - fy;
+    const dz = tz - fz;
+    const length = Math.hypot(dx, dy, dz);
+    if (length < 1e-6)
+        return 1;
+    const ux = dx / length;
+    const uy = dy / length;
+    const uz = dz / length;
+    const radius = Math.max(sourceRadius, 1e-3);
+    const end = length - Math.max(radius, 0.05);
+    let seen = 1;
+    let t = START_M;
+    for (let step = 0; step < MAX_STEPS && t < end; step++) {
+        const h = distance(fx + ux * t, fy + uy * t, fz + uz * t);
+        if (h <= 0)
+            return 0;
+        const cone = (radius * t) / length;
+        seen = Math.min(seen, h / cone);
+        if (seen <= 0)
+            return 0;
+        t += Math.max(h, MIN_STEP_M);
+    }
+    return Math.min(1, seen);
+}

package/dist/render/emptyTexture.d.ts

@@ -58,3 +58,9 @@ export declare function createEmptyTexture2DArray(gl: WebGL2RenderingContext): W
  * complete the other five are.
  */
 export declare function createEmptyTextureCube(gl: WebGL2RenderingContext): WebGLTexture;
+/**
+ * The same for DriftLight's two volumes while a scene has no field: one texel of an unsigned
+ * integer, reading "no brick here", or of zero light. GLSL ES gives a 3D sampler no default and a
+ * lookup through an unbound one is the undefined read this file exists to prevent.
+ */
+export declare function createEmptyTexture3D(gl: WebGL2RenderingContext, integer: boolean): WebGLTexture;

package/dist/render/emptyTexture.js

@@ -101,3 +101,22 @@ export function createEmptyTextureCube(gl) {
     gl.bindTexture(gl.TEXTURE_CUBE_MAP, null);
     return texture;
 }
+/**
+ * The same for DriftLight's two volumes while a scene has no field: one texel of an unsigned
+ * integer, reading "no brick here", or of zero light. GLSL ES gives a 3D sampler no default and a
+ * lookup through an unbound one is the undefined read this file exists to prevent.
+ */
+export function createEmptyTexture3D(gl, integer) {
+    const texture = allocate(gl, 'emptyTexture3D');
+    gl.bindTexture(gl.TEXTURE_3D, texture);
+    if (integer) {
+        gl.texImage3D(gl.TEXTURE_3D, 0, gl.R32UI, 1, 1, 1, 0, gl.RED_INTEGER, gl.UNSIGNED_INT, new Uint32Array(1));
+    }
+    else {
+        gl.texImage3D(gl.TEXTURE_3D, 0, gl.RGBA8, 1, 1, 1, 0, gl.RGBA, gl.UNSIGNED_BYTE, new Uint8Array(4));
+    }
+    gl.texParameteri(gl.TEXTURE_3D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_3D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+    gl.bindTexture(gl.TEXTURE_3D, null);
+    return texture;
+}

package/dist/render/exposurePass.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Eye adaptation on WebGL2: meter the finished scene, and follow it with a held brightness the
+ * composite reads. See `shaders/exposure.ts` for the design; this owns the targets and the draws.
+ *
+ * **Two one-texel targets that swap roles each frame**, because the adaptation reads what it held
+ * and a texture cannot be read and written in one draw. The composite is handed whichever was
+ * written last. `R16F`, because the held value is in stops and eight bits of a range twenty stops
+ * wide is an exposure that steps visibly as it moves.
+ *
+ * **And local exposure's grid, when that is asked for**: `RG16F`, a sum and a count per tile per
+ * band, filtered linearly because the composite reads it between tiles. See `localExposure.ts`.
+ */
+export declare class ExposurePass {
+    private readonly gl;
+    private meter;
+    private meterFramebuffer;
+    private localGrid;
+    private localFramebuffer;
+    private readonly held;
+    private readonly heldFramebuffers;
+    /** Which of the two held texels the next adaptation writes. */
+    private writing;
+    /** Whether anything is held yet: the first frame, and the first after a cut, snaps. */
+    private holding;
+    private allocated;
+    /** Set once if a half-float target will not complete; the pass is then off and says so once. */
+    private unavailable;
+    private readonly meterProgram;
+    private readonly meterUniforms;
+    private readonly adaptProgram;
+    private readonly adaptUniforms;
+    private readonly localProgram;
+    private readonly localUniforms;
+    private readonly vao;
+    constructor(gl: WebGL2RenderingContext);
+    /** Forget what is held, so the next frame meters afresh rather than easing from another shot. */
+    cut(): void;
+    private ensure;
+    /**
+     * Meter `scene` and move the held brightness toward it by `dtSec` of adaptation, and with `local`
+     * draw local exposure's grid too. Returns the texel the composite reads, or null where this pass
+     * could not run, which the caller reads as off.
+     */
+    run(scene: WebGLTexture, dtSec: number, local?: boolean): WebGLTexture | null;
+    /** Local exposure's grid as the last `run` drew it, or null before one has. */
+    get localTexture(): WebGLTexture | null;
+    dispose(): void;
+}

package/dist/render/exposurePass.js

@@ -0,0 +1,172 @@
+import { EXPOSURE_ADAPT_FRAG, EXPOSURE_METER_FRAG, METER_GRID, adaptBlend, } from './shaders/exposure.js';
+import { EXPOSURE_LOCAL_FRAG, LOCAL_GRID_WIDTH } from './shaders/localExposure.js';
+import { FULLSCREEN_VERT } from './shaders/fullscreen.js';
+import { compileProgram, uniformLocations } from './shader.js';
+/**
+ * Eye adaptation on WebGL2: meter the finished scene, and follow it with a held brightness the
+ * composite reads. See `shaders/exposure.ts` for the design; this owns the targets and the draws.
+ *
+ * **Two one-texel targets that swap roles each frame**, because the adaptation reads what it held
+ * and a texture cannot be read and written in one draw. The composite is handed whichever was
+ * written last. `R16F`, because the held value is in stops and eight bits of a range twenty stops
+ * wide is an exposure that steps visibly as it moves.
+ *
+ * **And local exposure's grid, when that is asked for**: `RG16F`, a sum and a count per tile per
+ * band, filtered linearly because the composite reads it between tiles. See `localExposure.ts`.
+ */
+export class ExposurePass {
+    gl;
+    meter = null;
+    meterFramebuffer = null;
+    localGrid = null;
+    localFramebuffer = null;
+    held = [null, null];
+    heldFramebuffers = [null, null];
+    /** Which of the two held texels the next adaptation writes. */
+    writing = 0;
+    /** Whether anything is held yet: the first frame, and the first after a cut, snaps. */
+    holding = false;
+    allocated = false;
+    /** Set once if a half-float target will not complete; the pass is then off and says so once. */
+    unavailable = false;
+    meterProgram;
+    meterUniforms;
+    adaptProgram;
+    adaptUniforms;
+    localProgram;
+    localUniforms;
+    vao;
+    constructor(gl) {
+        this.gl = gl;
+        this.meterProgram = compileProgram(gl, FULLSCREEN_VERT, EXPOSURE_METER_FRAG, 'exposureMeter');
+        this.meterUniforms = uniformLocations(gl, this.meterProgram, 'exposureMeter');
+        this.adaptProgram = compileProgram(gl, FULLSCREEN_VERT, EXPOSURE_ADAPT_FRAG, 'exposureAdapt');
+        this.adaptUniforms = uniformLocations(gl, this.adaptProgram, 'exposureAdapt');
+        this.localProgram = compileProgram(gl, FULLSCREEN_VERT, EXPOSURE_LOCAL_FRAG, 'exposureLocal');
+        this.localUniforms = uniformLocations(gl, this.localProgram, 'exposureLocal');
+        const vao = gl.createVertexArray();
+        if (vao === null)
+            throw new Error('ExposurePass: createVertexArray failed');
+        this.vao = vao;
+    }
+    /** Forget what is held, so the next frame meters afresh rather than easing from another shot. */
+    cut() {
+        this.holding = false;
+    }
+    ensure() {
+        if (this.unavailable)
+            return false;
+        if (this.allocated)
+            return true;
+        const { gl } = this;
+        const target = (size, height = size, pair = false) => {
+            const texture = gl.createTexture();
+            gl.bindTexture(gl.TEXTURE_2D, texture);
+            if (pair)
+                gl.texImage2D(gl.TEXTURE_2D, 0, gl.RG16F, size, height, 0, gl.RG, gl.HALF_FLOAT, null);
+            else
+                gl.texImage2D(gl.TEXTURE_2D, 0, gl.R16F, size, height, 0, gl.RED, gl.HALF_FLOAT, null);
+            const filter = pair ? gl.LINEAR : gl.NEAREST;
+            gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, filter);
+            gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, filter);
+            gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+            gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+            const framebuffer = gl.createFramebuffer();
+            gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
+            gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, texture, 0);
+            const ok = gl.checkFramebufferStatus(gl.FRAMEBUFFER) === gl.FRAMEBUFFER_COMPLETE;
+            return { texture, framebuffer, ok };
+        };
+        const meter = target(METER_GRID);
+        const first = target(1);
+        const second = target(1);
+        const local = target(LOCAL_GRID_WIDTH, METER_GRID, true);
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        gl.bindTexture(gl.TEXTURE_2D, null);
+        this.meter = meter.texture;
+        this.meterFramebuffer = meter.framebuffer;
+        this.held[0] = first.texture;
+        this.held[1] = second.texture;
+        this.heldFramebuffers[0] = first.framebuffer;
+        this.heldFramebuffers[1] = second.framebuffer;
+        this.localGrid = local.texture;
+        this.localFramebuffer = local.framebuffer;
+        this.allocated = true;
+        if (!meter.ok || !first.ok || !second.ok || !local.ok) {
+            this.unavailable = true;
+            console.warn('ExposurePass: this driver will not render to a half-float target, so eye adaptation is ' +
+                'off and the exposure is the one set. The frame itself is unaffected.');
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Meter `scene` and move the held brightness toward it by `dtSec` of adaptation, and with `local`
+     * draw local exposure's grid too. Returns the texel the composite reads, or null where this pass
+     * could not run, which the caller reads as off.
+     */
+    run(scene, dtSec, local = false) {
+        if (!this.ensure())
+            return null;
+        const { gl } = this;
+        gl.disable(gl.DEPTH_TEST);
+        gl.disable(gl.BLEND);
+        gl.disable(gl.CULL_FACE);
+        gl.depthMask(false);
+        gl.bindVertexArray(this.vao);
+        gl.bindFramebuffer(gl.FRAMEBUFFER, this.meterFramebuffer);
+        gl.viewport(0, 0, METER_GRID, METER_GRID);
+        gl.useProgram(this.meterProgram);
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_2D, scene);
+        gl.uniform1i(this.meterUniforms['uScene'] ?? null, 0);
+        gl.drawArrays(gl.TRIANGLES, 0, 3);
+        if (local) {
+            gl.bindFramebuffer(gl.FRAMEBUFFER, this.localFramebuffer);
+            gl.viewport(0, 0, LOCAL_GRID_WIDTH, METER_GRID);
+            gl.useProgram(this.localProgram);
+            gl.uniform1i(this.localUniforms['uScene'] ?? null, 0);
+            gl.drawArrays(gl.TRIANGLES, 0, 3);
+        }
+        const into = this.writing;
+        const from = 1 - into;
+        gl.bindFramebuffer(gl.FRAMEBUFFER, this.heldFramebuffers[into] ?? null);
+        gl.viewport(0, 0, 1, 1);
+        gl.useProgram(this.adaptProgram);
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_2D, this.meter);
+        gl.uniform1i(this.adaptUniforms['uMeter'] ?? null, 0);
+        gl.activeTexture(gl.TEXTURE1);
+        gl.bindTexture(gl.TEXTURE_2D, this.held[from] ?? null);
+        gl.uniform1i(this.adaptUniforms['uHeld'] ?? null, 1);
+        gl.uniform1f(this.adaptUniforms['uBlend'] ?? null, adaptBlend(dtSec, !this.holding));
+        gl.drawArrays(gl.TRIANGLES, 0, 3);
+        this.holding = true;
+        this.writing = from;
+        gl.bindVertexArray(null);
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        return this.held[into] ?? null;
+    }
+    /** Local exposure's grid as the last `run` drew it, or null before one has. */
+    get localTexture() {
+        return this.localGrid;
+    }
+    dispose() {
+        const { gl } = this;
+        for (const framebuffer of [
+            this.meterFramebuffer,
+            this.localFramebuffer,
+            ...this.heldFramebuffers,
+        ]) {
+            if (framebuffer !== null)
+                gl.deleteFramebuffer(framebuffer);
+        }
+        for (const texture of [this.meter, this.localGrid, ...this.held])
+            if (texture !== null)
+                gl.deleteTexture(texture);
+        gl.deleteProgram(this.meterProgram);
+        gl.deleteProgram(this.localProgram);
+        gl.deleteProgram(this.adaptProgram);
+        gl.deleteVertexArray(this.vao);
+    }
+}

package/dist/render/flameLight.d.ts

@@ -0,0 +1,71 @@
+/**
+ * A flame: one point light and one plume from a single description, flickering at the rate a flame
+ * of that size flickers.
+ *
+ * **The rate is physics, not taste.** A buoyant flame puffs at about 1.5 / √D times a second for a
+ * burning area D metres across (Cetegen and Ahmed, 1993). That is 15 Hz for a candle's centimetre,
+ * which is why a candle trembles, and 2.4 Hz for a 40 cm brazier, which is why a fire breathes.
+ * Before this, a scene wired its plume, its light and a flicker amplitude by hand. The selection's
+ * shared wobble ran every light at the same two rates, so a candle and a bonfire pulsed together.
+ *
+ * **What the description fixes.** The flame stands 2.5 D tall, which is a candle's 2.5 cm and a
+ * brazier's metre. The light sits a third of the way up it, where a flame is brightest, and its
+ * physical radius is D / 2, so its shadows soften as a fire's do. It sways by up to 6 per cent of
+ * the flame's height on each axis, a few centimetres for a brazier, so a shadow it casts travels
+ * rather than only dimming.
+ *
+ * **What it gives up.** The waveform is two sines, the pulse and a harmonic, which never gust. A
+ * fire in wind wants its sway driven by the scene's `WindField`, and nothing here reads one. What
+ * would make the rate wrong is a flame far outside the law's range: a jet, or a pool fire of
+ * several metres, which puffs slower than the formula says.
+ *
+ * Plain data and two functions. `updateFlame` writes into the light it made and allocates nothing,
+ * so a scene updates every flame in its frame and hands the lights to `selectPointLights`.
+ */
+import type { Vec3 } from '../math/color.ts';
+import type { PlumePlacement } from './plumeRenderer.ts';
+import type { PointLightSource } from './pointLightSelection.ts';
+export interface FlameOptions {
+    /** Where the fire burns from, world space: the wick's tip, the top of the coals. */
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+    /** How wide the burning area is, metres: a candle 0.01, a lantern 0.03, a brazier's bowl 0.4. */
+    readonly diameterM: number;
+    /** The light's colour at its mean brightness, in the caller's light units. */
+    readonly color: Vec3;
+    /** Metres at which the light ends. */
+    readonly radius: number;
+    /** How far the brightness swings either side of its mean, 0 to 1. Defaults to 0.18. */
+    readonly flicker?: number;
+    /** Keeps two flames of one size out of step. Defaults to 0. */
+    readonly seed?: number;
+    /** Whether the light may take a shadow slot. Defaults to true, as `PointLightSource` does. */
+    readonly castsShadow?: boolean;
+    /**
+     * How far the light wanders on each axis, as a share of the flame's height. Defaults to 0.06.
+     *
+     * 0 holds it still. A point light's static shadow map is baked from where the light stood, so a
+     * light that wanders reads that map from a few centimetres off. What would make the default wrong
+     * is a flame near a surface it shadows, where that offset shows as a band.
+     */
+    readonly sway?: number;
+}
+export interface Flame {
+    /** Rewritten by `updateFlame`. Offer it to `selectPointLights` with the scene's other lights. */
+    readonly light: PointLightSource;
+    /** Where the plume stands and how big it is, for `createPlumes`. */
+    readonly plume: PlumePlacement;
+    /** Pulses a second: 1.5 / √D. */
+    readonly frequencyHz: number;
+    readonly centre: Vec3;
+    readonly color: Vec3;
+    readonly flicker: number;
+    readonly phase: number;
+    readonly swayM: number;
+}
+/** The puffing rate of a flame burning from `diameterM` metres across. */
+export declare function flameFrequencyHz(diameterM: number): number;
+export declare function createFlame(options: FlameOptions): Flame;
+/** Where the flame's light is and how bright, at `timeSeconds`. Writes `flame.light` in place. */
+export declare function updateFlame(flame: Flame, timeSeconds: number): void;

package/dist/render/flameLight.js

@@ -0,0 +1,63 @@
+/** How tall a flame stands, as a multiple of the width it burns from. */
+const HEIGHT_PER_DIAMETER = 2.5;
+/** How far the light sways on each axis, as a share of the flame's height. */
+const SWAY_PER_HEIGHT = 0.06;
+/** The harmonic's rate against the pulse's, chosen irrational so the two never lock. */
+const HARMONIC = 2.37;
+/** The puffing rate of a flame burning from `diameterM` metres across. */
+export function flameFrequencyHz(diameterM) {
+    return 1.5 / Math.sqrt(Math.max(diameterM, 1e-3));
+}
+export function createFlame(options) {
+    const height = HEIGHT_PER_DIAMETER * options.diameterM;
+    const centre = [options.x, options.y + height / 3, options.z];
+    /* A seed spread over the whole turn, so seeds 1 and 2 are not neighbours in phase. */
+    const phase = ((options.seed ?? 0) * 2.399963) % (Math.PI * 2);
+    const light = {
+        x: centre[0],
+        y: centre[1],
+        z: centre[2],
+        r: options.color[0],
+        g: options.color[1],
+        b: options.color[2],
+        radius: options.radius,
+        /* Off, because this helper is the flicker; the selection's own would apply a second one. */
+        flicker: 0,
+        shadowNear: Math.max(0.05, options.diameterM),
+        sourceRadius: options.diameterM / 2,
+        ...(options.castsShadow === false ? { castsShadow: false } : {}),
+    };
+    return {
+        light,
+        plume: {
+            x: options.x,
+            y: options.y,
+            z: options.z,
+            width: options.diameterM / 2,
+            height,
+        },
+        frequencyHz: flameFrequencyHz(options.diameterM),
+        centre,
+        color: [options.color[0], options.color[1], options.color[2]],
+        flicker: options.flicker ?? 0.18,
+        phase,
+        swayM: (options.sway ?? SWAY_PER_HEIGHT) * height,
+    };
+}
+/** Where the flame's light is and how bright, at `timeSeconds`. Writes `flame.light` in place. */
+export function updateFlame(flame, timeSeconds) {
+    const w = 2 * Math.PI * flame.frequencyHz * timeSeconds;
+    const p = flame.phase;
+    const pulse = 0.65 * Math.sin(w + p) + 0.35 * Math.sin(HARMONIC * w + 1.9 * p);
+    const scale = 1 + flame.flicker * pulse;
+    const light = flame.light;
+    light.r = flame.color[0] * scale;
+    light.g = flame.color[1] * scale;
+    light.b = flame.color[2] * scale;
+    /* The sway runs slower than the pulse and on its own rates, so the light wanders rather than
+       tracing one loop. Up when the flame puffs up. */
+    const sway = flame.swayM;
+    light.x = flame.centre[0] + sway * Math.sin(0.83 * w + 2.1 * p);
+    light.y = flame.centre[1] + sway * Math.sin(w + p);
+    light.z = flame.centre[2] + sway * Math.cos(0.71 * w + 3.3 * p);
+}

package/dist/render/gi/bounceLights.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The frame's exact lights as DriftRay's probe bake reads them: what a surface a probe's ray
+ * strikes is lit by, besides the sun, the bounce already in the grid and a DriftLight field.
+ *
+ * **Why the trace needs them at all.** A probe ray shades what it hits itself rather than reading
+ * a capture, which is what lets the bounce follow a light that moves; but it shaded with the sun
+ * alone, so a courtyard at night bounced no firelight into the corners the fires could not see. A
+ * field carries the many fixed lights; these are the rest, the lights the frame shades one by one,
+ * flickering and moving as they do in the frame.
+ *
+ * **Decided here and bound there**, by the 2026-08-13 rule: which lights, in what order and at what
+ * weight is one decision for any backend that traces. A light a field sums carries a negative
+ * weight and is left out, because the field already brings it to the bounce; a fading light goes in
+ * at its weight, as the lit shader scales it.
+ *
+ * **At most `MAX_BOUNCE_LIGHTS`, the first the selection chose**, which is nearest the camera: each
+ * one is a march per ray that reaches it, and a probe far from the camera is lit by lights further
+ * down the list that this leaves out. What would change that is a scene whose bounce is dominated
+ * by lights far from where it is looked at, which would want the selection run again from the grid.
+ *
+ * What it gives up against the frame: a photometric profile and a cookie, which the bounce reads as
+ * a plain cone, and a light's specular, which a diffuse bounce has no use for.
+ */
+import type { PointLightSet } from '../lightBudget.ts';
+/** Lights the probe bake shades a hit with. */
+export declare const MAX_BOUNCE_LIGHTS = 32;
+/**
+ * Floats a light takes: where it is and how far it reaches; its colour at its weight and the cosine
+ * of its inner cone; the way it points and the cosine of its outer cone.
+ */
+export declare const BOUNCE_LIGHT_FLOATS = 12;
+export declare function createBounceLights(): Float32Array;
+/** Pack the lights of `lights` the bounce reads into `out`, and answer how many. */
+export declare function resolveBounceLights(lights: PointLightSet | null, out: Float32Array): number;

package/dist/render/gi/bounceLights.js

@@ -0,0 +1,66 @@
+/**
+ * The frame's exact lights as DriftRay's probe bake reads them: what a surface a probe's ray
+ * strikes is lit by, besides the sun, the bounce already in the grid and a DriftLight field.
+ *
+ * **Why the trace needs them at all.** A probe ray shades what it hits itself rather than reading
+ * a capture, which is what lets the bounce follow a light that moves; but it shaded with the sun
+ * alone, so a courtyard at night bounced no firelight into the corners the fires could not see. A
+ * field carries the many fixed lights; these are the rest, the lights the frame shades one by one,
+ * flickering and moving as they do in the frame.
+ *
+ * **Decided here and bound there**, by the 2026-08-13 rule: which lights, in what order and at what
+ * weight is one decision for any backend that traces. A light a field sums carries a negative
+ * weight and is left out, because the field already brings it to the bounce; a fading light goes in
+ * at its weight, as the lit shader scales it.
+ *
+ * **At most `MAX_BOUNCE_LIGHTS`, the first the selection chose**, which is nearest the camera: each
+ * one is a march per ray that reaches it, and a probe far from the camera is lit by lights further
+ * down the list that this leaves out. What would change that is a scene whose bounce is dominated
+ * by lights far from where it is looked at, which would want the selection run again from the grid.
+ *
+ * What it gives up against the frame: a photometric profile and a cookie, which the bounce reads as
+ * a plain cone, and a light's specular, which a diffuse bounce has no use for.
+ */
+import { POINT_LIGHT_COS_INNER, POINT_LIGHT_COS_OUTER } from '../clusteredLights.js';
+/** Lights the probe bake shades a hit with. */
+export const MAX_BOUNCE_LIGHTS = 32;
+/**
+ * Floats a light takes: where it is and how far it reaches; its colour at its weight and the cosine
+ * of its inner cone; the way it points and the cosine of its outer cone.
+ */
+export const BOUNCE_LIGHT_FLOATS = 12;
+export function createBounceLights() {
+    return new Float32Array(MAX_BOUNCE_LIGHTS * BOUNCE_LIGHT_FLOATS);
+}
+/** Pack the lights of `lights` the bounce reads into `out`, and answer how many. */
+export function resolveBounceLights(lights, out) {
+    if (lights === null)
+        return 0;
+    let count = 0;
+    for (let i = 0; i < lights.lightCount && count < MAX_BOUNCE_LIGHTS; i++) {
+        const weight = lights.lightWeights[i] ?? 0;
+        const radius = lights.lightRadii[i] ?? 0;
+        if (!(weight > 0) || !(radius > 0))
+            continue;
+        const r = lights.lightColors[i * 3] ?? 0;
+        const g = lights.lightColors[i * 3 + 1] ?? 0;
+        const b = lights.lightColors[i * 3 + 2] ?? 0;
+        if (!(r + g + b > 0))
+            continue;
+        const at = count * BOUNCE_LIGHT_FLOATS;
+        out[at] = lights.lightPositions[i * 3] ?? 0;
+        out[at + 1] = lights.lightPositions[i * 3 + 1] ?? 0;
+        out[at + 2] = lights.lightPositions[i * 3 + 2] ?? 0;
+        out[at + 3] = radius;
+        out[at + 4] = r * weight;
+        out[at + 5] = g * weight;
+        out[at + 6] = b * weight;
+        out[at + 7] = lights.lightConeCos?.[i * 2] ?? POINT_LIGHT_COS_INNER;
+        out[at + 8] = lights.lightDirections?.[i * 3] ?? 0;
+        out[at + 9] = lights.lightDirections?.[i * 3 + 1] ?? 0;
+        out[at + 10] = lights.lightDirections?.[i * 3 + 2] ?? 0;
+        out[at + 11] = lights.lightConeCos?.[i * 2 + 1] ?? POINT_LIGHT_COS_OUTER;
+        count++;
+    }
+    return count;
+}

package/dist/render/gi/fieldReach.d.ts

@@ -0,0 +1,12 @@
+import type { ProbeGrid } from '../probeGrid.ts';
+/**
+ * Cascades enough for the outermost to hold the whole grid, and one probe step past it, within the
+ * part of it that is trusted, wherever inside the grid the camera stands. At least `least` and at
+ * most `most`: each cascade is the same number of samples, so the bound is on memory, not reach.
+ */
+export declare function cascadesForGrid(grid: ProbeGrid, radius: number, least: number, most: number): number;
+/**
+ * Keeps, in place and in order, the scheduled probes inside the trusted part of the outermost
+ * cascade, `bounds` as `[minX, minY, minZ, maxX, maxY, maxZ]`. Returns how many are kept.
+ */
+export declare function probesTheFieldReaches(grid: ProbeGrid, scheduled: Int32Array, count: number, bounds: ArrayLike<number>): number;