@driftengine/core 4.8.5 → 4.8.7

package/dist/render/particleMaterial.js

@@ -1,5 +1,5 @@
-import { PARTICLE_MOTE_FRAG, PARTICLE_SMOKE_FRAG, PARTICLE_SPARK_FRAG, PARTICLE_VERT, } from './shaders/particle.js';
-import { PARTICLE_BINDINGS, PARTICLE_MOTE_FRAG_WGSL, PARTICLE_SMOKE_FRAG_WGSL, PARTICLE_SPARK_FRAG_WGSL, PARTICLE_VERT_WGSL, } from './shaders/generated/particle.wgsl.js';
+import { PARTICLE_MOTE_FRAG, PARTICLE_SMOKE_FRAG, PARTICLE_SPARK_FRAG, PARTICLE_SPRITE_FRAG, PARTICLE_VERT, } from './shaders/particle.js';
+import { PARTICLE_BINDINGS, PARTICLE_MOTE_FRAG_WGSL, PARTICLE_SMOKE_FRAG_WGSL, PARTICLE_SPARK_FRAG_WGSL, PARTICLE_SPRITE_FRAG_WGSL, PARTICLE_VERT_WGSL, } from './shaders/generated/particle.wgsl.js';
 /**
  * Every particle material this engine ships.
  *
@@ -28,6 +28,14 @@ const MATERIALS = {
         vertexWgsl: PARTICLE_VERT_WGSL,
         fragmentWgsl: PARTICLE_MOTE_FRAG_WGSL,
     },
+    /* An image a consumer supplies, not a shape this engine draws: see `PARTICLE_SPRITE_FRAG`. */
+    sprite: {
+        label: 'particle:sprite',
+        vertexSource: PARTICLE_VERT,
+        fragmentSource: PARTICLE_SPRITE_FRAG,
+        vertexWgsl: PARTICLE_VERT_WGSL,
+        fragmentWgsl: PARTICLE_SPRITE_FRAG_WGSL,
+    },
 };
 /** What the generator recorded about the shared vertex stage. */
 export const PARTICLE_VERT_BINDINGS = PARTICLE_BINDINGS.PARTICLE_VERT;

package/dist/render/particlePool.d.ts

@@ -36,9 +36,41 @@ export interface ParticleInstances {
     seeds: Float32Array;
     /** Current velocity, three floats each: what a streak is stretched along. */
     velocities: Float32Array;
+    /**
+     * A sprite's flipbook frame, one float each: its whole part names a cell of the image, counted
+     * across then down from the top-left, and its fraction is how far toward the next a batch that
+     * blends cells has come. Read by the `'sprite'` material alone. Absent is frame 0.
+     */
+    frames?: Float32Array;
+    /**
+     * A sprite's half-height in metres, one float each, beside `sizes`' half-width — a sprite need
+     * not be square. Read by the `'sprite'` material alone; absent or 0 is as tall as it is wide.
+     */
+    heights?: Float32Array;
     count: number;
     capacity: number;
 }
