@driftengine/core 4.7.2 → 4.7.4

package/dist/scene/node.js

@@ -122,7 +122,7 @@ export class SceneNode {
     attachChild(child) {
         if (child === this)
             throw new Error('SceneNode: a node cannot be its own child (cycle)');
-        for (let at = this; at !== null; at = at.parent) {
+        for (let at = this.parent; at !== null; at = at.parent) {
             if (at === child)
                 throw new Error('SceneNode: that would make a cycle');
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/core",
-  "version": "4.7.2",
+  "version": "4.7.4",
   "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.4",
+    "@driftengine/physics": "4.7.4",
     "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.4",
+    "@driftengine/network": "4.7.4",
+    "@driftengine/texture": "4.7.4"
   }
 }

package/src/geometry/meshBuilder.ts

@@ -969,8 +969,9 @@ export class MeshBuilder {
         // later one is transported from it, so the choice never shows.
         const ax = Math.abs(tx) < 0.9 ? 1 : 0;
         const ay = Math.abs(tx) < 0.9 ? 0 : 1;
-        ux = ay * tz - 0 * ty;
-        uy = 0 * tx - ax * tz;
+        // (ax, ay, 0) x tangent, with the terms the zero removes left out.
+        ux = ay * tz;
+        uy = -ax * tz;
         uz = ax * ty - ay * tx;
         seeded = true;
       }

package/src/math/exact.ts

@@ -69,7 +69,7 @@ const PI = 3.141592653589793;
 
 /* fdlibm's `__kernel_sin` coefficients. */
 const S1 = -1.6666666666666632e-1;
-const S2 = 8.3333333333224894e-3;
+const S2 = 8.33333333332249e-3;
 const S3 = -1.984126982985795e-4;
 const S4 = 2.7557313707070068e-6;
 const S5 = -2.5050760253406863e-8;
@@ -77,7 +77,7 @@ const S6 = 1.5896909952115501e-10;
 
 /* fdlibm's `__kernel_cos` coefficients. */
 const C1 = 4.1666666666666602e-2;
-const C2 = -1.3888888888874109e-3;
+const C2 = -1.388888888887411e-3;
 const C3 = 2.480158728947673e-5;
 const C4 = -2.7557314351390663e-7;
 const C5 = 2.0875723212981748e-9;
@@ -286,7 +286,7 @@ export function exactLog(x: number): number {
   if ((0x000fffff & (2 + hx)) < 3) {
     /* |f| < 2^-20: two terms of the series are the whole answer. */
     if (f === 0) return k === 0 ? 0 : k * LN2_HI + k * LN2_LO;
-    const r = f * f * (0.5 - 0.33333333333333333 * f);
+    const r = f * f * (0.5 - 0.3333333333333333 * f);
     return k === 0 ? f - r : k * LN2_HI - (r - k * LN2_LO - f);
   }
   const s = f / (2 + f);

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/linePass.ts

@@ -5,7 +5,6 @@ import {
   LINE_VERT_WGSL,
 } from '../../shaders/generated/line.wgsl.ts';
 import { buildSegmentQuads } from '../../segmentQuads.ts';
-import type { LineSegments } from '../../linePoints.ts';
 import type { UniformFields } from './scatterPass.ts';
 import { DEPTH_FORMAT } from './flatPass.ts';
 import type { PipelineCache } from './pipelineCache.ts';

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;