@driftengine/core 4.7.2 → 4.7.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/core",
-  "version": "4.7.2",
+  "version": "4.7.3",
   "description": "The runtime of DriftEngine, a WebGPU game engine with a WebGL2 fallback: renderer, loop, input, cameras, scene graph and physics",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,8 +29,8 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@driftengine/drft": "4.7.2",
-    "@driftengine/physics": "4.7.2",
+    "@driftengine/drft": "4.7.3",
+    "@driftengine/physics": "4.7.3",
     "gl-matrix": "^3.4.3"
   },
   "author": "Drift Technologies",
@@ -67,8 +67,8 @@
     "prepack": "node ../../scripts/build.mjs @driftengine/core"
   },
   "devDependencies": {
-    "@driftengine/nav": "4.7.2",
-    "@driftengine/network": "4.7.2",
-    "@driftengine/texture": "4.7.2"
+    "@driftengine/nav": "4.7.3",
+    "@driftengine/network": "4.7.3",
+    "@driftengine/texture": "4.7.3"
   }
 }

package/src/render/backend/webgl2/renderer.ts

@@ -56,12 +56,13 @@ import { boundsVisible } from '../../visibility.ts';
 import { createPassRegistry, drainRegistry, passAt, registerIn, unregisterIn } from '../../pass.ts';
 import type { ComputeDefinition, ComputeHandle } from '../../compute.ts';
 import {
-  MAX_CLUSTERED_LIGHTS,
   TABLE_HEIGHT,
   TABLE_WIDTH,
   buildLightClusters,
+  clusteredMode,
+  createClusterLightSet,
   createClusterTable,
-  type ClusterLightSet,
+  fillClusterLightSet,
 } from '../../clusteredLights.ts';
 import type {
   PassContext,
@@ -2211,21 +2212,7 @@ export class WebGL2Renderer implements RendererApi {
   private clusterTexture: WebGLTexture | null = null;
   private clusterTable: Uint32Array | null = null;
   /** Refilled per frame; holds references and allocates nothing. See `resolvePointLights`. */
-  private readonly clusterLights: {
-    count: number;
-    positions: Float32Array;
-    colors: Float32Array;
-    radii: Float32Array;
-    sourceRadii: Float32Array;
-    weights: Float32Array;
-  } = {
-    count: 0,
-    positions: new Float32Array(0),
-    colors: new Float32Array(0),
-    radii: new Float32Array(0),
-    sourceRadii: new Float32Array(0),
-    weights: new Float32Array(0),
-  };
+  private readonly clusterLights = createClusterLightSet();
   /** near, far, tan(fovY/2), aspect — written per frame, uploaded as one vec4. */
   private readonly clusterFrustum = new Float32Array(4);
 
@@ -2378,15 +2365,11 @@ export class WebGL2Renderer implements RendererApi {
     gl.uniformMatrix4fv(u['uView'] ?? null, false, camera.view);
 
     this.clusterTable ??= createClusterTable();
-    const lights = this.clusterLights;
-    lights.count = Math.min(env.lightCount ?? 0, MAX_CLUSTERED_LIGHTS);
-    lights.positions = env.lightPositions;
-    lights.colors = env.lightColors;
-    lights.radii = env.lightRadii;
-    lights.sourceRadii = env.lightSourceRadii ?? env.lightRadii;
-    lights.weights = env.lightWeights;
+    const lights = fillClusterLightSet(env, this.clusterLights);
+    /* A slot is read only under `POINT_SHADOWS`; see `lightHasFixture`. */
+    const shadowSlots = this.quality.pointShadows ? this.lightBudget.maxLights : 0;
     buildLightClusters(
-      lights as ClusterLightSet,
+      lights,
       camera.view as Float32Array,
       near,
       far,
@@ -2400,8 +2383,9 @@ export class WebGL2Renderer implements RendererApi {
        * to name, and saying so here is what stops the shader having to discover it. The shader
        * guards the read as well, for a build that reaches it another way.
        */
-      this.lightBudget.maxLights,
+      shadowSlots,
     );
+    gl.uniform1i(u['uClustered'] ?? null, clusteredMode(lights, lights.count, shadowSlots));
     gl.texSubImage2D(
       gl.TEXTURE_2D,
       0,

package/src/render/backend/webgpu/clusterBinner.ts

@@ -1,14 +1,11 @@
 import {
   CLUSTER_COUNT,
-  LIGHT_RECORD,
   LIGHT_TEXELS,
-  NO_IES_PROFILE,
-  POINT_LIGHT_COS_INNER,
-  POINT_LIGHT_COS_OUTER,
   MAX_CLUSTERED_LIGHTS,
   TABLE_HEIGHT,
   TABLE_WIDTH,
   type ClusterLightSet,
+  writeLightRecord,
 } from '../../clusteredLights.ts';
 import { MAX_POINT_LIGHTS } from '../../lightBudget.ts';
 import type { ComputeContext, ComputeDefinition, ComputeDevice } from '../../compute.ts';
@@ -77,7 +74,8 @@ export class ClusterBinner {
   private readonly paramsStaging = new ArrayBuffer(PARAMS_BYTES);
   private readonly paramsFloats = new Float32Array(this.paramsStaging);
   private readonly paramsUints = new Uint32Array(this.paramsStaging);
-  private readonly lightStaging = new Float32Array(MAX_CLUSTERED_LIGHTS * LIGHT_TEXELS * 4);
+  /* The records as bits, because one slot holds two halves that must not pass through a float. */
+  private readonly lightStaging = new Uint32Array(MAX_CLUSTERED_LIGHTS * LIGHT_TEXELS * 4);
 
   private frame: ClusterBinnerFrame | null = null;
 
@@ -172,48 +170,17 @@ export class ClusterBinner {
     const count = Math.min(frame.lights.count, MAX_CLUSTERED_LIGHTS);
 
     /*
-     * The records, in exactly the order `buildLightClusters` writes them, because the shader
+     * The records, by the function `buildLightClusters` writes them with, because the shader
      * copies them into the table verbatim and the lit pass reads one layout on both backends.
      */
     for (let light = 0; light < count; light++) {
-      const at = light * LIGHT_TEXELS * 4;
-      this.lightStaging[at] = frame.lights.positions[light * 3] ?? 0;
-      this.lightStaging[at + 1] = frame.lights.positions[light * 3 + 1] ?? 0;
-      this.lightStaging[at + 2] = frame.lights.positions[light * 3 + 2] ?? 0;
-      this.lightStaging[at + 3] = frame.lights.radii[light] ?? 0;
-      this.lightStaging[at + 4] = frame.lights.colors[light * 3] ?? 0;
-      this.lightStaging[at + 5] = frame.lights.colors[light * 3 + 1] ?? 0;
-      this.lightStaging[at + 6] = frame.lights.colors[light * 3 + 2] ?? 0;
-      this.lightStaging[at + 7] = frame.lights.sourceRadii[light] ?? 0;
-      this.lightStaging[at + LIGHT_RECORD.weight] = frame.lights.weights[light] ?? 1;
-      this.lightStaging[at + LIGHT_RECORD.shadowSlot] = light < frame.shadowSlots ? light : -1;
-      /*
-       * The cone, addressed through `LIGHT_RECORD` rather than by number. Two writers fill this
-       * record — the CPU binner in `clusteredLights.ts` and this — and the 2026-08-17 rule is that
-       * two implementations of one decision drift invisibly when the constants are identical. They
-       * now read the same table of offsets, so a field can only move in both at once.
-       *
-       * `POINT_LIGHT_COS_OUTER` and its inner twin are what make a light with no cone collapse to
-       * exactly the arithmetic a point light had. `scripts/cluster-check.mjs` compares the two
-       * tables byte for byte and is what would catch this being wrong anyway.
-       */
-      const directions = frame.lights.directions;
-      const cone = frame.lights.coneCos;
-      this.lightStaging[at + LIGHT_RECORD.directionX] = directions?.[light * 3] ?? 0;
-      this.lightStaging[at + LIGHT_RECORD.directionY] = directions?.[light * 3 + 1] ?? 0;
-      this.lightStaging[at + LIGHT_RECORD.directionZ] = directions?.[light * 3 + 2] ?? 0;
-      this.lightStaging[at + LIGHT_RECORD.cosInner] = cone?.[light * 2] ?? POINT_LIGHT_COS_INNER;
-      this.lightStaging[at + LIGHT_RECORD.cosOuter] =
-        cone?.[light * 2 + 1] ?? POINT_LIGHT_COS_OUTER;
-      this.lightStaging[at + LIGHT_RECORD.iesProfile] =
-        frame.lights.iesProfiles?.[light] ?? NO_IES_PROFILE;
-      /* The azimuth reference an asymmetric profile is oriented by; zero where a consumer gave
-         none, which the shader reads as no usable reference and leaves on the first plane. */
-      const axes = frame.lights.iesAxes;
-      this.lightStaging[at + LIGHT_RECORD.iesAxisX] = axes?.[light * 3] ?? 0;
-      this.lightStaging[at + LIGHT_RECORD.iesAxisY] = axes?.[light * 3 + 1] ?? 0;
-      this.lightStaging[at + LIGHT_RECORD.iesAxisZ] = axes?.[light * 3 + 2] ?? 0;
-      this.lightStaging[at + LIGHT_RECORD.cookie] = frame.lights.cookies?.[light] ?? NO_IES_PROFILE;
+      writeLightRecord(
+        frame.lights,
+        light,
+        frame.shadowSlots,
+        this.lightStaging,
+        light * LIGHT_TEXELS * 4,
+      );
     }
 
     this.paramsFloats.set(frame.view, 0);

package/src/render/backend/webgpu/renderer.ts

@@ -553,7 +553,11 @@ import { OcclusionBuffer } from '../../occlusion.ts';
 import { boundsVisible } from '../../visibility.ts';
 import { createPassRegistry, drainRegistry, passAt, registerIn, unregisterIn } from '../../pass.ts';
 import { ClusterBinner } from './clusterBinner.ts';
-import { MAX_CLUSTERED_LIGHTS, type ClusterLightSet } from '../../clusteredLights.ts';
+import {
+  clusteredMode,
+  createClusterLightSet,
+  fillClusterLightSet,
+} from '../../clusteredLights.ts';
 import {
   computeAt,
   createComputeRegistry,
@@ -5169,6 +5173,8 @@ export class WebGPURenderer implements RendererApi {
     iesProfiles: new Float32Array(0),
     iesAxes: new Float32Array(0),
     cookies: new Float32Array(0),
+    heldSourceRadii: new Float32Array(MAX_POINT_LIGHTS),
+    heldWeights: new Float32Array(MAX_POINT_LIGHTS),
   };
   /** Refilled per frame rather than allocated; see `resolveAtmosphere`. */
   private readonly medium: ResolvedAtmosphere = {
@@ -13548,21 +13554,7 @@ export class WebGPURenderer implements RendererApi {
   /** near, far, tan(fovY/2), aspect. Written per frame into the fragment block. */
   private readonly clusterFrustum = new Float32Array(4);
   /** Refilled per frame; holds references and allocates nothing. */
-  private readonly clusterLights: {
-    count: number;
-    positions: Float32Array;
-    colors: Float32Array;
-    radii: Float32Array;
-    sourceRadii: Float32Array;
-    weights: Float32Array;
-  } = {
-    count: 0,
-    positions: new Float32Array(0),
-    colors: new Float32Array(0),
-    radii: new Float32Array(0),
-    sourceRadii: new Float32Array(0),
-    weights: new Float32Array(0),
-  };
+  private readonly clusterLights = createClusterLightSet();
 
   /**
    * Reused per dispatch rather than allocated, for the reason `passContext` gives beside it: a
@@ -13662,21 +13654,18 @@ export class WebGPURenderer implements RendererApi {
     f[frustumAt + 3] = aspect;
     f.set(camera.view as Float32Array, at('uView'));
 
-    const set = this.clusterLights;
-    set.count = Math.min(env.lightCount ?? 0, MAX_CLUSTERED_LIGHTS);
-    set.positions = env.lightPositions;
-    set.colors = env.lightColors;
-    set.radii = env.lightRadii;
-    set.sourceRadii = env.lightSourceRadii ?? env.lightRadii;
-    set.weights = env.lightWeights;
+    const set = fillClusterLightSet(env, this.clusterLights);
+    /* A slot is read only under `POINT_SHADOWS`; see `lightHasFixture`. */
+    const shadowSlots = this.quality.pointShadows ? MAX_POINT_LIGHTS : 0;
+    i[at('uClustered')] = clusteredMode(set, set.count, shadowSlots);
     binner.setFrame({
-      lights: set as ClusterLightSet,
+      lights: set,
       view: camera.view as Float32Array,
       near,
       far,
       tanHalfFovY,
       aspect,
-      shadowSlots: MAX_POINT_LIGHTS,
+      shadowSlots,
     });
     this.dispatchCompute(this.clusterHandle);
   }

package/src/render/backend/webgpu/shaders/clusterBin.wgsl.ts

@@ -54,8 +54,12 @@ struct Params {
 }
 
 @group(0) @binding(0) var<uniform> params: Params;
-/** Three vec4s a light, in exactly the record order \`buildLightClusters\` writes. */
-@group(0) @binding(1) var<storage, read> lights: array<vec4<f32>>;
+/**
+ * The records as \`writeLightRecord\` lays them out, as bits. **\`u32\`, not \`f32\`**, because one
+ * slot holds two halves, and a zero weight read as a float would be a subnormal a GPU is free to
+ * flush on the way through; read as bits, the copy into the table cannot change them.
+ */
+@group(0) @binding(1) var<storage, read> lights: array<vec4<u32>>;
 /**
  * Write-only, which is all core WGSL offers and all the fixed-slot layout needs.
  *
@@ -81,7 +85,7 @@ fn distanceSqToBounds(p: vec3<f32>, lo: vec3<f32>, hi: vec3<f32>) -> f32 {
 
 /** A light's view-space centre, with depth positive along the view direction. */
 fn viewOf(light: u32) -> vec3<f32> {
-  let world = lights[light * LIGHT_TEXELS];
+  let world = bitcast<vec4<f32>>(lights[light * LIGHT_TEXELS]);
   let v = params.view * vec4<f32>(world.xyz, 1.0);
   return vec3<f32>(v.x, v.y, -v.z);
 }
@@ -113,7 +117,7 @@ fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
   if (id < params.lightCount) {
     let record = id * LIGHT_TEXELS;
     for (var t: u32 = 0u; t < LIGHT_TEXELS; t = t + 1u) {
-      textureStore(table, texelAt(record + t), bitcast<vec4<u32>>(lights[record + t]));
+      textureStore(table, texelAt(record + t), lights[record + t]);
     }
   }
 
@@ -157,7 +161,7 @@ fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
 
   /* Increasing light index, which is what makes the list sorted without a sort. */
   for (var light: u32 = 0u; light < params.lightCount; light = light + 1u) {
-    let radius = lights[light * LIGHT_TEXELS].w;
+    let radius = bitcast<f32>(lights[light * LIGHT_TEXELS].w);
     let v = viewOf(light);
     if (v.z + radius <= 0.0) {
       continue;

package/src/render/clusteredLights.ts

@@ -69,8 +69,16 @@ export const MAX_LIGHTS_PER_CLUSTER = (CLUSTER_TEXELS - 1) * 4;
 export const MAX_CLUSTERED_LIGHTS = 320;
 
 /**
- * Texels one light's record occupies: position and radius, colour and emitter size, then the
- * weight and the shadow slot.
+ * Texels one light's record occupies: position and radius, then colour with the emitter size and
+ * the weight, then the shadow slot and the fixture: direction, cone, profile, cookie and azimuth.
+ *
+ * **A plain point light is read in two of the five.** The lit pass fetches this record once per
+ * light per fragment, and at eight megapixels with lights crowded together that fetch is the
+ * frame: 320 lamps of radius 12 cost 26.2 ms of a 4K main pass when all five texels were read for
+ * every light, and 12.7 ms read in two, on the RX 9070 XT `demo/dev/clusterStress.html` was
+ * measured on. So the second texel carries a flag, `LIGHT_FIXTURE_FLAG`, and the last three are
+ * fetched only for a light that has a shadow slot, a cone, a profile or a cookie. What a plain light
+ * would have read there is what the shader assumes in their place, so the picture is the same.
  *
  * **The shadow slot is an index into the existing sixteen-wide shadow uniforms, not a layer.**
  * Clustering lifts how many lights *shade* a fragment; it does not lift how many shadow maps
@@ -109,6 +117,11 @@ export const LIGHT_TEXELS = 5;
  * rotating through that direction would snap its pattern round. The two obvious constructions put
  * that singularity where these fixtures actually point: `cross(worldUp, dir)` fails for a light
  * aimed straight down, which is a street light.
+ *
+ * **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.
  */
 export const LIGHT_RECORD = {
   positionX: 0,
@@ -118,23 +131,101 @@ export const LIGHT_RECORD = {
   colorR: 4,
   colorG: 5,
   colorB: 6,
-  sourceRadius: 7,
-  weight: 8,
-  shadowSlot: 9,
-  directionX: 10,
-  directionY: 11,
-  directionZ: 12,
-  cosInner: 13,
-  cosOuter: 14,
-  iesProfile: 15,
+  /** The emitter size and the weight, two halves in one word, and the fixture flag. */
+  sizeAndWeight: 7,
+  shadowSlot: 8,
+  directionX: 9,
+  directionY: 10,
+  directionZ: 11,
+  cosInner: 12,
+  cosOuter: 13,
+  iesProfile: 14,
+  /** A tile of the cookie atlas, or negative for none. */
+  cookie: 15,
   /** The fixture's azimuth zero, in world space. See the note above on why it cannot be derived. */
   iesAxisX: 16,
   iesAxisY: 17,
   iesAxisZ: 18,
-  /** A tile of the cookie atlas, or negative for none. Slot 19, the one the fifth texel spared. */
-  cookie: 19,
 } as const;
 
+/** 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 emitter size's half, which a size never needs.
+ */
+export const LIGHT_FIXTURE_FLAG = 0x8000;
+
+const halfScratch = new Float32Array(1);
+const halfScratchBits = new Uint32Array(halfScratch.buffer);
+
+/**
+ * A number as the sixteen bits of an IEEE half: rounded to the nearest, ties to even.
+ *
+ * **Computed here, once, and copied by both binners rather than converted on the GPU.** WGSL and
+ * GLSL both leave the rounding of `pack2x16float` to the implementation, and two producers of one
+ * table that round differently would make `scripts/cluster-check.mjs` compare noise.
+ *
+ * **A value only a subnormal half could hold is flushed to a signed zero.** A GPU may flush a
+ * subnormal it unpacks, and the fixed arm reads the same value from a uniform where nothing would;
+ * flushing it here means both arms read zero. Nothing is lost that a pixel could show: the largest
+ * value flushed is 6.1e-5, a weight no lamp is visible at.
+ */
+export function halfBits(value: number): number {
+  halfScratch[0] = value;
+  const x = halfScratchBits[0] ?? 0;
+  const sign = (x >>> 16) & 0x8000;
+  const exponent = (x >>> 23) & 0xff;
+  const mantissa = x & 0x7fffff;
+  if (exponent === 0xff) return sign | 0x7c00 | (mantissa === 0 ? 0 : 0x200);
+  const e = exponent - 127 + 15;
+  if (e >= 0x1f) return sign | 0x7c00;
+  if (e <= 0) return sign;
+  const truncated = (e << 10) | (mantissa >>> 13);
+  const rest = mantissa & 0x1fff;
+  /* A carry out of the mantissa lands in the exponent, which is the correct rounding up. */
+  const rounded =
+    rest > 0x1000 || (rest === 0x1000 && (truncated & 1) === 1) ? truncated + 1 : truncated;
+  return sign | rounded;
+}
+
+/** The number a half's bits hold. Exact: every half is also a float. */
+export function halfValue(half: number): number {
+  const sign = (half & 0x8000) === 0 ? 1 : -1;
+  const exponent = (half >>> 10) & 0x1f;
+  const mantissa = half & 0x3ff;
+  if (exponent === 0) return sign * mantissa * 2 ** -24;
+  if (exponent === 0x1f) return mantissa === 0 ? sign * Infinity : Number.NaN;
+  return sign * (1 + mantissa / 1024) * 2 ** (exponent - 15);
+}
+
+/**
+ * A lamp's emitter size as both arms read it: its magnitude, at half precision.
+ *
+ * **The fixed arm is rounded too, and that is what keeps the two arms one picture.**
+ * `resolvePointLights` passes the sixteen uniform lights through this and `lampWeight`, so a light
+ * moved from the uniform path to the froxel table shades with the same numbers. A negative size was
+ * never meaningful and now reads as its magnitude on both.
+ */
+export function lampSourceRadius(value: number): number {
+  return halfValue(halfBits(Math.abs(value)));
+}
+
+/** A lamp's weight as both arms read it: at half precision, sign kept. See `lampSourceRadius`. */
+export function lampWeight(value: number): number {
+  return halfValue(halfBits(value));
+}
+
+/**
+ * Slot 7 of a record: the emitter size's half in the low bits, the weight's in the high, and the
+ * fixture flag in the size's sign. The shader unpacks it with `unpackHalf2x16`, which is exact.
+ */
+export function packSizeAndWeight(sourceRadius: number, weight: number, fixture: boolean): number {
+  const size = halfBits(Math.abs(sourceRadius)) & 0x7fff;
+  return ((halfBits(weight) << 16) | size | (fixture ? LIGHT_FIXTURE_FLAG : 0)) >>> 0;
+}
+
 /**
  * The cone a light with no cone has: one that admits every direction, exactly.
  *
@@ -312,6 +403,71 @@ export interface ClusterLightSet {
   readonly iesProfiles?: Float32Array;
 }
 
+/** Where `fillClusterLightSet` reads a frame's lights from: the arrays `Environment` carries. */
+export interface ClusterLightArrays {
+  readonly lightCount?: number;
+  readonly lightPositions: Float32Array;
+  readonly lightColors: Float32Array;
+  readonly lightRadii: Float32Array;
+  readonly lightWeights: Float32Array;
+  readonly lightSourceRadii?: Float32Array;
+  readonly lightDirections?: Float32Array;
+  readonly lightConeCos?: Float32Array;
+  readonly lightIesProfiles?: Float32Array;
+  readonly lightIesAxes?: Float32Array;
+  readonly lightCookies?: Float32Array;
+}
+
+/** A `ClusterLightSet` a renderer refills every frame. */
+export type ClusterLightScratch = { -readonly [K in keyof ClusterLightSet]: ClusterLightSet[K] };
+
+/** No emitter size at all, which is what the fixed arm reads for a light that was given none. */
+const NO_SOURCE_SIZES = new Float32Array(0);
+
+export function createClusterLightSet(): ClusterLightScratch {
+  return {
+    count: 0,
+    positions: NO_SOURCE_SIZES,
+    colors: NO_SOURCE_SIZES,
+    radii: NO_SOURCE_SIZES,
+    sourceRadii: NO_SOURCE_SIZES,
+    weights: NO_SOURCE_SIZES,
+  };
+}
+
+/**
+ * A frame's lights as the binner reads them, in place, holding references and allocating nothing.
+ *
+ * **One assembly for both renderers, and it used to be two that had each dropped the same five
+ * fields.** Each backend copied the position, colour, radius, size and weight arrays and nothing
+ * else, so a spot's direction and cone, a profile, its axis and a cookie never reached the record:
+ * with clustering on, every fixture shaded as a bare point light. On a probe page holding one
+ * spot with a profile and a cookie the two arms differed by 357,706 pixels, the clustered one
+ * flooding the scene the cone was meant to cut. The record and both shaders were right throughout;
+ * the light never arrived.
+ *
+ * **And a light given no emitter size has none**, as the fixed arm reads it. This read the light's
+ * 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: ClusterLightArrays,
+  out: ClusterLightScratch,
+): ClusterLightSet {
+  out.count = Math.min(env.lightCount ?? 0, MAX_CLUSTERED_LIGHTS);
+  out.positions = env.lightPositions;
+  out.colors = env.lightColors;
+  out.radii = env.lightRadii;
+  out.sourceRadii = env.lightSourceRadii ?? NO_SOURCE_SIZES;
+  out.weights = env.lightWeights;
+  out.directions = env.lightDirections;
+  out.coneCos = env.lightConeCos;
+  out.iesProfiles = env.lightIesProfiles;
+  out.iesAxes = env.lightIesAxes;
+  out.cookies = env.lightCookies;
+  return out;
+}
+
 /*
  * Scratch, at module scope, because `buildLightClusters` runs per frame on WebGL2 and the house
  * rule forbids allocating there.
@@ -357,6 +513,108 @@ function distanceSqToBounds(x: number, y: number, z: number, b: Float32Array): n
   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`.
+ *
+ * **`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: ClusterLightSet,
+  light: number,
+  shadowSlots: number,
+): boolean {
+  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
+  );
+}
+
+/**
+ * The value of `uClustered` for a frame: 0 with clustering off, 1 when every light is plain, 2 when
+ * any carries a fixture.
+ *
+ * **The third state is a uniform the shader can branch on for free.** The flag test on each light is
+ * a branch on a value read from a texture, and a compiler may run both sides of one; 1.3 ms of a 4K
+ * main pass of 320 plain lamps was that test. Asked once a frame here, a scene whose lights are all
+ * plain never reaches it.
+ */
+export function clusteredMode(lights: ClusterLightSet, count: number, shadowSlots: number): 1 | 2 {
+  for (let light = 0; light < count; light++) {
+    if (lightHasFixture(lights, light, shadowSlots)) return 2;
+  }
+  return 1;
+}
+
+/**
+ * One light's record, at `at` in `out`, as the lit pass reads it.
+ *
+ * **The one writer.** The CPU binner calls this into the table and the GPU binner's staging calls
+ * it into the buffer its kernel copies verbatim, so a field can only move in both at once; the
+ * 2026-08-17 rule is that two implementations of one decision drift invisibly when the constants
+ * are identical, and these were two.
+ *
+ * **A light is plain unless it has a shadow slot, a cone, a profile or a cookie**, and then the
+ * flag is clear and the shader reads two texels. Every slot is still written, so a record holds no
+ * bytes from a light that was there last frame and the two binners' tables stay comparable.
+ *
+ * The shadow slot is signed and carried as a float's bits like everything else in the record. The
+ * first `MAX_POINT_LIGHTS` lights keep the shadow slots they already have, because
+ * `resolvePointLights` orders them so the ones worth shadowing come first, and everything past that
+ * is a light without a map, which is what a scene with two hundred lamps has anyway.
+ */
+export function writeLightRecord(
+  lights: ClusterLightSet,
+  light: number,
+  shadowSlots: number,
+  out: Uint32Array,
+  at: number,
+): void {
+  const directions = lights.directions;
+  const cone = lights.coneCos;
+  const axes = lights.iesAxes;
+  const shadowSlot = light < shadowSlots ? light : NO_SHADOW_SLOT;
+  const cosInner = cone?.[light * 2] ?? POINT_LIGHT_COS_INNER;
+  const cosOuter = cone?.[light * 2 + 1] ?? POINT_LIGHT_COS_OUTER;
+  const profile = lights.iesProfiles?.[light] ?? NO_IES_PROFILE;
+  const cookie = lights.cookies?.[light] ?? NO_IES_PROFILE;
+  const fixture = lightHasFixture(lights, light, shadowSlots);
+
+  out[at + LIGHT_RECORD.positionX] = floatBits(lights.positions[light * 3] ?? 0);
+  out[at + LIGHT_RECORD.positionY] = floatBits(lights.positions[light * 3 + 1] ?? 0);
+  out[at + LIGHT_RECORD.positionZ] = floatBits(lights.positions[light * 3 + 2] ?? 0);
+  out[at + LIGHT_RECORD.radius] = floatBits(lights.radii[light] ?? 0);
+  out[at + LIGHT_RECORD.colorR] = floatBits(lights.colors[light * 3] ?? 0);
+  out[at + LIGHT_RECORD.colorG] = floatBits(lights.colors[light * 3 + 1] ?? 0);
+  out[at + LIGHT_RECORD.colorB] = floatBits(lights.colors[light * 3 + 2] ?? 0);
+  out[at + LIGHT_RECORD.sizeAndWeight] = packSizeAndWeight(
+    lights.sourceRadii[light] ?? 0,
+    lights.weights[light] ?? 1,
+    fixture,
+  );
+  out[at + LIGHT_RECORD.shadowSlot] = floatBits(shadowSlot);
+  /* A light that declared no cone gets the one that admits everything; see the constants. */
+  out[at + LIGHT_RECORD.directionX] = floatBits(directions?.[light * 3] ?? 0);
+  out[at + LIGHT_RECORD.directionY] = floatBits(directions?.[light * 3 + 1] ?? 0);
+  out[at + LIGHT_RECORD.directionZ] = floatBits(directions?.[light * 3 + 2] ?? 0);
+  out[at + LIGHT_RECORD.cosInner] = floatBits(cosInner);
+  out[at + LIGHT_RECORD.cosOuter] = floatBits(cosOuter);
+  out[at + LIGHT_RECORD.iesProfile] = floatBits(profile);
+  out[at + LIGHT_RECORD.cookie] = floatBits(cookie);
+  /* Zero where a consumer gave none, which the shader reads as "no usable reference" and falls
+     back to the first plane, the behaviour every symmetric profile has anyway. */
+  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;
+}
+
 /**
  * Fill the table with this frame's light assignment, and answer how many lights it carried.
  *
@@ -434,51 +692,7 @@ export function buildLightClusters(
     const radius = lights.radii[light] ?? 0;
 
     /* The record, as the shader reads it. World space; see the note above. */
-    const record = lightBase(light);
-    table[record] = floatBits(x);
-    table[record + 1] = floatBits(y);
-    table[record + 2] = floatBits(z);
-    table[record + 3] = floatBits(radius);
-    table[record + 4] = floatBits(lights.colors[light * 3] ?? 0);
-    table[record + 5] = floatBits(lights.colors[light * 3 + 1] ?? 0);
-    table[record + 6] = floatBits(lights.colors[light * 3 + 2] ?? 0);
-    table[record + 7] = floatBits(lights.sourceRadii[light] ?? 0);
-    table[record + 8] = floatBits(lights.weights[light] ?? 1);
-    /*
-     * Signed, and carried as a float's bits like everything else in the record so the shader
-     * reads the whole texel one way. The first `MAX_POINT_LIGHTS` lights keep the shadow slots
-     * they already have — `resolvePointLights` orders them so the ones worth shadowing come
-     * first — and everything past that is a light without a map, which is what a scene with two
-     * hundred lamps has anyway.
-     */
-    table[record + LIGHT_RECORD.shadowSlot] = floatBits(
-      light < shadowSlots ? light : NO_SHADOW_SLOT,
-    );
-
-    /*
-     * The cone, and a light that declared none gets the one that admits everything. Written for
-     * every light rather than only for spots, because the shader reads the same six slots either
-     * way and a record left at whatever the last frame put there is a cone nobody asked for.
-     */
-    const cone = lights.coneCos;
-    const directions = lights.directions;
-    const iesAxes = lights.iesAxes;
-    table[record + LIGHT_RECORD.directionX] = floatBits(directions?.[light * 3] ?? 0);
-    table[record + LIGHT_RECORD.directionY] = floatBits(directions?.[light * 3 + 1] ?? 0);
-    table[record + LIGHT_RECORD.directionZ] = floatBits(directions?.[light * 3 + 2] ?? 0);
-    table[record + LIGHT_RECORD.cosInner] = floatBits(cone?.[light * 2] ?? POINT_LIGHT_COS_INNER);
-    table[record + LIGHT_RECORD.cosOuter] = floatBits(
-      cone?.[light * 2 + 1] ?? POINT_LIGHT_COS_OUTER,
-    );
-    table[record + LIGHT_RECORD.iesProfile] = floatBits(
-      lights.iesProfiles?.[light] ?? NO_IES_PROFILE,
-    );
-    /* Zero where a consumer gave none, which the shader reads as "no usable reference" and falls
-       back to the first plane — the behaviour every symmetric profile has anyway. */
-    table[record + LIGHT_RECORD.iesAxisX] = floatBits(iesAxes?.[light * 3] ?? 0);
-    table[record + LIGHT_RECORD.iesAxisY] = floatBits(iesAxes?.[light * 3 + 1] ?? 0);
-    table[record + LIGHT_RECORD.iesAxisZ] = floatBits(iesAxes?.[light * 3 + 2] ?? 0);
-    table[record + LIGHT_RECORD.cookie] = floatBits(lights.cookies?.[light] ?? NO_IES_PROFILE);
+    writeLightRecord(lights, light, shadowSlots, table, lightBase(light));
 
     /* Column-major, as gl-matrix builds it. The view looks down -z, so depth is -vz. */
     const vx = (view[0] ?? 0) * x + (view[4] ?? 0) * y + (view[8] ?? 0) * z + (view[12] ?? 0);