@driftengine/core 4.8.5 → 4.8.6

package/dist/render/particlePool.d.ts

@@ -36,6 +36,17 @@ 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;
 }

package/dist/render/particlePool.js

@@ -9,6 +9,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/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/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";

package/dist/render/shaders/bloom.js

@@ -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`.
  */
 /**
  * The thirteen taps every downsampling stage shares, decomposed into five overlapping boxes.
@@ -125,6 +127,11 @@ uniform sampler2D uSource;
 uniform vec2 uTexel;
 /** In scene units. 1.0 is "brighter than white", which is the useful place to start. */
 uniform float uThreshold;
+/**
+ * Scene units over which a colour comes in past the threshold, or 0 to subtract the threshold
+ * instead. See \`BloomResponse.ramp\`.
+ */
+uniform float uRamp;
 
 out vec4 fragColor;
 
@@ -141,6 +148,8 @@ ${BLOOM_BRIGHTNESS}
 vec3 fetch(vec2 uv) {
   vec3 c = min(textureLod(uSource, uv, 0.0).rgb, vec3(BLOOM_CEILING));
   float bright = brightness(c);
+  /* A ramp keeps a share of the colour, all of it a ramp's width past the line. */
+  if (uRamp > 0.0) return c * clamp((bright - uThreshold) / uRamp, 0.0, 1.0);
   return c * (max(bright - uThreshold, 0.0) / max(bright, 1e-4));
 }
 
@@ -189,7 +198,9 @@ ${BLOOM_BOXES}
 /**
  * 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.
@@ -204,6 +215,12 @@ precision highp float;
 in vec2 vUv;
 
 uniform sampler2D uSource;
+/**
+ * What the level being read is multiplied by: its tint, on the first draw up from the deepest
+ * level, and white on every other — each other level's tint is applied to the level below as it
+ * is added onto, by the blend. See \`BloomResponse.tints\`.
+ */
+uniform vec3 uScale;
 /** How far the tent reaches, in UV. One number for the whole chain. */
 uniform float uRadius;
 
@@ -222,6 +239,6 @@ void main() {
   vec3 i = textureLod(uSource, vUv + vec2( r, -r), 0.0).rgb;
 
   vec3 sum = e * 4.0 + (b + d + f + h) * 2.0 + (a + c + g + i);
-  fragColor = vec4(sum * 0.0625, 1.0);
+  fragColor = vec4(sum * 0.0625 * uScale, 1.0);
 }
 `;

package/dist/render/shaders/flat/areaLight.d.ts

