@driftengine/core 4.13.3 → 4.13.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/core",
-  "version": "4.13.3",
+  "version": "4.13.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.13.3",
-    "@driftengine/physics": "4.13.3",
+    "@driftengine/drft": "4.13.4",
+    "@driftengine/physics": "4.13.4",
     "gl-matrix": "^3.4.3"
   },
   "author": "Drift Technologies",
@@ -67,8 +67,8 @@
     "prepack": "node ../../scripts/build.mjs @driftengine/core"
   },
   "devDependencies": {
-    "@driftengine/nav": "4.13.3",
-    "@driftengine/network": "4.13.3",
-    "@driftengine/texture": "4.13.3"
+    "@driftengine/nav": "4.13.4",
+    "@driftengine/network": "4.13.4",
+    "@driftengine/texture": "4.13.4"
   }
 }

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

@@ -34,6 +34,7 @@ const SECTIONS: readonly (readonly [number, number])[] = [
   [7, 3],
   [10, 3],
   [13, 16],
+  [29, 1],
 ];
 /** Where the influences start, and where the garment's index sits, in particle counts. */
 const INFLUENCES = 13;

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

@@ -20,7 +20,7 @@ import { batchesOf } from '@driftengine/physics';
 import type { ClothBatches, SkinnedClothSetup } from '@driftengine/physics';
 
 /** Floats of statics a particle, across its sections. */
-export const CLOTH_STATIC_FLOATS = 29;
+export const CLOTH_STATIC_FLOATS = 30;
 
 /** Bit flags of the limits a set-up has: a max distance, a backstop, a frontstop. */
 export const CLOTH_LIMIT_MAX = 1;