+/**
+ * Floats one particle takes in a buffer a caller's own compute writes (`DeviceParticles`), in this
+ * order: position 3, half-width 1, roll 1, colour 3, opacity 1, age 1, seed 1, velocity 3, a
+ * sprite's frame 1 and its half-height 1 — `ParticleInstances`' streams, interleaved as the pool's
+ * own upload interleaves them. 64 bytes a particle.
+ */
+export declare const DEVICE_PARTICLE_FLOATS = 16;
+/**
+ * Particles a caller's own compute shader wrote into a buffer of its own (`registerCompute`), drawn
+ * where they lie by `drawDeviceParticles` rather than read back and uploaded again. WebGPU only.
+ *
+ * **Not sorted**, as a pool's are where its batch asks: the device holds them, so an alpha-blended
+ * set that must be drawn far to near sorts itself. A slot with a half-width of 0 draws nothing, which
+ * is how a fixed-size buffer holds fewer live particles than it has room for.
+ */
+export interface DeviceParticles {
+    /** A buffer with `VERTEX` usage, `DEVICE_PARTICLE_FLOATS` floats a particle. */
+    readonly buffer: GPUBuffer;
+    /** How many particles from its start to draw; no more than the buffer holds. */
+    readonly count: number;
+}
 /**
  * A pool of short-lived particles, simulated on the CPU and drawn as instances.
  *

package/dist/render/particlePool.js

@@ -1,4 +1,11 @@
 import { createInstanceData, writeInstance } from './instancedMesh.js';
+/**
+ * Floats one particle takes in a buffer a caller's own compute writes (`DeviceParticles`), in this
+ * order: position 3, half-width 1, roll 1, colour 3, opacity 1, age 1, seed 1, velocity 3, a
+ * sprite's frame 1 and its half-height 1 — `ParticleInstances`' streams, interleaved as the pool's
+ * own upload interleaves them. 64 bytes a particle.
+ */
+export const DEVICE_PARTICLE_FLOATS = 16;
 function createParticleInstances(capacity) {
     return {
         positions: new Float32Array(capacity * 3),
@@ -9,6 +16,8 @@ function createParticleInstances(capacity) {
         ages: new Float32Array(capacity),
         seeds: new Float32Array(capacity),
         velocities: new Float32Array(capacity * 3),
+        frames: new Float32Array(capacity),
+        heights: new Float32Array(capacity),
         count: 0,
         capacity,
     };

package/dist/render/particleSort.d.ts

@@ -0,0 +1,34 @@
+/**
+ * A pool's particles, farthest from the eye first, for a blended batch that asks to be sorted.
+ *
+ * **Why a blended batch wants it.** An alpha blend is order-dependent: a near puff drawn before a
+ * far one is covered by it, and a cloud of them drawn in the order they were born flickers as
+ * that order and the camera disagree. Back to front is the order the blend assumes. Additive
+ * blending is a sum and needs none of it, which is why sorting is the batch's choice.
+ *
+ * **Backend-neutral, as a copy**: the sorted particles are written into a second set of streams the
+ * batch owns, and each backend uploads that set exactly as it uploads an unsorted one — so the
+ * order is one decision, not two, by the 2026-08-13 rule. A merge sort into preallocated scratch,
+ * so nothing is allocated per frame however many particles there are; stable, so two particles at
+ * one distance keep their order and do not trade places from frame to frame.
+ *
+ * **What it gives up** is order between batches and within one particle: two sorted batches still
+ * draw one after the other, and two crossing cards cut through each other. **What would make it
+ * wrong** is a field of particles large enough that sorting it on the CPU costs a frame; the GPU
+ * sorts it then.
+ */
+import type { ParticleInstances } from './particlePool.ts';
+/** What sorting a batch keeps between frames: the order, its keys and the sorted copy. */
+export interface ParticleSort {
+    readonly order: Uint32Array;
+    readonly scratch: Uint32Array;
+    readonly keys: Float32Array;
+    readonly sorted: ParticleInstances;
+}
+/** Room to sort `capacity` particles, allocated once with the batch. */
+export declare function createParticleSort(capacity: number): ParticleSort;
+/**
+ * `data`'s live particles into `sort.sorted`, farthest from `eye` first, and that copy returned.
+ * At most the sort's capacity are kept.
+ */
+export declare function sortBackToFront(data: ParticleInstances, eye: ArrayLike<number>, sort: ParticleSort): ParticleInstances;

package/dist/render/particleSort.js

@@ -0,0 +1,96 @@
+/** Room to sort `capacity` particles, allocated once with the batch. */
+export function createParticleSort(capacity) {
+    return {
+        order: new Uint32Array(capacity),
+        scratch: new Uint32Array(capacity),
+        keys: new Float32Array(capacity),
+        sorted: {
+            positions: new Float32Array(capacity * 3),
+            sizes: new Float32Array(capacity),
+            spins: new Float32Array(capacity),
+            colors: new Float32Array(capacity * 3),
+            alphas: new Float32Array(capacity),
+            ages: new Float32Array(capacity),
+            seeds: new Float32Array(capacity),
+            velocities: new Float32Array(capacity * 3),
+            frames: new Float32Array(capacity),
+            heights: new Float32Array(capacity),
+            count: 0,
+            capacity,
+        },
+    };
+}
+/**
+ * `data`'s live particles into `sort.sorted`, farthest from `eye` first, and that copy returned.
+ * At most the sort's capacity are kept.
+ */
+export function sortBackToFront(data, eye, sort) {
+    const count = Math.min(data.count, sort.order.length);
+    const { order, keys } = sort;
+    const ex = eye[0] ?? 0;
+    const ey = eye[1] ?? 0;
+    const ez = eye[2] ?? 0;
+    for (let i = 0; i < count; i++) {
+        const dx = data.positions[i * 3] - ex;
+        const dy = data.positions[i * 3 + 1] - ey;
+        const dz = data.positions[i * 3 + 2] - ez;
+        keys[i] = dx * dx + dy * dy + dz * dz;
+        order[i] = i;
+    }
+    mergeSortFarFirst(order, sort.scratch, keys, count);
+    const out = sort.sorted;
+    for (let k = 0; k < count; k++) {
+        const i = order[k];
+        copy3(data.positions, i, out.positions, k);
+        copy3(data.colors, i, out.colors, k);
+        copy3(data.velocities, i, out.velocities, k);
+        out.sizes[k] = data.sizes[i];
+        out.spins[k] = data.spins[i];
+        out.alphas[k] = data.alphas[i];
+        out.ages[k] = data.ages[i];
+        out.seeds[k] = data.seeds[i];
+        out.frames[k] = data.frames?.[i] ?? 0;
+        out.heights[k] = data.heights?.[i] ?? 0;
+    }
+    out.count = count;
+    return out;
+}
+function copy3(from, i, to, k) {
+    to[k * 3] = from[i * 3];
+    to[k * 3 + 1] = from[i * 3 + 1];
+    to[k * 3 + 2] = from[i * 3 + 2];
+}
+/** A bottom-up merge sort of `order` by `keys`, largest first, stable, through `scratch`. */
+function mergeSortFarFirst(order, scratch, keys, count) {
+    let from = order;
+    let to = scratch;
+    for (let width = 1; width < count; width *= 2) {
+        for (let start = 0; start < count; start += 2 * width) {
+            const middle = Math.min(start + width, count);
+            const end = Math.min(start + 2 * width, count);
+            let a = start;
+            let b = middle;
+            let at = start;
+            while (a < middle && b < end) {
+                /* `>=` keeps the left run's particle first on a tie, which is what makes this stable. */
+                if (keys[from[a]] >= keys[from[b]]) {
+                    to[at++] = from[a++];
+                }
+                else {
+                    to[at++] = from[b++];
+                }
+            }
+            while (a < middle)
+                to[at++] = from[a++];
+            while (b < end)
+                to[at++] = from[b++];
+        }
+        const swap = from;
+        from = to;
+        to = swap;
+    }
+    /* Copied by hand: a subarray would be a view allocated every frame. */
+    if (from !== order)
+        for (let i = 0; i < count; i++)
+            order[i] = from[i];
+}

package/dist/render/pointLightSelection.d.ts

@@ -69,6 +69,14 @@ export interface PointLightSource {
      * whose uniform budget has none to spare.
      */
     inLightField?: boolean;
+    /**
+     * How the light fades with distance when it names its own way: `(1 - (d/R)^2)^n` with no distance
+     * term, `R` its radius and `n` this. Unreal's falloff for a light without inverse-square falloff,
+     * so a rig authored there — a fill of brightness 160 across 164 m, a key at exponent 8 — lights
+     * the space it was authored for rather than one that ends a few metres out. Absent or 0, the
+     * frame's own falloff (`pointLightFalloff`), which is every light before 4.8.7.
+     */
+    falloffExponent?: number;
 }
 export interface PointLightBuffer {
     readonly positions: Float32Array;
@@ -126,6 +134,11 @@ export interface PointLightBuffer {
     readonly directions: Float32Array;
     /** Two per slot: the cosine of the inner cone angle, then of the outer. */
     readonly coneCos: Float32Array;
+    /**
+     * One per slot: the light's own falloff exponent, or 0 for the frame's falloff. See
+     * `PointLightSource.falloffExponent`.
+     */
+    readonly falloffExponents: Float32Array;
     /** One per slot: a row of the photometric atlas, or −1 for a light with no profile. */
     readonly iesProfiles: Float32Array;
     /** Internal insertion-sort storage; exposed only to keep one flat object. */

package/dist/render/pointLightSelection.js

@@ -1,5 +1,5 @@
 /** Allocation-free selection and packing of point lights for a fixed shader budget. */
-import { POINT_LIGHT_COS_INNER, POINT_LIGHT_COS_OUTER } from './clusteredLights.js';
+import { POINT_LIGHT_COS_INNER, POINT_LIGHT_COS_OUTER, lightFalloffExponentOf, } from './clusteredLights.js';
 import { MAX_POINT_LIGHTS, POINT_SHADOW_POOL } from './lightBudget.js';
 import { gatherLights } from './lightGrid.js';
 export const DEFAULT_POINT_LIGHT_VIEW_RANGE = 180;
@@ -150,6 +150,7 @@ export function createPointLightBuffer(capacity = MAX_POINT_LIGHTS) {
         weights: new Float32Array(shaded),
         directions: new Float32Array(shaded * 3),
         coneCos: new Float32Array(shaded * 2),
+        falloffExponents: new Float32Array(shaded),
         /* −1 rather than 0, because row 0 is a real fixture and a light that asked for none must not
            be shaped by whichever profile happened to load first. */
         iesProfiles: new Float32Array(shaded).fill(-1),
@@ -382,6 +383,7 @@ function choose(sources, visit, visitCount, x, y, z, out, timeSeconds, viewRange
          * Restricting it to spots would be a smaller feature for no saving.
          */
         out.iesProfiles[slot] = light.iesProfile ?? -1;
+        out.falloffExponents[slot] = lightFalloffExponentOf(light.falloffExponent);
     }
     out.count = chosen;
     /*

package/dist/render/renderQuality.d.ts

@@ -209,13 +209,14 @@ export interface RenderQuality {
      * **`'pre-integrated'`, the default**: the lit stage's fit alone — a terminator softened and
      * reddened by the surface's curvature, light through thin parts, a penumbra each channel crosses
      * as far as it travels — at no cost beyond the skin pipeline itself. **`'screen-space'`** adds
-     * Burley's blur in the picture as well: a skin draw writes its diffuse to a target of its own (it
-     * is drawn twice to do so), which is spread across the pixels its scatter distance covers and
-     * added back before anything blended is drawn, so light crosses a shadow's edge and a nostril's
-     * rim in the picture rather than in a fit. See `skinBlur.ts`.
-     *
-     * Construction-time: two half-float targets the size of the frame, and a multisampled one under
-     * multisampling, made at the first skin draw. It needs the composite (`screenEffects`), which is
+     * Burley's blur in the picture as well: a skin draw writes the light its diffuse is made of to a
+     * target of its own and its colour to another (it is drawn three times to do so), and the light is
+     * spread across the pixels its scatter distance covers, multiplied by the colour and added back
+     * before anything blended is drawn, so light crosses a shadow's edge and a nostril's rim in the
+     * picture rather than in a fit. See `skinBlur.ts`.
+     *
+     * Construction-time: three half-float targets the size of the frame, and two multisampled ones
+     * under multisampling, made at the first skin draw. It needs the composite (`screenEffects`), which is
      * where the frame is still linear light to add to; without one, skin is pre-integrated and the
      * renderer says so once. What would make the default wrong is a close-up face that reads as wax
      * at a shadow's edge — that is what the blur is for.

package/dist/render/rendererHarness.js

@@ -76,6 +76,9 @@ export function recordingGl(options = {}) {
         ONE: 1,
         ONE_MINUS_SRC_ALPHA: 0x0303,
         TRIANGLES: 0x0004,
+        /* The winding a pass names, so a test can tell which one it chose. */
+        CW: 0x0900,
+        CCW: 0x0901,
         TEXTURE0: 0x84c0,
         DEPTH_BUFFER_BIT: 0x00000100,
         DEPTH_TEST: 0x0b71,

package/dist/render/rgb9e5.d.ts

@@ -0,0 +1,22 @@
+/**
+ * rgb9e5: three 9-bit mantissas over one shared 5-bit exponent, an unsigned float colour in four
+ * bytes. `EXT_texture_shared_exponent`'s encoding, the one a GPU's `rgb9e5ufloat` reads, written
+ * out so a lightmap page can hold its irradiance in four bytes a texel against a half float's eight.
+ *
+ * **What it gives up**: precision in the smaller channels, which share the largest one's exponent —
+ * a channel a thousandth of its neighbour keeps about one bit — and anything negative or past
+ * 65,408, which it clamps. Light is neither, and a bake's colours rarely span more than a few
+ * octaves within one texel, so a lightmap loses nothing visible; a value that needs each channel
+ * exact wants a format of its own.
+ *
+ * The bits, low to high: red in 0–8, green in 9–17, blue in 18–26, the exponent in 27–31, biased by
+ * 15, and a value is `mantissa * 2^(exponent - 15 - 9)`.
+ */
+/** The largest value the format holds: 511/512 of 2^16. */
+export declare const RGB9E5_MAX: number;
+/** One colour packed into its 32 bits, rounding to nearest; NaN and negatives are zero. */
+export declare function packRgb9e5(red: number, green: number, blue: number): number;
+/** A packed colour's three channels, into `out[at…at+2]`. */
+export declare function unpackRgb9e5(bits: number, out: {
+    [index: number]: number;
+}, at?: number): void;

package/dist/render/rgb9e5.js

@@ -0,0 +1,47 @@
+/**
+ * rgb9e5: three 9-bit mantissas over one shared 5-bit exponent, an unsigned float colour in four
+ * bytes. `EXT_texture_shared_exponent`'s encoding, the one a GPU's `rgb9e5ufloat` reads, written
+ * out so a lightmap page can hold its irradiance in four bytes a texel against a half float's eight.
+ *
+ * **What it gives up**: precision in the smaller channels, which share the largest one's exponent —
+ * a channel a thousandth of its neighbour keeps about one bit — and anything negative or past
+ * 65,408, which it clamps. Light is neither, and a bake's colours rarely span more than a few
+ * octaves within one texel, so a lightmap loses nothing visible; a value that needs each channel
+ * exact wants a format of its own.
+ *
+ * The bits, low to high: red in 0–8, green in 9–17, blue in 18–26, the exponent in 27–31, biased by
+ * 15, and a value is `mantissa * 2^(exponent - 15 - 9)`.
+ */
+const BIAS = 15;
+const MANTISSA_BITS = 9;
+const MANTISSA_VALUES = 1 << MANTISSA_BITS;
+const MAX_EXPONENT = 31;
+/** The largest value the format holds: 511/512 of 2^16. */
+export const RGB9E5_MAX = ((MANTISSA_VALUES - 1) / MANTISSA_VALUES) * 2 ** (MAX_EXPONENT - BIAS);
+const clampChannel = (v) => (v > 0 ? Math.min(v, RGB9E5_MAX) : 0);
+/** One colour packed into its 32 bits, rounding to nearest; NaN and negatives are zero. */
+export function packRgb9e5(red, green, blue) {
+    const r = clampChannel(red);
+    const g = clampChannel(green);
+    const b = clampChannel(blue);
+    const largest = Math.max(r, g, b);
+    let exponent = Math.max(-BIAS - 1, Math.floor(Math.log2(largest))) + 1 + BIAS;
+    let scale = 2 ** (exponent - BIAS - MANTISSA_BITS);
+    /* Rounding the largest channel up to 512 needs one more exponent, which the spec allows for. */
+    if (Math.floor(largest / scale + 0.5) === MANTISSA_VALUES) {
+        exponent += 1;
+        scale *= 2;
+    }
+    /* Inline rather than a helper: a page packs millions of texels, and a closure a call is one each. */
+    const mr = Math.min(MANTISSA_VALUES - 1, Math.floor(r / scale + 0.5));
+    const mg = Math.min(MANTISSA_VALUES - 1, Math.floor(g / scale + 0.5));
+    const mb = Math.min(MANTISSA_VALUES - 1, Math.floor(b / scale + 0.5));
+    return (mr | (mg << 9) | (mb << 18) | (exponent << 27)) >>> 0;
+}
+/** A packed colour's three channels, into `out[at…at+2]`. */
+export function unpackRgb9e5(bits, out, at = 0) {
+    const scale = 2 ** ((bits >>> 27) - BIAS - MANTISSA_BITS);
+    out[at] = (bits & 511) * scale;
+    out[at + 1] = ((bits >>> 9) & 511) * scale;
+    out[at + 2] = ((bits >>> 18) & 511) * scale;
+}

package/dist/render/sceneCapture.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A scene capture: a texture the world is drawn into from a camera of the caller's, which a material
+ * then shows like any image — a screen in the world showing what a camera elsewhere sees, a monitor,
+ * a security feed. The planar reflection's pass, for a caller's camera rather than a mirrored one.
+ *
+ * **It holds radiance, not display pixels**, as a probe does: drawn with the output transform held
+ * off, at the colour format a probe takes — half floats under `hdrScene`, bytes otherwise — and
+ * sampled linear, so a material showing it as its `emissive` emits the light the capture saw and the
+ * frame's grade then applies once, to the screen as to everything around it.
+ *
+ * **What it gives up**: it is the mesh pass alone, as a probe bake is — the sky, water, particles and
+ * anything else a scene draws after its world are in the capture only if the callback draws them;
+ * no temporal resolve, bloom or other effect after the world runs on it; and it has no mip chain, so
+ * a screen seen small and far shimmers where a mipmapped image would not.
+ */
+/** What a capture's texture is made from, in place of an image: its size and colour format. */
+export interface SceneCaptureTexels {
+    readonly kind: 'scene-capture';
+    readonly width: number;
+    readonly height: number;
+    /** Half floats, which hold light past one; bytes otherwise. */
+    readonly float: boolean;
+}
+/** The largest side a capture may have, the size every WebGL2 device must take. */
+export declare const MAX_SCENE_CAPTURE_SIZE = 4096;
+/** A capture's description, refused by name where a side is not a whole number of pixels it can be. */
+export declare function sceneCaptureTexels(width: number, height: number, float: boolean): SceneCaptureTexels;
+/** Whether a texture source is a capture's description rather than an image. */
+export declare function isSceneCaptureTexels(source: unknown): source is SceneCaptureTexels;

package/dist/render/sceneCapture.js

@@ -0,0 +1,36 @@
+/**
+ * A scene capture: a texture the world is drawn into from a camera of the caller's, which a material
+ * then shows like any image — a screen in the world showing what a camera elsewhere sees, a monitor,
+ * a security feed. The planar reflection's pass, for a caller's camera rather than a mirrored one.
+ *
+ * **It holds radiance, not display pixels**, as a probe does: drawn with the output transform held
+ * off, at the colour format a probe takes — half floats under `hdrScene`, bytes otherwise — and
+ * sampled linear, so a material showing it as its `emissive` emits the light the capture saw and the
+ * frame's grade then applies once, to the screen as to everything around it.
+ *
+ * **What it gives up**: it is the mesh pass alone, as a probe bake is — the sky, water, particles and
+ * anything else a scene draws after its world are in the capture only if the callback draws them;
+ * no temporal resolve, bloom or other effect after the world runs on it; and it has no mip chain, so
+ * a screen seen small and far shimmers where a mipmapped image would not.
+ */
+/** The largest side a capture may have, the size every WebGL2 device must take. */
+export const MAX_SCENE_CAPTURE_SIZE = 4096;
+/** A capture's description, refused by name where a side is not a whole number of pixels it can be. */
+export function sceneCaptureTexels(width, height, float) {
+    for (const [name, side] of [
+        ['width', width],
+        ['height', height],
+    ]) {
+        if (!Number.isInteger(side) || side < 1 || side > MAX_SCENE_CAPTURE_SIZE) {
+            throw new Error(`createSceneCapture: ${name} must be a whole number from 1 to ${MAX_SCENE_CAPTURE_SIZE}, ` +
+                `not ${String(side)}`);
+        }
+    }
+    return { kind: 'scene-capture', width, height, float };
+}
+/** Whether a texture source is a capture's description rather than an image. */
+export function isSceneCaptureTexels(source) {
+    return (typeof source === 'object' &&
+        source !== null &&
+        source.kind === 'scene-capture');
+}

package/dist/render/sceneTarget.d.ts

@@ -195,6 +195,9 @@ export declare class SceneTarget {
      * must reject it in the same place or the accumulation and the revealage cover different
      * fragments.
      */
+    /** The frame's size in pixels, as its targets are allocated. */
+    get frameWidth(): number;
+    get frameHeight(): number;
     /**
      * The depth the frame draws against, for a second framebuffer to share: skin's diffuse half,
      * which tests against it and writes none. The multisampled renderbuffer where the frame is
@@ -311,6 +314,8 @@ export declare class SceneTarget {
         readonly strength: number;
         /** In scene units, which is why this wants `keepsRange`. See `BloomPass`. */
         readonly threshold: number;
+        /** The ramp and each level's tint, as `resolveBloomResponse` writes them. */
+        readonly response: Float32Array;
     }, dof?: {
         /** Where the lens is focused, in metres. */
         readonly distance: number;

package/dist/render/sceneTarget.js

@@ -432,6 +432,13 @@ export class SceneTarget {
      * must reject it in the same place or the accumulation and the revealage cover different
      * fragments.
      */
+    /** The frame's size in pixels, as its targets are allocated. */
+    get frameWidth() {
+        return this.width;
+    }
+    get frameHeight() {
+        return this.height;
+    }
     /**
      * The depth the frame draws against, for a second framebuffer to share: skin's diffuse half,
      * which tests against it and writes none. The multisampled renderbuffer where the frame is
@@ -776,7 +783,7 @@ export class SceneTarget {
         let bloomTexture = null;
         if (bloom !== undefined && scene !== null) {
             this.bloom ??= new BloomPass(gl);
-            bloomTexture = this.bloom.run(scene, this.width, this.height, bloom.threshold);
+            bloomTexture = this.bloom.run(scene, this.width, this.height, bloom.threshold, bloom.response);
         }
         /*
          * Eye adaptation, metered from the same resolved scene bloom reads, and after it for the same

package/dist/render/screenSpaceReflection.d.ts

@@ -159,9 +159,30 @@ export declare function edgeFade(margin: number, band: number): number;
  * nothing at one running directly into it.
  */
 export declare function towardCameraFade(direction: ReadonlyVec3, viewDirection: ReadonlyVec3): number;
+/**
+ * What a `ReflectiveSurface` is made with: its box, which way the surfaces inside it face, and how
+ * much and how far they reflect. Every number but the box has a default; see each field.
+ */
 export interface ReflectiveSurfaceOptions extends DecalBox {
-    /** How much of what the ray finds lands on the surface, 0 to 1. */
+    /**
+     * How much of what the ray finds lands on the surface, 0 to 1: one share over the box, or with
+     * `fresnel` the surface's reflectance head-on.
+     */
     readonly strength?: number;
+    /**
+     * Whether `strength` is the surface's reflectance head-on, F0, rather than one share over the
+     * box. Each pixel then returns `F0 · A + B` of what its ray finds, the split-sum environment BRDF
+     * at its own view and `roughness` — Karis's fit, the one the lit stage reflects its environment
+     * by — so a floor returns more toward the horizon than underfoot, and the share follows the
+     * camera as Unreal weighs its reflections. **False by default**, the one share as before.
+     *
+     * **What it gives up**: the pass has no material buffer, so the roughness and F0 are the box's,
+     * not each pixel's, and nothing occludes the reflection where the lit stage's ambient occlusion
+     * would. A floor of one material is what it is for.
+     */
+    readonly fresnel?: boolean;
+    /** The surface's roughness, 0 to 1, that `fresnel` weighs by. 0, a polished surface, if absent. */
+    readonly roughness?: number;
     /** How far a ray may travel, world metres. */
     readonly reachM?: number;
     /** How deep a depth sample is treated as being. See `ScreenSpaceMarch.thicknessM`. */
@@ -189,6 +210,9 @@ export declare class ReflectiveSurface {
     readonly axis: Float32Array<ArrayBuffer>;
     readonly tint: Float32Array<ArrayBuffer>;
     strength: number;
+    /** See `ReflectiveSurfaceOptions.fresnel`. */
+    fresnel: boolean;
+    roughness: number;
     reachM: number;
     thicknessM: number;
     steps: number;
@@ -226,6 +250,8 @@ export interface RecordedReflection {
     readonly axis: Float32Array;
     readonly tint: Float32Array;
     strength: number;
+    fresnel: boolean;
+    roughness: number;
     reachM: number;
     thicknessM: number;
     steps: number;

package/dist/render/screenSpaceReflection.js

@@ -292,6 +292,9 @@ export class ReflectiveSurface {
     axis = new Float32Array(3);
     tint = new Float32Array(3);
     strength;
+    /** See `ReflectiveSurfaceOptions.fresnel`. */
+    fresnel;
+    roughness;
     reachM;
     thicknessM;
     steps;
@@ -308,6 +311,8 @@ export class ReflectiveSurface {
         /* Half, because a mirror is the rare case: a wet floor, polished stone and a car bonnet all
            return a fraction of what lands on them, and a consumer who wants a mirror asks for one. */
         this.strength = options.strength ?? 0.5;
+        this.fresnel = options.fresnel ?? false;
+        this.roughness = options.roughness ?? 0;
         /* Eight metres covers a room and a street corner. Further costs steps rather than accuracy,
            since the step is the reach divided by them. */
         this.reachM = options.reachM ?? 8;
@@ -366,6 +371,8 @@ function newRecord() {
         axis: new Float32Array(3),
         tint: new Float32Array(3),
         strength: 0.5,
+        fresnel: false,
+        roughness: 0,
         reachM: 8,
         thicknessM: 0.25,
         steps: 24,
@@ -414,6 +421,8 @@ export class ReflectionQueue {
         record.axis.set(surface.axis);
         record.tint.set(surface.tint);
         record.strength = Math.min(1, Math.max(0, surface.strength));
+        record.fresnel = surface.fresnel;
+        record.roughness = Math.min(1, Math.max(0, surface.roughness));
         record.reachM = Math.max(0, surface.reachM);
         record.thicknessM = Math.max(0, surface.thicknessM);
         record.steps = Math.min(32, Math.max(1, Math.round(surface.steps)));

package/dist/render/shaders/bloom.d.ts

@@ -27,7 +27,9 @@
  * 3. **Upsample**, additively back up the chain through a tent filter.
  *
  * Deliberately absent, because they were asked against by name: lens dirt, anamorphic streaks
- * and ghosting. One threshold, one radius, one strength.
+ * and ghosting. One threshold, one radius, one strength — and, since 4.8.6, how a colour comes in
+ * past the threshold and a tint for each octave, which is how another engine's stage is matched
+ * rather than how this one looks: see `BloomResponse` in `bloomChain.ts`.
  */
 /**
  * Stage one: threshold the scene and halve it.
@@ -46,7 +48,7 @@
  * first stage because it is not energy-preserving, and running it down the whole chain darkens
  * every large bright area rather than only taming isolated ones.
  */
-export declare const BLOOM_PREFILTER_FRAG = "#version 300 es\nprecision highp float;\n\nin vec2 vUv;\n\nuniform sampler2D uSource;\n/** One source texel in UV. The thirteen taps are laid out in source texels. */\nuniform vec2 uTexel;\n/** In scene units. 1.0 is \"brighter than white\", which is the useful place to start. */\nuniform float uThreshold;\n\nout vec4 fragColor;\n\n/**\n * A ceiling on what any one pixel may contribute, well above anything a scene means.\n *\n * Not a look control. A half-float target can hold an infinity, and an infinity through the\n * threshold below is inf/inf, which is a NaN that the chain then spreads across the whole\n * frame \u2014 the one failure mode where a post pass destroys the picture rather than degrading\n * it. Anything above this is indistinguishable after the tone curve anyway.\n */\nconst float BLOOM_CEILING = 256.0;\n\nfloat brightness(vec3 c) {\n  return max(c.r, max(c.g, c.b));\n}\n\nvec3 fetch(vec2 uv) {\n  vec3 c = min(textureLod(uSource, uv, 0.0).rgb, vec3(BLOOM_CEILING));\n  float bright = brightness(c);\n  return c * (max(bright - uThreshold, 0.0) / max(bright, 1e-4));\n}\n\n/** How much a box counts for. A runaway pixel drags its box's brightness up and its weight down. */\nfloat firefly(vec3 c) {\n  return 1.0 / (1.0 + brightness(c));\n}\n\nvoid main() {\n\n  vec2 t = uTexel;\n  vec3 a = fetch(vUv + vec2(-2.0,  2.0) * t);\n  vec3 b = fetch(vUv + vec2( 0.0,  2.0) * t);\n  vec3 c = fetch(vUv + vec2( 2.0,  2.0) * t);\n  vec3 d = fetch(vUv + vec2(-2.0,  0.0) * t);\n  vec3 e = fetch(vUv);\n  vec3 f = fetch(vUv + vec2( 2.0,  0.0) * t);\n  vec3 g = fetch(vUv + vec2(-2.0, -2.0) * t);\n  vec3 h = fetch(vUv + vec2( 0.0, -2.0) * t);\n  vec3 i = fetch(vUv + vec2( 2.0, -2.0) * t);\n  vec3 j = fetch(vUv + vec2(-1.0,  1.0) * t);\n  vec3 k = fetch(vUv + vec2( 1.0,  1.0) * t);\n  vec3 l = fetch(vUv + vec2(-1.0, -1.0) * t);\n  vec3 m = fetch(vUv + vec2( 1.0, -1.0) * t);\n\n  vec3 box0 = (a + b + d + e) * 0.25;\n  vec3 box1 = (b + c + e + f) * 0.25;\n  vec3 box2 = (d + e + g + h) * 0.25;\n  vec3 box3 = (e + f + h + i) * 0.25;\n  vec3 box4 = (j + k + l + m) * 0.25;\n\n  float w0 = firefly(box0) * 0.125;\n  float w1 = firefly(box1) * 0.125;\n  float w2 = firefly(box2) * 0.125;\n  float w3 = firefly(box3) * 0.125;\n  float w4 = firefly(box4) * 0.5;\n  vec3 sum = box0 * w0 + box1 * w1 + box2 * w2 + box3 * w3 + box4 * w4;\n  fragColor = vec4(sum / max(w0 + w1 + w2 + w3 + w4, 1e-4), 1.0);\n}\n";
+export declare const BLOOM_PREFILTER_FRAG = "#version 300 es\nprecision highp float;\n\nin vec2 vUv;\n\nuniform sampler2D uSource;\n/** One source texel in UV. The thirteen taps are laid out in source texels. */\nuniform vec2 uTexel;\n/** In scene units. 1.0 is \"brighter than white\", which is the useful place to start. */\nuniform float uThreshold;\n/**\n * Scene units over which a colour comes in past the threshold, or 0 to subtract the threshold\n * instead. See `BloomResponse.ramp`.\n */\nuniform float uRamp;\n\nout vec4 fragColor;\n\n/**\n * A ceiling on what any one pixel may contribute, well above anything a scene means.\n *\n * Not a look control. A half-float target can hold an infinity, and an infinity through the\n * threshold below is inf/inf, which is a NaN that the chain then spreads across the whole\n * frame \u2014 the one failure mode where a post pass destroys the picture rather than degrading\n * it. Anything above this is indistinguishable after the tone curve anyway.\n */\nconst float BLOOM_CEILING = 256.0;\n\nfloat brightness(vec3 c) {\n  return max(c.r, max(c.g, c.b));\n}\n\nvec3 fetch(vec2 uv) {\n  vec3 c = min(textureLod(uSource, uv, 0.0).rgb, vec3(BLOOM_CEILING));\n  float bright = brightness(c);\n  /* A ramp keeps a share of the colour, all of it a ramp's width past the line. */\n  if (uRamp > 0.0) return c * clamp((bright - uThreshold) / uRamp, 0.0, 1.0);\n  return c * (max(bright - uThreshold, 0.0) / max(bright, 1e-4));\n}\n\n/** How much a box counts for. A runaway pixel drags its box's brightness up and its weight down. */\nfloat firefly(vec3 c) {\n  return 1.0 / (1.0 + brightness(c));\n}\n\nvoid main() {\n\n  vec2 t = uTexel;\n  vec3 a = fetch(vUv + vec2(-2.0,  2.0) * t);\n  vec3 b = fetch(vUv + vec2( 0.0,  2.0) * t);\n  vec3 c = fetch(vUv + vec2( 2.0,  2.0) * t);\n  vec3 d = fetch(vUv + vec2(-2.0,  0.0) * t);\n  vec3 e = fetch(vUv);\n  vec3 f = fetch(vUv + vec2( 2.0,  0.0) * t);\n  vec3 g = fetch(vUv + vec2(-2.0, -2.0) * t);\n  vec3 h = fetch(vUv + vec2( 0.0, -2.0) * t);\n  vec3 i = fetch(vUv + vec2( 2.0, -2.0) * t);\n  vec3 j = fetch(vUv + vec2(-1.0,  1.0) * t);\n  vec3 k = fetch(vUv + vec2( 1.0,  1.0) * t);\n  vec3 l = fetch(vUv + vec2(-1.0, -1.0) * t);\n  vec3 m = fetch(vUv + vec2( 1.0, -1.0) * t);\n\n  vec3 box0 = (a + b + d + e) * 0.25;\n  vec3 box1 = (b + c + e + f) * 0.25;\n  vec3 box2 = (d + e + g + h) * 0.25;\n  vec3 box3 = (e + f + h + i) * 0.25;\n  vec3 box4 = (j + k + l + m) * 0.25;\n\n  float w0 = firefly(box0) * 0.125;\n  float w1 = firefly(box1) * 0.125;\n  float w2 = firefly(box2) * 0.125;\n  float w3 = firefly(box3) * 0.125;\n  float w4 = firefly(box4) * 0.5;\n  vec3 sum = box0 * w0 + box1 * w1 + box2 * w2 + box3 * w3 + box4 * w4;\n  fragColor = vec4(sum / max(w0 + w1 + w2 + w3 + w4, 1e-4), 1.0);\n}\n";
 /**
  * Stage two: halve what is already thresholded, once per level.
  *
@@ -58,7 +60,9 @@ export declare const BLOOM_DOWNSAMPLE_FRAG = "#version 300 es\nprecision highp f
 /**
  * Stage three: a 3x3 tent, added into the level above.
  *
- * **Additive rather than a mix, and each octave counts the same.** A lone bright pixel arrives
+ * **Additive rather than a mix, and each octave counts the same** unless a tint says otherwise:
+ * the level being added onto is multiplied by its own tint as it is, by the blend, and the deepest
+ * by `uScale` on the first draw. White everywhere is exactly the sum. A lone bright pixel arrives
  * at level n divided by four to the n, spread over four to the n pixels, so summing the levels
  * lifts its own pixel by about a third and lays a long shallow tail around it. That falloff is
  * what a real glare looks like; a single gaussian gives a disc with an end to it.
@@ -67,4 +71,4 @@ export declare const BLOOM_DOWNSAMPLE_FRAG = "#version 300 es\nprecision highp f
  * level and on every display. A tent rather than a box because the seams between the four
  * texels a bilinear upsample reads are otherwise visible as a grid on a wide, faint halo.
  */
-export declare const BLOOM_UPSAMPLE_FRAG = "#version 300 es\nprecision highp float;\n\nin vec2 vUv;\n\nuniform sampler2D uSource;\n/** How far the tent reaches, in UV. One number for the whole chain. */\nuniform float uRadius;\n\nout vec4 fragColor;\n\nvoid main() {\n  float r = uRadius;\n  vec3 a = textureLod(uSource, vUv + vec2(-r,  r), 0.0).rgb;\n  vec3 b = textureLod(uSource, vUv + vec2(0.0, r), 0.0).rgb;\n  vec3 c = textureLod(uSource, vUv + vec2( r,  r), 0.0).rgb;\n  vec3 d = textureLod(uSource, vUv + vec2(-r, 0.0), 0.0).rgb;\n  vec3 e = textureLod(uSource, vUv, 0.0).rgb;\n  vec3 f = textureLod(uSource, vUv + vec2( r, 0.0), 0.0).rgb;\n  vec3 g = textureLod(uSource, vUv + vec2(-r, -r), 0.0).rgb;\n  vec3 h = textureLod(uSource, vUv + vec2(0.0, -r), 0.0).rgb;\n  vec3 i = textureLod(uSource, vUv + vec2( r, -r), 0.0).rgb;\n\n  vec3 sum = e * 4.0 + (b + d + f + h) * 2.0 + (a + c + g + i);\n  fragColor = vec4(sum * 0.0625, 1.0);\n}\n";
+export declare const BLOOM_UPSAMPLE_FRAG = "#version 300 es\nprecision highp float;\n\nin vec2 vUv;\n\nuniform sampler2D uSource;\n/**\n * What the level being read is multiplied by: its tint, on the first draw up from the deepest\n * level, and white on every other \u2014 each other level's tint is applied to the level below as it\n * is added onto, by the blend. See `BloomResponse.tints`.\n */\nuniform vec3 uScale;\n/** How far the tent reaches, in UV. One number for the whole chain. */\nuniform float uRadius;\n\nout vec4 fragColor;\n\nvoid main() {\n  float r = uRadius;\n  vec3 a = textureLod(uSource, vUv + vec2(-r,  r), 0.0).rgb;\n  vec3 b = textureLod(uSource, vUv + vec2(0.0, r), 0.0).rgb;\n  vec3 c = textureLod(uSource, vUv + vec2( r,  r), 0.0).rgb;\n  vec3 d = textureLod(uSource, vUv + vec2(-r, 0.0), 0.0).rgb;\n  vec3 e = textureLod(uSource, vUv, 0.0).rgb;\n  vec3 f = textureLod(uSource, vUv + vec2( r, 0.0), 0.0).rgb;\n  vec3 g = textureLod(uSource, vUv + vec2(-r, -r), 0.0).rgb;\n  vec3 h = textureLod(uSource, vUv + vec2(0.0, -r), 0.0).rgb;\n  vec3 i = textureLod(uSource, vUv + vec2( r, -r), 0.0).rgb;\n\n  vec3 sum = e * 4.0 + (b + d + f + h) * 2.0 + (a + c + g + i);\n  fragColor = vec4(sum * 0.0625 * uScale, 1.0);\n}\n";