@@ -0,0 +1,10 @@
+/**
+ * One rectangle's light on a fragment: its form factor, and what it adds once its occlusion is
+ * known. **The one statement of it**, called by the fixed loop over the first `maxAreaLights`
+ * rectangles and by the froxel table's for the rest, so the two arms shade a rectangle with one
+ * body rather than two transcriptions of it — the zero-pixel gate between them means something
+ * only if that is so.
+ *
+ * Depth zero and after the models, whose `modelLight` it calls; see `flatFrag`.
+ */
+export declare const AREA_LIGHT_GLSL = "\n/**\n * The rectangle's signed form factor at this fragment: its corners **wound so a surface on the\n * emitting side sees them counter-clockwise**, which is what makes it positive there. The natural\n * order \u2014 minus, plus, plus, minus \u2014 winds the other way, and every one-sided light then clamped to\n * zero and the frame was black. The sign is the sidedness: a one-sided rectangle takes the positive\n * part and a two-sided one the magnitude.\n */\nfloat areaSignedForm(vec3 n, vec3 centre, vec3 right, vec3 up, vec2 halfSize) {\n  vec3 c0 = centre - right * halfSize.x + up * halfSize.y;\n  vec3 c1 = centre + right * halfSize.x + up * halfSize.y;\n  vec3 c2 = centre + right * halfSize.x - up * halfSize.y;\n  vec3 c3 = centre - right * halfSize.x - up * halfSize.y;\n  return quadFormFactor(n, vWorldPos, c0, c1, c2, c3);\n}\n\n/**\n * What one rectangle of colour `color` and form factor `form` adds to the lamps' two sums, open\n * and shadowed by `occl` and `glass`.\n *\n * **A model answers a rectangle as it answers a lamp at its centre**, carried at the rectangle's\n * own energy: the diffuse by the exact form factor over the centre's cosine, the specular by the\n * form factor. An approximation, stated: a model's lobe is not integrated over the rectangle as the\n * standard lobe is, so a glossy model under a large softbox shows a lobe from its centre rather than\n * its shape.\n *\n * **The standard lobe is integrated over the rectangle**, rather than sampled at one point on it.\n * What stood here once handed the closest point on the rectangle to `sphereLobe` and scaled it by\n * `form`, the *diffuse* form factor. Measured against a brute-force integral by\n * `scripts/areaSpecular.mjs`, that lost the reflection rather than blurring it: on polished metal\n * facing a softbox it returned 0.000233 where the integral is 0.9207, and head-on on a rough surface\n * it was 3.7 times too bright. Worst 287% either way; this is 40.1% where the light is what the\n * surface reflects and 79.0% for one overhead. `quadCoverage` says what fraction of the specular\n * lobe the rectangle covers and the environment BRDF says how much the surface returns, the split\n * the probe path uses. **`dfg.x + dfg.y` and not `envSpecularEnergy`**, deliberately: the\n * compensation returns the multiply-scattered share, and every direct lobe in this shader is\n * single-scattering, so adding it here returns energy the light never had. Measured at 211%\n * against 40.1%.\n */\nvoid areaLightAdd(\n  vec3 centre,\n  vec3 right,\n  vec3 up,\n  vec2 halfSize,\n  vec3 color,\n  float form,\n  float occl,\n  vec3 glass,\n  vec3 n,\n  vec3 albedo,\n  float metal,\n  vec3 specColor,\n  float roughness,\n  bool modelled,\n  inout vec3 lampOpen,\n  inout vec3 lampShadowed\n) {\n  if (modelled) {\n    vec3 areaL = normalize(centre - vWorldPos);\n    modelLight(areaL, 0.0, 0.0);\n    vec3 areaModel = (mDiffuse * (form / max(dot(n, areaL), 1e-3)) + mSpecular * form) * color;\n    lampOpen += areaModel;\n    lampShadowed += areaModel * occl * glass;\n    return;\n  }\n  /* Held back with the point lamps', and shadowed by the same term it always was. */\n  vec3 areaDiffuse = albedo * color * form * (1.0 - metal);\n  lampOpen += areaDiffuse;\n  lampShadowed += areaDiffuse * occl * glass;\n\n  if (vSpecular > 0.0 || metal > 0.0) {\n    vec3 c0 = centre - right * halfSize.x + up * halfSize.y;\n    vec3 c1 = centre + right * halfSize.x + up * halfSize.y;\n    vec3 c2 = centre + right * halfSize.x - up * halfSize.y;\n    vec3 c3 = centre - right * halfSize.x - up * halfSize.y;\n    vec3 toEyeArea = normalize(uCameraPos - vWorldPos);\n    float coverage = quadCoverage(n, vWorldPos, toEyeArea, roughness, c0, c1, c2, c3);\n    if (coverage > 0.0) {\n      vec2 areaDfg = envBrdfApprox(max(dot(n, toEyeArea), 0.0), roughness);\n      vec3 areaSpec = specColor * areaDfg.x + vec3(areaDfg.y);\n      vec3 areaHighlight = areaSpec * color * coverage;\n      lampOpen += areaHighlight;\n      lampShadowed += areaHighlight * occl * glass;\n    }\n  }\n}\n";

package/dist/render/shaders/flat/areaLight.js