@@ -29,7 +29,10 @@ export const CLOTH_LIMIT_FRONT = 4;
 
 export interface PackedCloth {
   readonly count: number;
-  /** inverse mass, max distance, backstop ×2, frontstop ×2, thickness, rest ×3, normal ×3, influences ×16. */
+  /**
+   * inverse mass, max distance, backstop ×2, frontstop ×2, thickness, rest ×3, normal ×3,
+   * influences ×16, pull weight.
+   */
   readonly statics: Float32Array;
   /** Distance records (a, b, rest, compliance), bending (four ids, rest, compliance), tethers (particle, anchor, length). */
   readonly constraints: Uint32Array;
@@ -77,6 +80,7 @@ export function packCloth(setup: SkinnedClothSetup): PackedCloth {
       statics[at + i * 2 + 1] = real ? radius : 0;
     }
     statics[6 * n + i] = limits.thickness?.[i] ?? 0;
+    statics[29 * n + i] = setup.pullWeights?.[i] ?? 1;
     for (let k = 0; k < 3; k++) {
       statics[7 * n + i * 3 + k] = setup.positions[i * 3 + k] as number;
       statics[10 * n + i * 3 + k] = setup.normals?.[i * 3 + k] ?? (k === 2 ? 1 : 0);

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

@@ -338,7 +338,7 @@ export class GpuClothSet {
     u[base + 32] = garment.range.colliderBase;
     u[base + 33] = garment.range.colliders;
     u[base + 34] = garment.particles.width;
-    f[base + 35] = 1 / (1 + p.pull * h * h);
+    f[base + 35] = p.pull * h * h;
     f[base + 36] = exactExp(p.damping * h);
     f[base + 37] = exactExp(p.drag * h);
     f[base + 38] = p.maxDistanceScale;

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

@@ -88,8 +88,9 @@ struct Pace {
   colliderBase: u32,
   colliders: u32,
   width: u32,
-  /* The share of its offset from its skinned position a particle keeps a substep: the pull's. */
-  pullKeep: f32,
+  /* The garment's pull as a substep's stiffness, pull · h²: a particle weighted w keeps
+     1 / (1 + w · pullStep) of its offset from its skinned position. */
+  pullStep: f32,
   keep: f32,
   dragKeep: f32,
   maxDistanceScale: f32,
@@ -119,7 +120,7 @@ struct Batch {
 
 /* The record of particle i's garment this round: which garment a particle is, in statics. */
 fn paceAt(i: u32) -> u32 {
-  return round.at + u32(statics[29u * c.count + i]);
+  return round.at + u32(statics[30u * c.count + i]);
 }
 
 fn stateAt(section: u32, i: u32) -> u32 {
@@ -446,8 +447,9 @@ fn clothLimit(@builtin(global_invocation_id) id: vec3<u32>) {
   var p = load(at);
   let t = skinnedAt(i, g);
   /* Only where there is a pull, as on the CPU: t + (p - t) is not p in floats. */
-  if (paces[g].pullKeep < 1.0) {
-    p = t + (p - t) * paces[g].pullKeep;
+  let pull = statics[29u * n + i] * paces[g].pullStep;
+  if (pull > 0.0) {
+    p = t + (p - t) * (1.0 / (1.0 + pull));
   }
   /* A max distance below zero is none: the CPU's Infinity, which a device may not be handed. */
   let maxDistance = statics[n + i];

package/src/render/hairLobes.ts

@@ -50,6 +50,17 @@ export const HAIR_MIN_BETA = 0.05;
  */
 export const HAIR_SCATTER_SPHERE = 1.33;
 
+/**
+ * How far every lobe is widened for light from every side, in radians: the angle a source would
+ * subtend to widen them as much, `sourceRadius / 2·dist` in `hairLight`'s terms.
+ *
+ * **0.2, the real-time form's own value**, which stands one direction in for the sphere: a lobe as
+ * narrow as a lamp's would put the whole sky's light into one highlight wherever the eye's
+ * direction happens to meet it. What it gives up is the sky's shape: a sun low in a clear sky and
+ * an even overcast light hair through the same widened lobes.
+ */
+export const HAIR_AREA = 0.2;
+
 /** How much the scatter term leans toward the strand's own direction rather than the pseudo-normal. */
 const KAJIYA_SHARE = 0.33;
 
@@ -98,6 +109,71 @@ export function hairLight(
   sourceRadius: number,
   dist: number,
   out: Float64Array,
+): void {
+  const grow = sourceRadius / Math.max(2 * dist, 1e-3);
+  hairLobes(tangent, toLight, toEye, fibre, roughness, shift, scatter, backlit, grow, out);
+}
+
+/** The flattened eye `hairIndirect` lights a strand along, as the shader finds it. */
+const flattened = new Float64Array(3);
+
+/**
+ * The share of light from every side a strand returns, a colour into `out`, with the one
+ * direction's lobes it is made of into `lobes` (`HAIR_OUT`'s layout). `normal` is the surface's,
+ * which stands in for the flattened eye where the eye runs along the strand and there is none.
+ *
+ * **One direction for the sphere**: the eye flattened across the strand, `V − T(V·T)`, unshadowed,
+ * with no light from behind and so no transmitted lobe, every lobe widened by `HAIR_AREA`. Twice
+ * the sum, and at most all of what arrives. **Why twice**: the scatter's half is then
+ * `HAIR_SCATTER_SPHERE`, its own answer to an even sky — along the flattened eye its shape is
+ * `mix(1/2, 1, 0.33)`, 0.665, which doubled is that constant's 1.33 — so the lobes ride on a
+ * scatter the sphere's quadrature already holds to, and R and TRT are what the direction adds.
+ */
+export function hairIndirect(
+  tangent: ArrayLike<number>,
+  toEye: ArrayLike<number>,
+  normal: ArrayLike<number>,
+  fibre: Vec3,
+  roughness: number,
+  shift: number,
+  scatter: number,
+  lobes: Float64Array,
+  out: Float64Array,
+): void {
+  const along = dot(tangent, toEye);
+  let length2 = 0;
+  for (let c = 0; c < 3; c++) {
+    const across = (toEye[c] as number) - (tangent[c] as number) * along;
+    flattened[c] = across;
+    length2 += across * across;
+  }
+  for (let c = 0; c < 3; c++) {
+    flattened[c] =
+      length2 > 1e-8 ? (flattened[c] as number) / Math.sqrt(length2) : (normal[c] as number);
+  }
+  hairLobes(tangent, flattened, toEye, fibre, roughness, shift, scatter, 0, HAIR_AREA, lobes);
+  for (let c = 0; c < 3; c++) {
+    const sum =
+      (lobes[HAIR_OUT.r] as number) +
+      (lobes[HAIR_OUT.tt + c] as number) +
+      (lobes[HAIR_OUT.trt + c] as number) +
+      (lobes[HAIR_OUT.scatter + c] as number);
+    out[c] = Math.min(1, 2 * sum);
+  }
+}
+
+/** `hairLight`'s arithmetic, every lobe widened by `grow` radians. */
+function hairLobes(
+  tangent: ArrayLike<number>,
+  toLight: ArrayLike<number>,
+  toEye: ArrayLike<number>,
+  fibre: Vec3,
+  roughness: number,
+  shift: number,
+  scatter: number,
+  backlit: number,
+  grow: number,
+  out: Float64Array,
 ): void {
   const sinI = clamp(dot(tangent, toLight), -1, 1);
   const sinO = clamp(dot(tangent, toEye), -1, 1);
@@ -124,7 +200,6 @@ export function hairLight(
   const cosPhi = lpvp / Math.sqrt(lp2 * vp2 + 1e-4);
   const cosHalfPhi = Math.sqrt(clamp(0.5 + 0.5 * cosPhi, 0, 1));
   const beta = Math.max(roughness * roughness, HAIR_MIN_BETA);
-  const grow = sourceRadius / Math.max(2 * dist, 1e-3);
   const x = sinI + sinO;
 
   const r =

package/src/render/shaders/flat/hair.ts

@@ -4,29 +4,35 @@
  * receives, and every term to a finite answer where the geometry degenerates.
  *
  * **The strand is the tangent, root to tip.** The model map's green turns each strand's tilt by up
- * to half of it either way (0.5 is none) and its blue is occlusion, which the sky, DriftLight and
- * the environment's reflection take and the lamps do not — their shadows are theirs to cast. The
- * red is not read: a colour from root to tip is the albedo map's to carry.
+ * to half of it either way (0.5 is none) and its blue is occlusion, which light from every side
+ * takes and the lamps do not — their shadows are theirs to cast. The red is not read: a colour from
+ * root to tip is the albedo map's to carry.
  *
- * **The environment** is the reflected lobe's: mirrored about a normal turned toward the eye across
- * the strand, which is the cone R lies on, at the strand's own Fresnel — the lobe integrates to it
- * over every direction of arrival. **What it gives up** is the two transmitted lobes against the
- * sky, which a head of hair lit from behind by an open sky would show as a rim; the lamps carry
- * them.
+ * **Light from every side** — the sky, the probes, DriftLight — goes through the lobes rather than
+ * past them: they are evaluated once, for a light along the eye flattened across the strand, every
+ * lobe widened by \`HAIR_AREA\` as a source that large would widen it, and their sum taken as the
+ * share of that light the strand returns (\`hairIndirect\`). That is how a real-time hair model
+ * stands one direction in for the sphere: a strand returns most toward the eye what arrives from
+ * the eye's side of it, and the R and TRT lobes are what make a fibre gold rather than a wash of
+ * its scatter. The environment's reflection leaves hair out, because R already took its share.
+ *
+ * **What it gives up**: light from behind. The direction stands for the eye's side only, so there
+ * is no transmitted lobe in it, and a head of hair lit from behind by an open sky shows no rim
+ * from the sky; the lamps carry one. And the share is one direction's, not the sphere's integral,
+ * so it moves with the eye as the lobes do rather than holding still as an average would. **What
+ * would make it wrong** is hair seen mostly against its light, a head against a bright window,
+ * whose sky arrives through the strands rather than off them and wants the transmitted lobe back.
  */
-import { HAIR_F0, HAIR_MIN_BETA, HAIR_SCATTER_SPHERE } from '../../hairLobes.ts';
+import { HAIR_AREA, HAIR_F0, HAIR_MIN_BETA } from '../../hairLobes.ts';
 
 export const HAIR_GLSL = /* glsl */ `
 const float HAIR_F0 = ${HAIR_F0.toFixed(9)};
 const float HAIR_MIN_BETA = ${HAIR_MIN_BETA.toFixed(3)};
-const float HAIR_SCATTER_SPHERE = ${HAIR_SCATTER_SPHERE.toFixed(3)};
+const float HAIR_AREA = ${HAIR_AREA.toFixed(3)};
 
-/* This texel's tilt, gathered once with the surface. */
+/* This texel's tilt, and the share of light from every side it returns: gathered with the surface. */
 float hShift;
-
-void hairSurface() {
-  hShift = uModelParams[0].x * (0.5 + mMap.g);
-}
+vec3 hAround;
 
 /** A longitudinal lobe: a normalised Gaussian of width \`beta\` at \`x\` from its centre. */
 float hairLongitudinal(float beta, float x) {
@@ -38,14 +44,18 @@ float hairFresnel(float cosine) {
   return HAIR_F0 + (1.0 - HAIR_F0) * c * c * c * c * c;
 }
 
-/** The normal turned toward the eye across the strand: the scatter's and the environment's. */
+/** The normal turned toward the eye across the strand: the scatter's, and light from every side's. */
 vec3 hairAcross() {
   vec3 across = mToEye - mTangent * dot(mTangent, mToEye);
   float length2 = dot(across, across);
   return length2 > 1e-8 ? across * inversesqrt(length2) : mNormal;
 }
 
-void hairLight(vec3 l, float sourceRadius, float dist) {
+/**
+ * The lobes for light arriving along \`l\`, into \`mSpecular\` and \`mDiffuse\`: every lobe widened by
+ * \`grow\` radians, and the transmitted one scaled by \`backlit\`.
+ */
+void hairLobes(vec3 l, float grow, float backlit) {
   vec3 t = mTangent;
   float sinI = clamp(dot(t, l), -1.0, 1.0);
   float sinO = clamp(dot(t, mToEye), -1.0, 1.0);
@@ -56,7 +66,6 @@ void hairLight(vec3 l, float sourceRadius, float dist) {
   float cosPhi = dot(lp, vp) * inversesqrt(dot(lp, lp) * dot(vp, vp) + 1e-4);
   float cosHalfPhi = sqrt(clamp(0.5 + 0.5 * cosPhi, 0.0, 1.0));
   float beta = max(mRoughness * mRoughness, HAIR_MIN_BETA);
-  float grow = sourceRadius / max(2.0 * dist, 1e-3);
   float x = sinI + sinO;
 
   float r = hairLongitudinal(beta + grow, x + 2.0 * hShift) * 0.25 * cosHalfPhi
@@ -66,7 +75,7 @@ void hairLight(vec3 l, float sourceRadius, float dist) {
   float h = cosHalfPhi * (1.0 + a * (0.6 - 0.8 * cosPhi));
   float fTT = hairFresnel(cosD * sqrt(clamp(1.0 - h * h, 0.0, 1.0)));
   float tt = hairLongitudinal(0.5 * beta + grow, x - hShift) * exp(-3.65 * cosPhi - 3.98)
-    * (1.0 - fTT) * (1.0 - fTT) * uModelParams[0].z;
+    * (1.0 - fTT) * (1.0 - fTT) * backlit;
   float ttPower = 0.5 * sqrt(clamp(1.0 - h * h * a * a, 0.0, 1.0)) / cosD;
 
   float fTRT = hairFresnel(0.5 * cosD);
@@ -81,6 +90,11 @@ void hairLight(vec3 l, float sourceRadius, float dist) {
   mDiffuse = sqrt(mAlbedo) * uModelParams[0].y * mix(wrapped, 1.0 - abs(sinI), 0.33);
 }
 
+/** A lamp, or the sun at no size: widened by the angle it subtends, as \`sphereLobe\` takes it. */
+void hairLight(vec3 l, float sourceRadius, float dist) {
+  hairLobes(l, sourceRadius / max(2.0 * dist, 1e-3), uModelParams[0].z);
+}
+
 /**
  * A shadow on the scatter: light that reaches a strand in another's shadow has passed through
  * hair to get there, so a penumbra deepens toward the fibre's own hue.
@@ -90,13 +104,25 @@ vec3 hairShade(float shadow) {
   return shadow * pow(max(hue, vec3(1e-4)), vec3(1.0 - shadow));
 }
 
-/** Light from every side, through the scatter term: \`HAIR_SCATTER_SPHERE\` says why that number. */
-vec3 hairAround(vec3 light) {
-  return sqrt(mAlbedo) * (uModelParams[0].y * HAIR_SCATTER_SPHERE * mMap.b) * light;
+/**
+ * The share of light from every side a strand returns: the lobes for a light along the eye
+ * flattened across the strand, unshadowed, with nothing from behind and every lobe widened by
+ * \`HAIR_AREA\`, twice their sum and at most all of it. Twice, in this engine's units, because the
+ * lobes are per unit irradiance and the scatter's half is then exactly \`HAIR_SCATTER_SPHERE\`, its
+ * own average over the sphere: \`hairLobes.ts\` says why, and holds the arithmetic to it.
+ */
+vec3 hairIndirect() {
+  hairLobes(hairAcross(), HAIR_AREA, 0.0);
+  return min(vec3(1.0), 2.0 * (mSpecular + mDiffuse));
 }
 
-/** The reflected lobe's share of the environment: its Fresnel, which is what it integrates to. */
-float hairReflectance() {
-  return hairFresnel(dot(hairAcross(), mToEye)) * mMap.b;
+void hairSurface() {
+  hShift = uModelParams[0].x * (0.5 + mMap.g);
+  hAround = hairIndirect();
+}
+
+/** Light from every side, through the lobes, under the map's occlusion. */
+vec3 hairAround(vec3 light) {
+  return hAround * (mMap.b * light);
 }
 `;

package/src/render/shaders/flat/main.ts

@@ -695,8 +695,9 @@ export const MAIN_GLSL = `void main() {
      * branch it did not take before.
      */
     /* A model reflects its environment whatever the pass asked of the standard model: see
-       modelReflectance. On the switches alone, so the derivatives below stay in uniform flow. */
-    if (uEnvironmentDials.y > 0.0 || uMaterialFlags.y != 0 || modelled) {
+       modelReflectance. Hair takes none: modelReflects. On the switches alone, so the derivatives
+       below stay in uniform flow. */
+    if ((uEnvironmentDials.y > 0.0 || uMaterialFlags.y != 0 || modelled) && modelReflects()) {
       vec3 toEye = normalize(uCameraPos - vWorldPos);
       vec3 mirrored = reflect(-toEye, modelled ? modelReflectNormal(n) : n);
       vec3 environment = mix(uAmbientGround, uAmbient, mirrored.y * 0.5 + 0.5);

package/src/render/shaders/flat/models.ts

@@ -12,8 +12,8 @@
  * **Where the models plug in.** `main` gathers the surface once (`modelSurface`), then asks at each
  * place light arrives: `modelLight` for the sun, each lamp and each rectangle, `modelAmbient` for
  * the sky and the probe's irradiance, `modelIrradiance` for DriftLight, `modelReflectNormal` and
- * `modelReflectance` for the environment's reflection. Each returns today's term for the standard
- * model, and each model's file is where its own answers are.
+ * `modelReflectance` for the environment's reflection, which `modelReflects` keeps from hair. Each
+ * returns today's term for the standard model, and each model's file is where its own answers are.
  *
  * **What a model returns from a light** is the two halves the standard terms are: a diffuse already
  * weighted by the angle of arrival, and a specular lobe in the engine's peak-normalised units (see
@@ -95,6 +95,15 @@ bool modelSeesBehind() {
   return false;
 }
 
+/**
+ * Whether the environment's reflection reaches this surface: every model's but hair's, whose share
+ * of it is in its light from every side (hair.ts).
+ */
+bool modelReflects() {
+  if (MODEL_HAIR) return false;
+  return true;
+}
+
 /* The surface a model shades, gathered once in main before any light reaches it. */
 vec3 mNormal;
 vec3 mToEye;
@@ -285,7 +294,6 @@ vec3 modelIrradiance(vec3 irradiance) {
 /** The normal the environment is reflected about: the surface's own, but for a stretched lobe. */
 vec3 modelReflectNormal(vec3 n) {
   if (MODEL_ANISOTROPIC) return anisotropicReflectNormal(n);
-  if (MODEL_HAIR) return hairAcross();
   return n;
 }
 
@@ -361,7 +369,6 @@ vec3 modelDiffuseOut(vec3 diffuse, float fog) {
  * what the standard model would.
  */
 float modelReflectance(float standard) {
-  if (MODEL_HAIR) return hairReflectance();
   if (MODEL_SKIN) return skinReflectance();
   if (MODEL_EYE) return eyeReflectance();
   return standard;