@driftengine/core 4.8.5 → 4.8.7

package/dist/render/clusteredLights.js

@@ -84,7 +84,7 @@ export const MAX_CLUSTERED_LIGHTS = 320;
  * it cannot. That is what lets a light index the shadow uniforms by a number read from a texture,
  * and it is the same fact the octahedral array texture was built on.
  */
-export const LIGHT_TEXELS = 5;
+export const LIGHT_TEXELS = 6;
 /**
  * Where each field of a light's record sits, as an offset in `uint`s from `lightBase`.
  *
@@ -114,7 +114,11 @@ export const LIGHT_TEXELS = 5;
  * **Reordered 2026-10-02 so a plain light's fields are the first eight**, which is what lets the
  * shader stop after two texels. Nine values are needed by every light and eight fit in two
  * texels, so the emitter size and the weight share slot 7 as two halves; see `packSizeAndWeight`.
- * Slot 19 is spare.
+ *
+ * **A sixth texel arrived in 4.8.7 for a light's own falloff exponent**, the fifth's last slot
+ * having gone to the channels: 6 KB more of a table near 300, read only for a light whose record
+ * carries a fixture, which a light with an exponent does. Slots 21 and 22 are a rectangle's barn
+ * doors and spare on a lamp; slot 23 is spare.
  */
 export const LIGHT_RECORD = {
     positionX: 0,
@@ -139,11 +143,43 @@ export const LIGHT_RECORD = {
     iesAxisX: 16,
     iesAxisY: 17,
     iesAxisZ: 18,
+    /**
+     * The light's lighting channels, a mask (`PointLightSet.lightChannels`), in the slot that was
+     * spare. A light naming channels other than the default is read as carrying a fixture, so its
+     * last texels are fetched; a plain light's are not, and the shader takes the default for it.
+     */
+    channels: 19,
+    /** The light's own falloff exponent, or 0 for the frame's falloff. `PointLightSource.falloffExponent`. */
+    falloffExponent: 20,
+    /** A rectangle's barn doors: the cosine of their angle from its normal, then their length in metres. */
+    barnDoorCos: 21,
+    barnDoorLength: 22,
 };
+/** The lighting channel every light and every surface is on unless it says otherwise. */
+export const DEFAULT_LIGHT_CHANNELS = 1;
+/**
+ * A light's channels as the shader compares them: a whole mask from 1 to 255, or the default where
+ * none was named or what was named is not one. The froxel record and the uniform path both write
+ * this, so a light named badly is on channel 1 in both rather than on two different guesses.
+ */
+export function lightChannelsOf(value) {
+    if (value === undefined || !Number.isInteger(value) || value < 1 || value > 255) {
+        return DEFAULT_LIGHT_CHANNELS;
+    }
+    return value;
+}
+/**
+ * A light's own falloff exponent as the shader reads it: a positive finite number, or 0 for the
+ * frame's falloff where none was named or what was named is not one. The record and the uniform
+ * path both write this, so a light named badly falls off by the frame's rule in both.
+ */
+export function lightFalloffExponentOf(value) {
+    return value !== undefined && Number.isFinite(value) && value > 0 ? value : 0;
+}
 /** Texels the lit pass reads for a light whose record carries no fixture. */
 export const PLAIN_LIGHT_TEXELS = 2;
 /**
- * The bit of `sizeAndWeight` that says the record's last three texels hold something: the sign of
+ * The bit of `sizeAndWeight` that says the record's last four texels hold something: the sign of
  * the emitter size's half, which a size never needs.
  */
 export const LIGHT_FIXTURE_FLAG = 0x8000;
@@ -354,8 +390,14 @@ export function createClusterLightSet() {
  * radius in its place, an emitter as wide as the light reaches, which widened every lamp's
  * highlight on a specular surface on the clustered arm alone.
  */
-export function fillClusterLightSet(env, out) {
+export function fillClusterLightSet(env, out, 
+/** How many rectangles the fixed arm shades; the rest of the buffer is clustered. */
+areaFrom = 0) {
     out.count = Math.min(env.lightCount ?? 0, MAX_CLUSTERED_LIGHTS);
+    const areas = env.areaLights ?? null;
+    out.areas = areas;
+    out.areaFrom = areaFrom;
+    out.areaCount = Math.max(0, Math.min((areas?.count ?? 0) - areaFrom, MAX_CLUSTERED_LIGHTS - out.count));
     out.positions = env.lightPositions;
     out.colors = env.lightColors;
     out.radii = env.lightRadii;
@@ -366,6 +408,8 @@ export function fillClusterLightSet(env, out) {
     out.iesProfiles = env.lightIesProfiles;
     out.iesAxes = env.lightIesAxes;
     out.cookies = env.lightCookies;
+    out.channels = env.lightChannels;
+    out.falloffExponents = env.lightFalloffExponents;
     return out;
 }
 /*
@@ -410,20 +454,25 @@ function distanceSqToBounds(x, y, z, b) {
     return dx * dx + dy * dy + dz * dz;
 }
 /**
- * Whether a light's record needs its last three texels: it holds a shadow slot, a cone, a profile
- * or a cookie. Everything else is a plain light, read in `PLAIN_LIGHT_TEXELS`.
+ * Whether a light's record needs its last four texels: it holds a shadow slot, a cone, a profile,
+ * a cookie, channels of its own or a falloff exponent of its own. Everything else is a plain light, read in `PLAIN_LIGHT_TEXELS`.
  *
  * **`shadowSlots` is zero where the lit shader has no point shadows**, and both binners are handed
  * it that way: a slot is only read under `POINT_SHADOWS`, so a light holding one in a build without
  * them was paying for three texels the shader then ignored.
  */
 export function lightHasFixture(lights, light, shadowSlots) {
+    /* A rectangle's record always carries its axes and extents past the second texel. */
+    if (light >= lights.count)
+        return true;
     const cone = lights.coneCos;
     return (light < shadowSlots ||
         (cone?.[light * 2] ?? POINT_LIGHT_COS_INNER) !== POINT_LIGHT_COS_INNER ||
         (cone?.[light * 2 + 1] ?? POINT_LIGHT_COS_OUTER) !== POINT_LIGHT_COS_OUTER ||
         (lights.iesProfiles?.[light] ?? NO_IES_PROFILE) >= 0 ||
-        (lights.cookies?.[light] ?? NO_IES_PROFILE) >= 0);
+        (lights.cookies?.[light] ?? NO_IES_PROFILE) >= 0 ||
+        lightChannelsOf(lights.channels?.[light]) !== DEFAULT_LIGHT_CHANNELS ||
+        lightFalloffExponentOf(lights.falloffExponents?.[light]) > 0);
 }
 /**
  * The value of `uClustered` for a frame: 0 with clustering off, 1 when every light is plain, 2 when
@@ -459,6 +508,10 @@ export function clusteredMode(lights, count, shadowSlots) {
  * is a light without a map, which is what a scene with two hundred lamps has anyway.
  */
 export function writeLightRecord(lights, light, shadowSlots, out, at) {
+    if (light >= lights.count) {
+        writeAreaRecord(lights, light, out, at);
+        return;
+    }
     const directions = lights.directions;
     const cone = lights.coneCos;
     const axes = lights.iesAxes;
@@ -490,7 +543,72 @@ export function writeLightRecord(lights, light, shadowSlots, out, at) {
     out[at + LIGHT_RECORD.iesAxisX] = floatBits(axes?.[light * 3] ?? 0);
     out[at + LIGHT_RECORD.iesAxisY] = floatBits(axes?.[light * 3 + 1] ?? 0);
     out[at + LIGHT_RECORD.iesAxisZ] = floatBits(axes?.[light * 3 + 2] ?? 0);
-    out[at + 19] = 0;
+    out[at + LIGHT_RECORD.channels] = floatBits(lightChannelsOf(lights.channels?.[light]));
+    out[at + LIGHT_RECORD.falloffExponent] = floatBits(lightFalloffExponentOf(lights.falloffExponents?.[light]));
+    out[at + LIGHT_RECORD.barnDoorCos] = 0;
+    out[at + LIGHT_RECORD.barnDoorLength] = 0;
+    out[at + LIGHT_RECORD.barnDoorLength + 1] = 0;
+}
+/**
+ * Which rectangle of the area buffer clustered light `light` is, for a light past the point
+ * lights. See `ClusterLightSet.areas`.
+ */
+function areaSlot(lights, light) {
+    return (lights.areaFrom ?? 0) + light - lights.count;
+}
+/**
+ * A rectangle's record, which the shader tells from a lamp's by its **negative radius** — its
+ * reach, negated — and reads to its sixth texel: sidedness where a lamp keeps its shadow slot,
+ * the right axis where a spot keeps its direction, the half extents where its cone is, the up
+ * axis where the azimuth is, the channels, and the barn doors in the sixth. Never shadowed: a rectangle's occlusion is
+ * the fixed arm's, which is why the first `maxAreaLights` stay there.
+ */
+function writeAreaRecord(lights, light, out, at) {
+    const areas = lights.areas;
+    const a = areaSlot(lights, light);
+    const pos = areas?.positions;
+    const color = areas?.colors;
+    const right = areas?.right;
+    const up = areas?.up;
+    const sizes = areas?.sizes;
+    out[at + LIGHT_RECORD.positionX] = floatBits(pos?.[a * 3] ?? 0);
+    out[at + LIGHT_RECORD.positionY] = floatBits(pos?.[a * 3 + 1] ?? 0);
+    out[at + LIGHT_RECORD.positionZ] = floatBits(pos?.[a * 3 + 2] ?? 0);
+    out[at + LIGHT_RECORD.radius] = floatBits(-areaReach(lights, light));
+    out[at + LIGHT_RECORD.colorR] = floatBits(color?.[a * 3] ?? 0);
+    out[at + LIGHT_RECORD.colorG] = floatBits(color?.[a * 3 + 1] ?? 0);
+    out[at + LIGHT_RECORD.colorB] = floatBits(color?.[a * 3 + 2] ?? 0);
+    out[at + LIGHT_RECORD.sizeAndWeight] = packSizeAndWeight(0, 1, true);
+    out[at + LIGHT_RECORD.shadowSlot] = floatBits(areas?.twoSided[a] ?? 0);
+    out[at + LIGHT_RECORD.directionX] = floatBits(right?.[a * 3] ?? 1);
+    out[at + LIGHT_RECORD.directionY] = floatBits(right?.[a * 3 + 1] ?? 0);
+    out[at + LIGHT_RECORD.directionZ] = floatBits(right?.[a * 3 + 2] ?? 0);
+    out[at + LIGHT_RECORD.cosInner] = floatBits(sizes?.[a * 2] ?? 0);
+    out[at + LIGHT_RECORD.cosOuter] = floatBits(sizes?.[a * 2 + 1] ?? 0);
+    out[at + LIGHT_RECORD.iesProfile] = floatBits(NO_IES_PROFILE);
+    out[at + LIGHT_RECORD.cookie] = floatBits(NO_IES_PROFILE);
+    out[at + LIGHT_RECORD.iesAxisX] = floatBits(up?.[a * 3] ?? 0);
+    out[at + LIGHT_RECORD.iesAxisY] = floatBits(up?.[a * 3 + 1] ?? 1);
+    out[at + LIGHT_RECORD.iesAxisZ] = floatBits(up?.[a * 3 + 2] ?? 0);
+    out[at + LIGHT_RECORD.channels] = floatBits(DEFAULT_LIGHT_CHANNELS);
+    out[at + LIGHT_RECORD.falloffExponent] = 0;
+    out[at + LIGHT_RECORD.barnDoorCos] = floatBits(areas?.barnDoors?.[a * 2] ?? 0);
+    out[at + LIGHT_RECORD.barnDoorLength] = floatBits(areas?.barnDoors?.[a * 2 + 1] ?? 0);
+    out[at + LIGHT_RECORD.barnDoorLength + 1] = 0;
+}
+/** A clustered rectangle's reach, which its record carries negated. See `AreaLightSource.range`. */
+function areaReach(lights, light) {
+    const areas = lights.areas;
+    const a = areaSlot(lights, light);
+    const named = areas?.ranges?.[a] ?? 0;
+    if (named > 0)
+        return named;
+    const sizes = areas?.sizes;
+    return Math.hypot(sizes?.[a * 2] ?? 0, sizes?.[a * 2 + 1] ?? 0);
+}
+/** How many lights the table carries: the point lights and the clustered rectangles after them. */
+export function clusteredLightTotal(lights) {
+    return Math.min(lights.count + (lights.areaCount ?? 0), MAX_CLUSTERED_LIGHTS);
 }
 /**
  * Fill the table with this frame's light assignment, and answer how many lights it carried.
@@ -538,7 +656,7 @@ export function writeLightRecord(lights, light, shadowSlots, out, at) {
  * Fills a caller-owned table and allocates nothing.
  */
 export function buildLightClusters(lights, view, near, far, tanHalfFovY, aspect, table, shadowSlots) {
-    const count = Math.min(lights.count, MAX_CLUSTERED_LIGHTS);
+    const count = clusteredLightTotal(lights);
     /*
      * The whole cluster region, not just the counts.
      *
@@ -553,10 +671,14 @@ export function buildLightClusters(lights, view, near, far, tanHalfFovY, aspect,
     for (let k = 0; k <= CLUSTER_Z; k++)
         sliceDepths[k] = sliceNearDepth(k, near, far);
     for (let light = 0; light < count; light++) {
-        const x = lights.positions[light * 3] ?? 0;
-        const y = lights.positions[light * 3 + 1] ?? 0;
-        const z = lights.positions[light * 3 + 2] ?? 0;
-        const radius = lights.radii[light] ?? 0;
+        /* A rectangle past the lamps is placed by its centre and binned by its reach. */
+        const area = light >= lights.count;
+        const from = area ? (lights.areas?.positions ?? lights.positions) : lights.positions;
+        const slot = area ? areaSlot(lights, light) : light;
+        const x = from[slot * 3] ?? 0;
+        const y = from[slot * 3 + 1] ?? 0;
+        const z = from[slot * 3 + 2] ?? 0;
+        const radius = area ? areaReach(lights, light) : (lights.radii[light] ?? 0);
         /* The record, as the shader reads it. World space; see the note above. */
         writeLightRecord(lights, light, shadowSlots, table, lightBase(light));
         /* Column-major, as gl-matrix builds it. The view looks down -z, so depth is -vz. */
@@ -570,6 +692,39 @@ export function buildLightClusters(lights, view, near, far, tanHalfFovY, aspect,
         /* Entirely behind the camera, so no cluster can reach it. */
         if (depth + radius <= 0)
             continue;
+        /*
+         * **A spot is binned by its cone as well as its sphere.** A 10° spot reaching thirty metres
+         * touches every froxel its sphere does and lights a sliver of them, and a stage rigged with
+         * hundreds of such fixtures put every one of them in nearly every froxel near the floor: 313
+         * lights cost 11.7 ms of a 1600x900 frame. The cone is tested against each froxel's bounding
+         * sphere in view space, which is conservative, by the construction `coneBoxGap` describes.
+         */
+        const cosOuter = lights.coneCos?.[light * 2 + 1] ?? POINT_LIGHT_COS_OUTER;
+        const directions = lights.directions;
+        let coneCos = POINT_LIGHT_COS_OUTER;
+        let coneSin = 0;
+        let axisX = 0;
+        let axisY = 0;
+        let axisZ = 0;
+        if (!area && directions !== undefined && cosOuter > -1) {
+            const dx = directions[light * 3] ?? 0;
+            const dy = directions[light * 3 + 1] ?? 0;
+            const dz = directions[light * 3 + 2] ?? 0;
+            const ax = (view[0] ?? 0) * dx + (view[4] ?? 0) * dy + (view[8] ?? 0) * dz;
+            const ay = (view[1] ?? 0) * dx + (view[5] ?? 0) * dy + (view[9] ?? 0) * dz;
+            const az = -((view[2] ?? 0) * dx + (view[6] ?? 0) * dy + (view[10] ?? 0) * dz);
+            const length = Math.sqrt(ax * ax + ay * ay + az * az);
+            /* The shader measures the cone against the direction as given, so a long one is a wider
+               cone: `dot(L, d) >= c` is `dot(L, d / |d|) >= c / |d|`. */
+            if (length > 1e-6 && cosOuter / length > -1) {
+                coneCos = cosOuter / length;
+                coneSin = Math.sqrt(Math.max(0, 1 - coneCos * coneCos));
+                axisX = ax / length;
+                axisY = ay / length;
+                axisZ = az / length;
+            }
+        }
+        const spot = coneCos > -1;
         /*
          * The slices the sphere could possibly touch. The tiles are derived per slice, below.
          *
@@ -617,6 +772,10 @@ export function buildLightClusters(lights, view, near, far, tanHalfFovY, aspect,
                     sliceBounds(i, j, zNear, zFar, halfWNear, halfWFar, halfHNear, halfHFar, bounds);
                     if (distanceSqToBounds(vx, vy, depth, bounds) > radiusSq)
                         continue;
+                    if (spot &&
+                        coneBoxGap(vx, vy, depth, axisX, axisY, axisZ, coneCos, coneSin, bounds) > 0) {
+                        continue;
+                    }
                     insert(table, i + j * CLUSTER_X + k * CLUSTER_X * CLUSTER_Y, light, bounds);
                 }
             }
@@ -624,6 +783,48 @@ export function buildLightClusters(lights, view, near, far, tanHalfFovY, aspect,
     }
     return count;
 }
+/**
+ * How far a froxel lies outside a spot's cone, in metres, or a negative number where the cone
+ * reaches it: positive is a froxel the light cannot shade. Everything in view space with depth
+ * positive, as the binner holds it; `axis` is unit length and `cosA`, `sinA` are the outer cone's.
+ *
+ * **The froxel's bounding sphere against the infinite cone**, after Wronski's cone test for
+ * clustered spots. With `V` from the apex to the sphere's centre at an angle `θ` from the axis and
+ * `A` the cone's half-angle, the centre's distance from the cone is `|V| sin(θ − A)` — which is
+ * `cosA |V⊥| − (V·axis) sinA` — while `θ − A` is under a right angle, and `|V|` past it, where the
+ * nearest point of the cone is its apex. Inside the cone it is negative. So the gap is exact for
+ * the sphere, and the sphere holds the froxel: the test can only keep a light, never drop one the
+ * shader would draw. The apex case is what drops a froxel behind a spot whose sphere reaches it,
+ * which the formula alone underestimates.
+ *
+ * **What it gives up** is tightness at the near end of the frustum, where a froxel is a long thin
+ * box whose sphere is much larger than it: a spot grazing such a froxel is kept. **What would make
+ * it wrong** is a profile showing those near froxels hold the cost; testing the box's corners is
+ * the tight version, at eight dot products a pair.
+ *
+ * Exported so the conformance page can tell a disagreement at the cone's edge from a real one; the
+ * GPU binner writes the same arithmetic in WGSL.
+ */
+export function coneBoxGap(px, py, pz, axisX, axisY, axisZ, cosA, sinA, box) {
+    const b0 = box[0] ?? 0;
+    const b1 = box[1] ?? 0;
+    const b2 = box[2] ?? 0;
+    const b3 = box[3] ?? 0;
+    const b4 = box[4] ?? 0;
+    const b5 = box[5] ?? 0;
+    const ex = (b3 - b0) * 0.5;
+    const ey = (b4 - b1) * 0.5;
+    const ez = (b5 - b2) * 0.5;
+    const vx = (b0 + b3) * 0.5 - px;
+    const vy = (b1 + b4) * 0.5 - py;
+    const vz = (b2 + b5) * 0.5 - pz;
+    const along = vx * axisX + vy * axisY + vz * axisZ;
+    const lengthSq = vx * vx + vy * vy + vz * vz;
+    const across = Math.sqrt(Math.max(lengthSq - along * along, 0));
+    const reach = Math.sqrt(lengthSq);
+    const distance = along < -sinA * reach ? reach : cosA * across - along * sinA;
+    return distance - Math.sqrt(ex * ex + ey * ey + ez * ez);
+}
 /** An NDC coordinate to a tile index, clamped. */
 function tileOf(ndc, tiles) {
     const tile = Math.floor((ndc + 1) * 0.5 * tiles);

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

@@ -26,6 +26,8 @@ export interface FieldLight extends LightReach {
     readonly b: number;
     /** The emitter's physical radius, which widens its penumbra. */
     readonly sourceRadius: number;
+    /** Its own falloff exponent, overriding the frame's above zero. See `pointLightShape`. */
+    readonly falloffExponent?: number;
 }
 /**
  * Fill `light` and `direction`, `BRICK_TEXELS * 4` floats each, x fastest, for brick `brick`.

package/dist/render/driftLight/bake.js

@@ -66,7 +66,7 @@ export function sampleFieldLight(px, py, pz, lights, candidates, first, last, fa
         const dist = Math.hypot(dx, dy, dz);
         if (dist >= source.radius)
             continue;
-        const shape = pointLightShape(dist, source.radius, falloff);
+        const shape = pointLightShape(dist, source.radius, falloff, source.falloffExponent);
         if (shape <= 0)
             continue;
         const seen = distance === null

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

@@ -9,8 +9,10 @@
  *
  * Both of the renderer's falloffs: `smooth`, the default, is a linear ramp squared, reaching zero at
  * the radius; `inverseSquare` is physical, windowed so it still reaches zero at the radius, and
- * floored at ten centimetres so a surface touching a light is not infinitely bright.
+ * floored at ten centimetres so a surface touching a light is not infinitely bright. And a light's
+ * own, which overrides both: `(1 - (d/R)^2)^n` with no distance term, for an exponent `n` above zero
+ * (`PointLightSource.falloffExponent`).
  */
 export type PointLightFalloff = 'smooth' | 'inverseSquare';
 /** The shader's `shape` for an unshaped point light: no cone, no photometric profile. */
-export declare function pointLightShape(dist: number, radius: number, falloff: PointLightFalloff): number;
+export declare function pointLightShape(dist: number, radius: number, falloff: PointLightFalloff, exponent?: number): number;

package/dist/render/driftLight/falloff.js

@@ -9,10 +9,16 @@
  *
  * Both of the renderer's falloffs: `smooth`, the default, is a linear ramp squared, reaching zero at
  * the radius; `inverseSquare` is physical, windowed so it still reaches zero at the radius, and
- * floored at ten centimetres so a surface touching a light is not infinitely bright.
+ * floored at ten centimetres so a surface touching a light is not infinitely bright. And a light's
+ * own, which overrides both: `(1 - (d/R)^2)^n` with no distance term, for an exponent `n` above zero
+ * (`PointLightSource.falloffExponent`).
  */
 /** The shader's `shape` for an unshaped point light: no cone, no photometric profile. */
-export function pointLightShape(dist, radius, falloff) {
+export function pointLightShape(dist, radius, falloff, exponent = 0) {
+    if (exponent > 0) {
+        const reach = dist / Math.max(radius, 1e-4);
+        return Math.min(1, Math.max(0, 1 - reach * reach)) ** exponent;
+    }
     if (falloff === 'inverseSquare') {
         const ratio = dist / Math.max(radius, 1e-4);
         const window = Math.min(1, Math.max(0, 1 - ratio ** 4));

package/dist/render/fixtureAtlas.js

@@ -12,7 +12,7 @@
  * only ever reaches forward — to the next plane, and from the last to the repeat of the first — so
  * past its last row it meets the texture's edge and the clamp, never a cookie. A cookie's own
  * half-texel inset keeps it inside its band on both axes. The shader finds the bands from
- * `textureSize` and `uIesAtlasRows`, so the fold cost no uniform.
+ * `textureSize` and `uFixtureShape.x`, so the fold cost no uniform.
  *
  * **What it gives up**: every texel is four half floats where a profile needed one, a few kilobytes
  * a scene; and setting either table rebuilds the whole texture, which a consumer does once per set.

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

@@ -26,9 +26,10 @@ import type { PointLightSet } from '../lightBudget.ts';
 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.
+ * of its inner cone; the way it points and the cosine of its outer cone; and its own falloff
+ * exponent, 0 for the frame's, in a fourth row of its own (`PointLightSource.falloffExponent`).
  */
-export declare const BOUNCE_LIGHT_FLOATS = 12;
+export declare const BOUNCE_LIGHT_FLOATS = 16;
 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

@@ -21,14 +21,15 @@
  * 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';
+import { POINT_LIGHT_COS_INNER, POINT_LIGHT_COS_OUTER, lightFalloffExponentOf, } 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.
+ * of its inner cone; the way it points and the cosine of its outer cone; and its own falloff
+ * exponent, 0 for the frame's, in a fourth row of its own (`PointLightSource.falloffExponent`).
  */
-export const BOUNCE_LIGHT_FLOATS = 12;
+export const BOUNCE_LIGHT_FLOATS = 16;
 export function createBounceLights() {
     return new Float32Array(MAX_BOUNCE_LIGHTS * BOUNCE_LIGHT_FLOATS);
 }
@@ -60,6 +61,10 @@ export function resolveBounceLights(lights, out) {
         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;
+        out[at + 12] = lightFalloffExponentOf(lights.lightFalloffExponents?.[i]);
+        out[at + 13] = 0;
+        out[at + 14] = 0;
+        out[at + 15] = 0;
         count++;
     }
     return count;

package/dist/render/instanceCull.js

@@ -44,6 +44,18 @@ export function cullInstances(data, local, frustum, out) {
         out.tints[kept * 3] = tints[i * 3];
         out.tints[kept * 3 + 1] = tints[i * 3 + 1];
         out.tints[kept * 3 + 2] = tints[i * 3 + 2];
+        if (out.alphas !== undefined)
+            out.alphas[kept] = data.alphas?.[i] ?? 1;
+        const regions = data.lightmapRegions;
+        if (regions !== undefined && out.lightmapRegions !== undefined) {
+            for (let k = 0; k < 4; k++)
+                out.lightmapRegions[kept * 4 + k] = regions[i * 4 + k];
+        }
+        const cells = data.uvRegions;
+        if (cells !== undefined && out.uvRegions !== undefined) {
+            for (let k = 0; k < 4; k++)
+                out.uvRegions[kept * 4 + k] = cells[i * 4 + k];
+        }
         kept++;
     }
     out.count = kept;

package/dist/render/instances.d.ts

@@ -10,10 +10,11 @@
  * plant. This one carries a full transform, because a vehicle pitches and rolls on its suspension
  * and a yaw cannot say so.
  *
- * **What it gives up** is a matrix per instance where a scatter spends five floats: 76 bytes
+ * **What it gives up** is a matrix per instance where a scatter spends five floats: 80 bytes
  * against 44, and no wind. **What would make it wrong** is a caller wanting per-instance
- * anything else — an opacity, a morph weight — which wants another attribute, and the sixteen
- * WebGL2 guarantees are already spent.
+ * anything beyond an opacity and a texture cell — a morph weight, say — which wants another
+ * attribute, and the sixteen WebGL2 guarantees are already spent. The opacity rides the float the
+ * stride was padded with and the cell the matrix's bottom row, which is why neither costs a byte.
  */
 export interface MeshInstances {
     /**
@@ -30,6 +31,40 @@ export interface MeshInstances {
      * — the alternative is a second batch per colour, which is the thing this exists to avoid.
      */
     readonly tints: Float32Array;
+    /**
+     * One float each, the instance's opacity from 0 to 1, which a blended draw
+     * (`drawTranslucentInstanced`) multiplies into the batch's own. **Absent, or an instance past its
+     * end, is 1** — wholly opaque, which is what every instance was before 4.8.6.
+     *
+     * What lets one draw carry particles fading at different rates: without it a consumer drew a
+     * batch per opacity level, each a draw and a material of its own. It is the instance's twin of
+     * the per-vertex alpha lane (`MeshData.channel`), multiplied in where that lane is.
+     */
+    readonly alphas?: Float32Array;
+    /**
+     * Four floats each, the instance's region of its lightmap page: `[scaleU, scaleV, biasU, biasV]`,
+     * read by a draw whose material is a `lightmapModel` — instances of one mesh in one material sit
+     * in different regions of one page, each applied before the material's own region. **They ride
+     * the tint and the opacity**, which a lightmapped instance gives up (see `lightmap.ts`): where
+     * these are given, those are not read. **A lightmapped batch needs them**, since a bake is
+     * different light at each instance; one drawn without them reads its tints as its regions, and
+     * either mismatch is said once on the console.
+     */
+    readonly lightmapRegions?: Float32Array;
+    /**
+     * Four floats each, the instance's cell of its texture: `[scaleU, scaleV, offsetU, offsetV]`,
+     * applied to the mesh's coordinates before the material's own scale and offset, in every pass
+     * that reads them — so one draw carries particles in different cells of a flipbook, or props
+     * wearing different tiles of one atlas. **Absent, or past `count`, is the whole texture**,
+     * `[1, 1, 0, 0]`, which is what every instance read before 4.8.7.
+     *
+     * **It rides the matrix's bottom row**, which an instance's placement — a turn, a scale and a
+     * move — leaves at `[0, 0, 0, 1]`, and which every stage drawing an instance rebuilds as that.
+     * So a placement must be affine, as every placement of a solid object is; a projective one is
+     * drawn as its affine part. A culled batch (`cullInstances`) carries the cells only into a
+     * target that has the array.
+     */
+    readonly uvRegions?: Float32Array;
     /** How many instances the arrays hold. Fixed at creation; the buffers are sized from it. */
     readonly capacity: number;
     /** How many are live. The rest of the buffer is neither uploaded nor drawn. */
@@ -44,20 +79,21 @@ export interface MeshInstances {
  */
 export declare function createMeshInstances(capacity: number): MeshInstances;
 /**
- * Floats one instance occupies in the interleaved vertex buffer: sixteen of matrix, three of
- * tint, and one of padding.
+ * Floats one instance occupies in the interleaved vertex buffer: sixteen of matrix, the bottom row
+ * of which carries the texture cell, three of tint, and the opacity.
  *
- * **Padded to twenty so the stride is 80 bytes rather than 76.** A vertex buffer's stride must be
- * a multiple of four on both backends, which 76 already is — the padding is for the *attribute*
- * offsets: the tint sits at byte 64 and a three-float attribute ending at 76 leaves the next
- * instance's first column starting there, which is legal but puts every second instance on an
- * offset no driver aligns well. One wasted float an instance is 4 bytes against 76.
+ * **Twenty so the stride is 80 bytes rather than 76.** A vertex buffer's stride must be a multiple
+ * of four on both backends, which 76 already is — the twentieth float was padding for the
+ * *attribute* offsets: the tint sits at byte 64 and a three-float attribute ending at 76 leaves the
+ * next instance's first column starting there, which is legal but puts every second instance on an
+ * offset no driver aligns well. Since 4.8.6 it carries the instance's opacity, read with the tint
+ * as one four-float attribute, so the opacity cost no attribute and no byte.
  */
 export declare const INSTANCE_FLOATS = 20;
 /** Bytes one instance occupies. See `INSTANCE_FLOATS`. */
 export declare const INSTANCE_STRIDE: number;
 /**
- * Interleave `count` instances into `out`, matrix then tint, at `INSTANCE_FLOATS` apart.
+ * Interleave `count` instances into `out`, matrix, tint and opacity, at `INSTANCE_FLOATS` apart.
  *
  * **Interleaved rather than two buffers** so a batch's upload is one `writeBuffer` and an
  * instance's colour sits beside the matrix that places it. Shared by both backends, because

package/dist/render/instances.js

@@ -9,25 +9,27 @@ export function createMeshInstances(capacity) {
     return {
         models: new Float32Array(capacity * 16),
         tints: new Float32Array(capacity * 3),
+        alphas: new Float32Array(capacity).fill(1),
         capacity,
         count: 0,
     };
 }
 /**
- * Floats one instance occupies in the interleaved vertex buffer: sixteen of matrix, three of
- * tint, and one of padding.
+ * Floats one instance occupies in the interleaved vertex buffer: sixteen of matrix, the bottom row
+ * of which carries the texture cell, three of tint, and the opacity.
  *
- * **Padded to twenty so the stride is 80 bytes rather than 76.** A vertex buffer's stride must be
- * a multiple of four on both backends, which 76 already is — the padding is for the *attribute*
- * offsets: the tint sits at byte 64 and a three-float attribute ending at 76 leaves the next
- * instance's first column starting there, which is legal but puts every second instance on an
- * offset no driver aligns well. One wasted float an instance is 4 bytes against 76.
+ * **Twenty so the stride is 80 bytes rather than 76.** A vertex buffer's stride must be a multiple
+ * of four on both backends, which 76 already is — the twentieth float was padding for the
+ * *attribute* offsets: the tint sits at byte 64 and a three-float attribute ending at 76 leaves the
+ * next instance's first column starting there, which is legal but puts every second instance on an
+ * offset no driver aligns well. Since 4.8.6 it carries the instance's opacity, read with the tint
+ * as one four-float attribute, so the opacity cost no attribute and no byte.
  */
 export const INSTANCE_FLOATS = 20;
 /** Bytes one instance occupies. See `INSTANCE_FLOATS`. */
 export const INSTANCE_STRIDE = INSTANCE_FLOATS * 4;
 /**
- * Interleave `count` instances into `out`, matrix then tint, at `INSTANCE_FLOATS` apart.
+ * Interleave `count` instances into `out`, matrix, tint and opacity, at `INSTANCE_FLOATS` apart.
  *
  * **Interleaved rather than two buffers** so a batch's upload is one `writeBuffer` and an
  * instance's colour sits beside the matrix that places it. Shared by both backends, because
@@ -37,16 +39,29 @@ export const INSTANCE_STRIDE = INSTANCE_FLOATS * 4;
  * Writes nothing beyond `count`, and allocates nothing: `out` is the caller's staging array.
  */
 export function packInstances(instances, out) {
-    const { models, tints } = instances;
+    const { models, tints, alphas, lightmapRegions, uvRegions } = instances;
     const count = Math.min(instances.count, instances.capacity);
     for (let i = 0; i < count; i += 1) {
         const at = i * INSTANCE_FLOATS;
         const m = i * 16;
         for (let c = 0; c < 16; c += 1)
             out[at + c] = models[m + c];
+        /* The texture cell in the bottom row an affine placement leaves free. See `uvRegions`. */
+        const cell = i * 4;
+        out[at + 3] = uvRegions?.[cell] ?? 1;
+        out[at + 7] = uvRegions?.[cell + 1] ?? 1;
+        out[at + 11] = uvRegions?.[cell + 2] ?? 0;
+        out[at + 15] = uvRegions?.[cell + 3] ?? 0;
+        if (lightmapRegions !== undefined) {
+            /* The region in the tint's and the opacity's place. See `lightmapRegions`. */
+            for (let c = 0; c < 4; c += 1)
+                out[at + 16 + c] = lightmapRegions[i * 4 + c];
+            continue;
+        }
         const t = i * 3;
         out[at + 16] = tints[t];
         out[at + 17] = tints[t + 1];
         out[at + 18] = tints[t + 2];
+        out[at + 19] = alphas?.[i] ?? 1;
     }
 }