@@ -0,0 +1,96 @@
+/**
+ * One rectangle's light on a fragment: its form factor, and what it adds once its occlusion is
+ * known. **The one statement of it**, called by the fixed loop over the first `maxAreaLights`
+ * rectangles and by the froxel table's for the rest, so the two arms shade a rectangle with one
+ * body rather than two transcriptions of it — the zero-pixel gate between them means something
+ * only if that is so.
+ *
+ * Depth zero and after the models, whose `modelLight` it calls; see `flatFrag`.
+ */
+export const AREA_LIGHT_GLSL = /* glsl */ `
+/**
+ * The rectangle's signed form factor at this fragment: its corners **wound so a surface on the
+ * emitting side sees them counter-clockwise**, which is what makes it positive there. The natural
+ * order — minus, plus, plus, minus — winds the other way, and every one-sided light then clamped to
+ * zero and the frame was black. The sign is the sidedness: a one-sided rectangle takes the positive
+ * part and a two-sided one the magnitude.
+ */
+float areaSignedForm(vec3 n, vec3 centre, vec3 right, vec3 up, vec2 halfSize) {
+  vec3 c0 = centre - right * halfSize.x + up * halfSize.y;
+  vec3 c1 = centre + right * halfSize.x + up * halfSize.y;
+  vec3 c2 = centre + right * halfSize.x - up * halfSize.y;
+  vec3 c3 = centre - right * halfSize.x - up * halfSize.y;
+  return quadFormFactor(n, vWorldPos, c0, c1, c2, c3);
+}
+
+/**
+ * What one rectangle of colour \`color\` and form factor \`form\` adds to the lamps' two sums, open
+ * and shadowed by \`occl\` and \`glass\`.
+ *
+ * **A model answers a rectangle as it answers a lamp at its centre**, carried at the rectangle's
+ * own energy: the diffuse by the exact form factor over the centre's cosine, the specular by the
+ * form factor. An approximation, stated: a model's lobe is not integrated over the rectangle as the
+ * standard lobe is, so a glossy model under a large softbox shows a lobe from its centre rather than
+ * its shape.
+ *
+ * **The standard lobe is integrated over the rectangle**, rather than sampled at one point on it.
+ * What stood here once handed the closest point on the rectangle to \`sphereLobe\` and scaled it by
+ * \`form\`, the *diffuse* form factor. Measured against a brute-force integral by
+ * \`scripts/areaSpecular.mjs\`, that lost the reflection rather than blurring it: on polished metal
+ * facing a softbox it returned 0.000233 where the integral is 0.9207, and head-on on a rough surface
+ * it was 3.7 times too bright. Worst 287% either way; this is 40.1% where the light is what the
+ * surface reflects and 79.0% for one overhead. \`quadCoverage\` says what fraction of the specular
+ * lobe the rectangle covers and the environment BRDF says how much the surface returns, the split
+ * the probe path uses. **\`dfg.x + dfg.y\` and not \`envSpecularEnergy\`**, deliberately: the
+ * compensation returns the multiply-scattered share, and every direct lobe in this shader is
+ * single-scattering, so adding it here returns energy the light never had. Measured at 211%
+ * against 40.1%.
+ */
+void areaLightAdd(
+  vec3 centre,
+  vec3 right,
+  vec3 up,
+  vec2 halfSize,
+  vec3 color,
+  float form,
+  float occl,
+  vec3 glass,
+  vec3 n,
+  vec3 albedo,
+  float metal,
+  vec3 specColor,
+  float roughness,
+  bool modelled,
+  inout vec3 lampOpen,
+  inout vec3 lampShadowed
+) {
+  if (modelled) {
+    vec3 areaL = normalize(centre - vWorldPos);
+    modelLight(areaL, 0.0, 0.0);
+    vec3 areaModel = (mDiffuse * (form / max(dot(n, areaL), 1e-3)) + mSpecular * form) * color;
+    lampOpen += areaModel;
+    lampShadowed += areaModel * occl * glass;
+    return;
+  }
+  /* Held back with the point lamps', and shadowed by the same term it always was. */
+  vec3 areaDiffuse = albedo * color * form * (1.0 - metal);
+  lampOpen += areaDiffuse;
+  lampShadowed += areaDiffuse * occl * glass;
+
+  if (vSpecular > 0.0 || metal > 0.0) {
+    vec3 c0 = centre - right * halfSize.x + up * halfSize.y;
+    vec3 c1 = centre + right * halfSize.x + up * halfSize.y;
+    vec3 c2 = centre + right * halfSize.x - up * halfSize.y;
+    vec3 c3 = centre - right * halfSize.x - up * halfSize.y;
+    vec3 toEyeArea = normalize(uCameraPos - vWorldPos);
+    float coverage = quadCoverage(n, vWorldPos, toEyeArea, roughness, c0, c1, c2, c3);
+    if (coverage > 0.0) {
+      vec2 areaDfg = envBrdfApprox(max(dot(n, toEyeArea), 0.0), roughness);
+      vec3 areaSpec = specColor * areaDfg.x + vec3(areaDfg.y);
+      vec3 areaHighlight = areaSpec * color * coverage;
+      lampOpen += areaHighlight;
+      lampShadowed += areaHighlight * occl * glass;
+    }
+  }
+}
+`;

package/dist/render/shaders/flat/index.js

@@ -15,6 +15,8 @@ import { SKINNING_GLSL } from '../skinning.js';
 import { SURFACE_GLSL } from './surface.js';
 import { MAIN_GLSL } from './main.js';
 import { MODELS_GLSL } from './models.js';
+import { AREA_LIGHT_GLSL } from './areaLight.js';
+import { NORMAL_MAP_GLSL } from './normalMap.js';
 import { DRIFT_LIGHT_GLSL } from './driftLight.js';
 import { SURFACE_EFFECTS_GLSL } from './surfaceEffects.js';
 import { CHANNEL_ATTRIBUTE, CHANNEL_BEND } from '../vertexChannel.js';
@@ -106,7 +108,17 @@ layout(location = 11) in vec4 aInstanceModel0;
 layout(location = 12) in vec4 aInstanceModel1;
 layout(location = 13) in vec4 aInstanceModel2;
 layout(location = 14) in vec4 aInstanceModel3;
-layout(location = 15) in vec3 aInstanceTint;
+/**
+ * The instance's tint, and its opacity in w: \`MeshInstances.alphas\`, 1 where none was given — or,
+ * in a lightmapped batch's pipeline, its region of the page (\`MeshInstances.lightmapRegions\`).
+ */
+layout(location = 15) in vec4 aInstanceTint;
+/*
+ * On in the pipeline a lightmapped material draws an instanced batch with, where the lane above is
+ * a region and not a tint: the second coordinates leave scaled and offset by it, under a tint and an
+ * opacity of one. See lightmap.ts.
+ */
+const bool LIGHTMAP_REGIONS = false; // wgsl:override
 #else
 uniform mat4 uModel;
 /**
@@ -232,7 +244,8 @@ void main() {
 #endif
 #if INSTANCED
   mat4 model = mat4(aInstanceModel0, aInstanceModel1, aInstanceModel2, aInstanceModel3);
-  vec3 tint = aInstanceTint;
+  vec3 tint = aInstanceTint.rgb;
+  if (LIGHTMAP_REGIONS) tint = vec3(1.0);
 #else
   mat4 model = uModel;
   vec3 tint = uTint;
@@ -286,10 +299,19 @@ void main() {
   vRelief = aRelief;
   vTangent = vec4(worldTangent, aTangent.w);
 #if INSTANCED
-  /* No channel on this path; the neutral values are what every mesh read before it existed. */
+  /*
+   * No channel on this path; the neutral values are what every mesh read before it existed — but
+   * for the opacity, which an instance carries of its own, 1 where none was given.
+   */
   vSkyDirect = 1.0;
-  vAlpha = 1.0;
+  vAlpha = aInstanceTint.w;
   vThickness = 1.0;
+  if (LIGHTMAP_REGIONS) {
+    /* Out of the lane's \`-1 - uv\`, through the region, and back into it. See lightmap.ts. */
+    vGrain = -1.0 - ((-1.0 - aGrain) * aInstanceTint.x + aInstanceTint.z);
+    vRelief = -1.0 - ((-1.0 - aRelief) * aInstanceTint.y + aInstanceTint.w);
+    vAlpha = 1.0;
+  }
 #else
   vSkyDirect = aChannel.y;
   vAlpha = aChannel.z;
@@ -426,6 +448,8 @@ export function flatFrag(options) {
          * and `main` is unconditional by construction.
          */
         TANGENT_FRAME_GLSL,
+        /* After the frame it calls, unconditional for the same reason. See normalMap.ts. */
+        NORMAL_MAP_GLSL,
         /* Unconditional for the same reason, and called only where a cutoff was asked for. */
         CUTOUT_COVERAGE_GLSL,
         CUTOUT_DITHER_GLSL,
@@ -433,6 +457,8 @@ export function flatFrag(options) {
         SURFACE_EFFECTS_GLSL,
         /* Depth zero and after the tangent frame and the lobes it calls; see models.ts. */
         MODELS_GLSL,
+        /* After the models, whose answer to a rectangle it asks for. See areaLight.ts. */
+        AREA_LIGHT_GLSL,
         MAIN_GLSL,
     ].join('\n'), {
         POINT_SHADOWS: options.pointShadows,