@woosh/meep-engine 2.169.1 → 2.169.2

package/src/engine/ecs/evaluation/complex/PointFitnessGaussianBlur.d.ts

@@ -1,11 +1,23 @@
+/**
+ * Blurs another {@link PointFitnessFunction} by sampling it over an axis-aligned box centred on the
+ * query point and weighting the samples with a separable 3D gaussian.
+ *
+ * Sampling convention (shared with {@link CellFilterGaussianBlur}): the taps are centred on
+ * `(samples-1)/2` and spaced `size/(samples-1)` apart, so the outermost taps land exactly on the
+ * faces of the box and the tap pattern is symmetric about the query point.
+ *
+ * An axis with a zero `size` still gets its (minimum) taps, but they all land on the query point,
+ * so the axis contributes a constant factor that cancels in the normalisation — i.e. a `size_z` of
+ * 0 gives a plain 2D blur.
+ */
 export class PointFitnessGaussianBlur extends PointFitnessFunction {
     /**
      *
      * @param {PointFitnessFunction} source
-     * @param {number} x
+     * @param {number} x size of the blur box along X, in world units
      * @param {number} y
      * @param {number} z
-     * @param {number} [quality]
+     * @param {number} [quality] taps per world unit along each axis
      * @returns {PointFitnessGaussianBlur}
      */
     static from(source: PointFitnessFunction, x: number, y: number, z: number, quality?: number): PointFitnessGaussianBlur;
@@ -18,6 +30,14 @@ export class PointFitnessGaussianBlur extends PointFitnessFunction {
     size_x: number;
     size_y: number;
     size_z: number;
+    /**
+     * Taps per world unit that {@link samples_x}/{@link samples_y}/{@link samples_z} were derived
+     * from. Kept only so the derivation can be reproduced (serialization records the box size and
+     * the quality, not the resulting tap counts); {@link evaluate} reads the sample counts.
+     *
+     * @type {number}
+     */
+    quality: number;
     /**
      *
      * @type {PointFitnessFunction}

package/src/engine/ecs/evaluation/complex/PointFitnessGaussianBlur.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PointFitnessGaussianBlur.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/ecs/evaluation/complex/PointFitnessGaussianBlur.js"],"names":[],"mappings":"AAIA;IAwBI;;;;;;;;OAQG;IACH,oBAPW,oBAAoB,KACpB,MAAM,KACN,MAAM,KACN,MAAM,YACN,MAAM,GACJ,wBAAwB,CAwBpC;IAnDG,kBAAkB;IAClB,kBAAkB;IAClB,kBAAkB;IAElB,gBAAiB;IACjB,gBAAiB;IACjB,gBAAiB;IAGjB,eAAe;IACf,eAAe;IACf,eAAe;IAEf;;;OAGG;IACH,QAFU,oBAAoB,CAEZ;IAoCtB,mDA4DC;IAGL,aAAuC;CAFtC;qCA1HoC,4BAA4B"}
+{"version":3,"file":"PointFitnessGaussianBlur.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/ecs/evaluation/complex/PointFitnessGaussianBlur.js"],"names":[],"mappings":"AAiCA;;;;;;;;;;;GAWG;AACH;IA6BI;;;;;;;;OAQG;IACH,oBAPW,oBAAoB,KACpB,MAAM,KACN,MAAM,KACN,MAAM,YACN,MAAM,GACJ,wBAAwB,CA8BpC;IAhED,kBAAc;IACd,kBAAc;IACd,kBAAc;IAEd,gBAAwB;IACxB,gBAAwB;IACxB,gBAAwB;IAExB,eAAW;IACX,eAAW;IACX,eAAW;IAEX;;;;;;OAMG;IACH,SAFU,MAAM,CAEJ;IAEZ;;;OAGG;IACH,QAFU,oBAAoB,CAEhB;IAyCd,mDA2DC;IAGL,aAAuC;CAFtC;qCA7KoC,4BAA4B"}

package/src/engine/ecs/evaluation/complex/PointFitnessGaussianBlur.js

@@ -1,38 +1,84 @@
 import { PointFitnessFunction } from "../PointFitnessFunction.js";
 import { assert } from "../../../../core/assert.js";
 import { gaussian } from "../../../../core/math/gaussian.js";
+import { max2 } from "../../../../core/math/max2.js";
+import { nextOdd } from "../../../../core/math/nextOdd.js";
+
+/**
+ * Number of taps to spread across one axis of the blur box.
+ *
+ * Forced odd so a tap lands exactly on the centre, and to at least 3 so the axis is actually
+ * sampled either side of centre. Matches {@link CellFilterGaussianBlur.from}.
+ *
+ * @param {number} extent size of the blur box along this axis, in world units
+ * @param {number} quality taps per world unit
+ * @returns {number} odd integer, at least 3
+ */
+function axis_sample_count(extent, quality) {
+    return max2(3, nextOdd(Math.round(quality * extent)));
+}
+
+/**
+ * Standard deviation for an axis, in kernel-index units.
+ *
+ * The kernel spans `±(samples-1)/2` indices and should cover `±3` sigma of the gaussian, otherwise
+ * the taps sit on a near-flat part of the bell and the "blur" degenerates into a box filter.
+ *
+ * @param {number} samples
+ * @returns {number}
+ */
+function axis_sigma(samples) {
+    return (samples - 1) / 6;
+}
 
+/**
+ * Blurs another {@link PointFitnessFunction} by sampling it over an axis-aligned box centred on the
+ * query point and weighting the samples with a separable 3D gaussian.
+ *
+ * Sampling convention (shared with {@link CellFilterGaussianBlur}): the taps are centred on
+ * `(samples-1)/2` and spaced `size/(samples-1)` apart, so the outermost taps land exactly on the
+ * faces of the box and the tap pattern is symmetric about the query point.
+ *
+ * An axis with a zero `size` still gets its (minimum) taps, but they all land on the query point,
+ * so the axis contributes a constant factor that cancels in the normalisation — i.e. a `size_z` of
+ * 0 gives a plain 2D blur.
+ */
 export class PointFitnessGaussianBlur extends PointFitnessFunction {
-    constructor() {
-        super();
 
-        this.samples_x = 5;
-        this.samples_y = 5;
-        this.samples_z = 5;
+    samples_x = 5;
+    samples_y = 5;
+    samples_z = 5;
 
-        this.sigma_x = 10;
-        this.sigma_y = 10;
-        this.sigma_z = 10;
+    sigma_x = axis_sigma(5);
+    sigma_y = axis_sigma(5);
+    sigma_z = axis_sigma(5);
 
+    size_x = 1;
+    size_y = 1;
+    size_z = 1;
 
-        this.size_x = 1;
-        this.size_y = 1;
-        this.size_z = 1;
+    /**
+     * Taps per world unit that {@link samples_x}/{@link samples_y}/{@link samples_z} were derived
+     * from. Kept only so the derivation can be reproduced (serialization records the box size and
+     * the quality, not the resulting tap counts); {@link evaluate} reads the sample counts.
+     *
+     * @type {number}
+     */
+    quality = 5;
 
-        /**
-         *
-         * @type {PointFitnessFunction}
-         */
-        this.source = null;
-    }
+    /**
+     *
+     * @type {PointFitnessFunction}
+     */
+    source = null;
 
     /**
      *
      * @param {PointFitnessFunction} source
-     * @param {number} x
+     * @param {number} x size of the blur box along X, in world units
      * @param {number} y
      * @param {number} z
-     * @param {number} [quality]
+     * @param {number} [quality] taps per world unit along each axis
      * @returns {PointFitnessGaussianBlur}
      */
     static from(source, x, y, z, quality = 5) {
@@ -48,14 +94,20 @@ export class PointFitnessGaussianBlur extends PointFitnessFunction {
 
         r.source = source;
 
-        r.samples_x = x * quality;
-        r.samples_y = y * quality;
-        r.samples_z = z * quality;
+        r.quality = quality;
+
+        r.samples_x = axis_sample_count(x, quality);
+        r.samples_y = axis_sample_count(y, quality);
+        r.samples_z = axis_sample_count(z, quality);
 
         r.size_x = x;
         r.size_y = y;
         r.size_z = z;
 
+        r.sigma_x = axis_sigma(r.samples_x);
+        r.sigma_y = axis_sigma(r.samples_y);
+        r.sigma_z = axis_sigma(r.samples_z);
+
         return r;
     }
 
@@ -64,13 +116,17 @@ export class PointFitnessGaussianBlur extends PointFitnessFunction {
         const samplesY = this.samples_y;
         const samplesZ = this.samples_z;
 
-        const half_samples_x = (samplesX / 2);
-        const half_samples_y = (samplesY / 2);
-        const half_samples_z = (samplesZ / 2);
+        // taps are centred on the middle index, so they are symmetric about the query point
+        const half_samples_x = (samplesX - 1) * 0.5;
+        const half_samples_y = (samplesY - 1) * 0.5;
+        const half_samples_z = (samplesZ - 1) * 0.5;
+
+        // spacing that puts the outermost taps exactly on the faces of the blur box
+        const step_x = this.size_x / (samplesX - 1);
+        const step_y = this.size_y / (samplesY - 1);
+        const step_z = this.size_z / (samplesZ - 1);
 
-        const sizeX = this.size_x;
-        const sizeY = this.size_y;
-        const sizeZ = this.size_z;
+        const source = this.source;
 
         let sum = 0;
         let powerTotal = 0;
@@ -81,18 +137,14 @@ export class PointFitnessGaussianBlur extends PointFitnessFunction {
 
             const fz = gaussian(this.sigma_z, local_z);
 
-            const nz = local_z / samplesZ;
-
-            const offset_z = sizeZ * nz;
+            const offset_z = local_z * step_z;
 
             for (let iy = 0; iy < samplesY; iy++) {
                 const local_y = iy - half_samples_y;
 
                 const fy = gaussian(this.sigma_y, local_y);
 
-                const ny = local_y / samplesY;
-
-                const offset_y = sizeY * ny;
+                const offset_y = local_y * step_y;
 
                 for (let ix = 0; ix < samplesX; ix++) {
 
@@ -100,15 +152,13 @@ export class PointFitnessGaussianBlur extends PointFitnessFunction {
 
                     const fx = gaussian(this.sigma_x, local_x);
 
-                    const nx = local_x / samplesX;
-
-                    const offset_x = sizeX * nx;
+                    const offset_x = local_x * step_x;
 
                     const power = fx * fy * fz;
 
                     powerTotal += power;
 
-                    const sourceValue = this.source.evaluate(ecd, x + offset_x, y + offset_y, z + offset_z);
+                    const sourceValue = source.evaluate(ecd, x + offset_x, y + offset_y, z + offset_z);
 
                     sum += sourceValue * power;
 
@@ -116,9 +166,10 @@ export class PointFitnessGaussianBlur extends PointFitnessFunction {
             }
         }
 
-        const result = sum / powerTotal;
-
-        return result;
+        // dividing by the accumulated power is exactly what a pre-normalized kernel
+        // (see `core/math/build_gaussian_kernel_2d.js`) does; there is no `initialize` stage on
+        // PointFitnessFunction to precompute one into, so the weights are evaluated inline
+        return sum / powerTotal;
     }
 }
 

package/src/engine/ecs/gui/hud/HeadsUpDisplaySystem.d.ts

@@ -23,7 +23,9 @@ declare class HeadsUpDisplaySystem extends System<any> {
     shutdown(em: any): Promise<void>;
     startup(em: any): Promise<void>;
     /**
-     * NOTE: for the sake of speed all of the matrix and vector multiplications have been inlined, readability of this method is pretty bad
+     * NOTE: for the sake of speed the projection multiplications have been inlined, readability of this method is pretty bad.
+     * The quaternion rotation is NOT inlined — {@link v3_quaternion_apply} already writes into a caller-supplied
+     * array, so it costs no allocation and there is nothing to gain from a private copy of the expansion.
      * @param {HeadsUpDisplay} hud
      * @param {Transform} transform
      * @param {ViewportPosition} vp

package/src/engine/ecs/gui/hud/HeadsUpDisplaySystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HeadsUpDisplaySystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/ecs/gui/hud/HeadsUpDisplaySystem.js"],"names":[],"mappings":";AAeA;;;;;GAKG;AACH;IASI;;;OAGG;IACH,4BAFW,cAAc,EAqBxB;IA/BD,wCAAgC;IAGhC,2HAGE;IAaE,yBAA8B;IAM9B;;;;OAIG;IACH,+BAAiD;IAGrD,iCAGC;IAED,gCAIC;IAED;;;;;;;OAOG;IACH,sCA6JC;IAED,6BAsBC;CACJ;uBA3PsB,iBAAiB;2BAIb,qBAAqB;uBAFzB,kBAAkB;4CALG,uDAAuD;6BAMtE,iCAAiC;+BAL/B,qCAAqC"}
+{"version":3,"file":"HeadsUpDisplaySystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/ecs/gui/hud/HeadsUpDisplaySystem.js"],"names":[],"mappings":";AAsBA;;;;;GAKG;AACH;IASI;;;OAGG;IACH,4BAFW,cAAc,EAqBxB;IA/BD,wCAAgC;IAGhC,2HAGE;IAaE,yBAA8B;IAM9B;;;;OAIG;IACH,+BAAiD;IAGrD,iCAGC;IAED,gCAIC;IAED;;;;;;;;;OASG;IACH,sCAkJC;IAED,6BAsBC;CACJ;uBAxPsB,iBAAiB;2BAIb,qBAAqB;uBAFzB,kBAAkB;4CALG,uDAAuD;6BAMtE,iCAAiC;+BAL/B,qCAAqC"}

package/src/engine/ecs/gui/hud/HeadsUpDisplaySystem.js

@@ -1,4 +1,5 @@
 import { m4_multiply } from "../../../../core/geom/3d/mat4/m4_multiply.js";
+import { v3_quaternion_apply } from "../../../../core/geom/vec3/v3_quaternion_apply.js";
 import { ResourceAccessKind } from "../../../../core/model/ResourceAccessKind.js";
 import { ResourceAccessSpecification } from "../../../../core/model/ResourceAccessSpecification.js";
 import { GraphicsEngine } from "../../../graphics/GraphicsEngine.js";
@@ -12,6 +13,12 @@ import { HeadsUpDisplayFlag } from "./HeadsUpDisplayFlag.js";
 
 const projection = new Float32Array(16);
 
+/**
+ * Destination for {@link v3_quaternion_apply}; the world offset is rotated through here.
+ * @type {Float64Array}
+ */
+const scratch_rotated_offset = new Float64Array(3);
+
 
 /**
  *
@@ -65,7 +72,9 @@ class HeadsUpDisplaySystem extends System {
     }
 
     /**
-     * NOTE: for the sake of speed all of the matrix and vector multiplications have been inlined, readability of this method is pretty bad
+     * NOTE: for the sake of speed the projection multiplications have been inlined, readability of this method is pretty bad.
+     * The quaternion rotation is NOT inlined — {@link v3_quaternion_apply} already writes into a caller-supplied
+     * array, so it costs no allocation and there is nothing to gain from a private copy of the expansion.
      * @param {HeadsUpDisplay} hud
      * @param {Transform} transform
      * @param {ViewportPosition} vp
@@ -89,22 +98,11 @@ class HeadsUpDisplaySystem extends System {
 
             const q = transform.rotation;
 
-            const qx = q.x;
-            const qy = q.y;
-            const qz = q.z;
-            const qw = q.w;
-
-            // calculate quat * vec
-            const ix = qw * x + qy * z - qz * y;
-            const iy = qw * y + qz * x - qx * z;
-            const iz = qw * z + qx * y - qy * x;
-            const iw = -qx * x - qy * y - qz * z;
-
-            // calculate result * inverse quat
-            x = ix * qw + iw * -qx + iy * -qz - iz * -qy;
-            y = iy * qw + iw * -qy + iz * -qx - ix * -qz;
-            z = iz * qw + iw * -qz + ix * -qy - iy * -qx;
+            v3_quaternion_apply(scratch_rotated_offset, 0, x, y, z, q.x, q.y, q.z, q.w);
 
+            x = scratch_rotated_offset[0];
+            y = scratch_rotated_offset[1];
+            z = scratch_rotated_offset[2];
         }
 
         // add transform position to get final world position

package/src/engine/ecs/gui/parallax/GuiElementParallaxSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GuiElementParallaxSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/ecs/gui/parallax/GuiElementParallaxSystem.js"],"names":[],"mappings":"AAIA;IAGI;;;;OAIG;IACH,yCAeC;IAtBD,gEAAgD;IAW5C;;;OAGG;IACH,UAFU,OAAK,IAAI,CAEK;IAExB;;;OAGG;IACH,SAFU,gBAAc,IAAI,CAEN;IAG1B;;;;;OAKG;IACH,uBAJW,kBAAkB,WAClB,UAAU,UACV,MAAM,QA2ChB;IAED,6BAWC;CACJ;uBA1FsB,iBAAiB;uBACjB,kBAAkB;mCACN,yBAAyB"}
+{"version":3,"file":"GuiElementParallaxSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/ecs/gui/parallax/GuiElementParallaxSystem.js"],"names":[],"mappings":"AAKA;IAGI;;;;OAIG;IACH,yCAeC;IAtBD,gEAAgD;IAW5C;;;OAGG;IACH,UAFU,OAAK,IAAI,CAEK;IAExB;;;OAGG;IACH,SAFU,gBAAc,IAAI,CAEN;IAG1B;;;;;OAKG;IACH,uBAJW,kBAAkB,WAClB,UAAU,UACV,MAAM,QA6BhB;IAED,6BAWC;CACJ;uBA5EsB,iBAAiB;uBACjB,kBAAkB;mCACN,yBAAyB"}

package/src/engine/ecs/gui/parallax/GuiElementParallaxSystem.js

@@ -1,3 +1,4 @@
+import { apply_pointer_tilt_3d } from "../../../ui/apply_pointer_tilt_3d.js";
 import { System } from "../../System.js";
 import GUIElement from "../GUIElement.js";
 import { GuiElementParallax } from "./GuiElementParallax.js";
@@ -37,43 +38,29 @@ export class GuiElementParallaxSystem extends System {
 
         const p = this.pointer.position;
 
-        const pointer_x = p.x;
-        const pointer_y = p.y;
-
         const viewport_side = this.viewport.size;
 
         const view = element.view;
 
+        const el = view.el;
+
         /**
          *
          * @type {ClientRect}
          */
-        const rect = view.el.getBoundingClientRect();
-
-        const center_x = rect.left + rect.width * 0.5;
-        const center_y = rect.top + rect.height * 0.5;
-
-
-        const viewport_center_x = viewport_side.x * 0.5;
-        const viewport_center_y = viewport_side.y * 0.5;
-
-        const delta_x = pointer_x - viewport_center_x;
-        const delta_y = pointer_y - viewport_center_y;
-
-
-        const tilt_x = (delta_y / viewport_center_y);
-        const tilt_y = -(delta_x / viewport_center_x);
-
-        const radius = Math.sqrt(tilt_x * tilt_x + tilt_y * tilt_y);
-
-        const angle = radius * parallax.angle;
-
-
-        const style = view.el.style;
-
-        style.transformOrigin = '50% 50%';
-        style.transform = `rotate3d(${tilt_x},${tilt_y},0,${angle}deg)`;
-        style.transformStyle = 'preserve-3d';
+        const rect = el.getBoundingClientRect();
+
+        apply_pointer_tilt_3d(
+            el,
+            p.x, p.y,
+            rect.left + rect.width * 0.5, rect.top + rect.height * 0.5,
+            viewport_side.x, viewport_side.y,
+            parallax.angle,
+            0
+        );
+
+        // children of a parallaxed element participate in the same 3d space
+        el.style.transformStyle = 'preserve-3d';
     }
 
     update(timeDelta) {

package/src/engine/ecs/ik/OneBoneSurfaceAlignmentSolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OneBoneSurfaceAlignmentSolver.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/ik/OneBoneSurfaceAlignmentSolver.js"],"names":[],"mappings":"AAqCA;;GAEG;AACH;IACI,0BA0KC;CACJ;yBA1MwB,eAAe"}
+{"version":3,"file":"OneBoneSurfaceAlignmentSolver.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/ik/OneBoneSurfaceAlignmentSolver.js"],"names":[],"mappings":"AAkCA;;GAEG;AACH;IACI,0BA+GC;CACJ;yBA/IwB,eAAe"}

package/src/engine/ecs/ik/OneBoneSurfaceAlignmentSolver.js

@@ -1,13 +1,10 @@
 import { SurfacePoint3 } from "../../../core/geom/3d/SurfacePoint3.js";
 import Quaternion from "../../../core/geom/Quaternion.js";
-import { v3_displace_in_direction } from "../../../core/geom/vec3/v3_displace_in_direction.js";
-import { v3_dot } from "../../../core/geom/vec3/v3_dot.js";
-import { v3_length } from "../../../core/geom/vec3/v3_length.js";
 import Vector3 from "../../../core/geom/Vector3.js";
 import { clamp } from "../../../core/math/clamp.js";
-import { clamp01 } from "../../../core/math/clamp01.js";
 import { inverseLerp } from "../../../core/math/inverseLerp.js";
 import { findSkeletonBoneByType } from "../../graphics/ecs/mesh/SkeletonUtils.js";
+import { ik_probe_terrain_contact } from "./ik_probe_terrain_contact.js";
 import { IKSolver } from "./IKSolver.js";
 
 const boneWorldPosition = new Vector3();
@@ -71,85 +68,26 @@ export class OneBoneSurfaceAlignmentSolver extends IKSolver {
         parentWorldPosition.y = parentBoneWM[13];
         parentWorldPosition.z = parentBoneWM[14];
 
-        //compute direction for ray casting
-        const directionX = boneWorldPosition.x - parentWorldPosition.x;
-        const directionY = boneWorldPosition.y - parentWorldPosition.y;
-        const directionZ = boneWorldPosition.z - parentWorldPosition.z;
-
-
-        let contactExists = terrain.raycastFirstSync(
-            contact,
-            parentWorldPosition.x,
-            parentWorldPosition.y,
-            parentWorldPosition.z,
-            directionX,
-            directionY,
-            directionZ
-        );
-
-        if (!contactExists) {
-            //no contact
-            return;
-        }
-
-        const contactPosition = contact.position;
-        const contactNormal = contact.normal;
-
-        //perform secondary cast from the bone, back along the surface normal
-        contactExists = terrain.raycastFirstSync(
-            contact,
-            boneWorldPosition.x + contactNormal.x,
-            boneWorldPosition.y + contactNormal.y,
-            boneWorldPosition.z + contactNormal.z,
-            -contactNormal.x,
-            -contactNormal.y,
-            -contactNormal.z
-        );
-
-        if (!contactExists) {
-            //no contact
-            return;
-        }
-
-
         const bone_scale = boneWorldScale.length() * ONE_OVER_SQRT_3;
 
-        const targetOffsetDistance = constraint.offset * bone_scale;
-
-        v3_displace_in_direction(
+        //cast from the parent towards the bone to find the surface underneath it
+        let influence = ik_probe_terrain_contact(
             targetPosition,
-            targetOffsetDistance,
-            contactPosition.x, contactPosition.y, contactPosition.z,
-            contactNormal.x, contactNormal.y, contactNormal.z
+            contact,
+            terrain,
+            parentWorldPosition,
+            boneWorldPosition,
+            constraint,
+            bone_scale
         );
 
-        const delta_contact_c_x = targetPosition.x - boneWorldPosition.x;
-        const delta_contact_c_y = targetPosition.y - boneWorldPosition.y;
-        const delta_contact_c_z = targetPosition.z - boneWorldPosition.z;
-
-        //check if current effector position is above the contact point
-        const dot_contact_side = v3_dot(directionX, directionY, directionZ, delta_contact_c_x, delta_contact_c_y, delta_contact_c_z);
-
-        const delta_contact_c_length = v3_length(delta_contact_c_x, delta_contact_c_y, delta_contact_c_z);
-
-        let influence;
-
-        if (dot_contact_side < 0) {
-            //penetration detected
-            influence = 1;
-
-        } else {
-            //no penetration, hovering case, use hover distance for influence
-            const normalized_effector_distance = inverseLerp(0, bone_scale, delta_contact_c_length);
-
-            influence = 1 - clamp01(constraint.distance.normalizeValue(normalized_effector_distance));
-        }
-
         if (influence <= 0) {
-            //no influence
+            //no contact, or no influence
             return;
         }
 
+        const contactNormal = contact.normal;
+
         r.copy(bone.quaternion);
 
         //we want to make bone align orthogonally to surface contact normal

package/src/engine/ecs/ik/TwoBoneInverseKinematicsSolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TwoBoneInverseKinematicsSolver.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/ik/TwoBoneInverseKinematicsSolver.js"],"names":[],"mappings":"AA8CA;IAGI,0BAuIC;CACJ;yBA9KwB,eAAe"}
+{"version":3,"file":"TwoBoneInverseKinematicsSolver.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/ik/TwoBoneInverseKinematicsSolver.js"],"names":[],"mappings":"AA0CA;IAGI,0BA4EC;CACJ;yBAnHwB,eAAe"}

package/src/engine/ecs/ik/TwoBoneInverseKinematicsSolver.js

@@ -1,14 +1,10 @@
 import { assert } from "../../../core/assert.js";
 import { SurfacePoint3 } from "../../../core/geom/3d/SurfacePoint3.js";
 import Quaternion from "../../../core/geom/Quaternion.js";
-import { v3_displace_in_direction } from "../../../core/geom/vec3/v3_displace_in_direction.js";
-import { v3_dot } from "../../../core/geom/vec3/v3_dot.js";
-import { v3_length } from "../../../core/geom/vec3/v3_length.js";
 import Vector3 from "../../../core/geom/Vector3.js";
-import { clamp01 } from "../../../core/math/clamp01.js";
-import { inverseLerp } from "../../../core/math/inverseLerp.js";
 import { findSkeletonBoneByType } from "../../graphics/ecs/mesh/SkeletonUtils.js";
 import { two_joint_ik } from "../../physics/inverse_kinematics/two_joint_ik.js";
+import { ik_probe_terrain_contact } from "./ik_probe_terrain_contact.js";
 import { IKSolver } from "./IKSolver.js";
 
 const boneWorldPositionC = new Vector3();
@@ -72,81 +68,22 @@ export class TwoBoneInverseKinematicsSolver extends IKSolver {
         computeGlobalTransform(boneB, boneWorldPositionB, globalRotationB, v3);
         computeGlobalTransform(boneC, boneWorldPositionC, globalRotationC, v3);
 
-        //check if the there is a penetration with the terrain between the two bones
-        const directionX = boneWorldPositionC.x - boneWorldPositionA.x;
-        const directionY = boneWorldPositionC.y - boneWorldPositionA.y;
-        const directionZ = boneWorldPositionC.z - boneWorldPositionA.z;
-
-        let contactExists = terrain.raycastFirstSync(
-            contact,
-            boneWorldPositionA.x,
-            boneWorldPositionA.y,
-            boneWorldPositionA.z,
-            directionX,
-            directionY,
-            directionZ
-        );
-
-        if (!contactExists) {
-            //no contact
-            return;
-        }
-
-        const contactPosition = contact.position;
-        const contactNormal = contact.normal;
-
-        //perform secondary cast from the bone, back along the surface normal
-        contactExists = terrain.raycastFirstSync(
-            contact,
-            boneWorldPositionC.x + contactNormal.x,
-            boneWorldPositionC.y + contactNormal.y,
-            boneWorldPositionC.z + contactNormal.z,
-            -contactNormal.x,
-            -contactNormal.y,
-            -contactNormal.z
-        );
-
-        if (!contactExists) {
-            //no contact
-            return;
-        }
-
         //compute total length of the limb
         const limbLength = boneWorldPositionA.distanceTo(boneWorldPositionB) + boneWorldPositionB.distanceTo(boneWorldPositionC);
 
-        const targetOffsetDistance = constraint.offset * limbLength;
-
-        v3_displace_in_direction(
+        //check if there is a penetration with the terrain between the two bones
+        const influence = ik_probe_terrain_contact(
             targetPosition,
-            targetOffsetDistance,
-            contactPosition.x, contactPosition.y, contactPosition.z,
-            contact.normal.x, contact.normal.y, contact.normal.z
+            contact,
+            terrain,
+            boneWorldPositionA,
+            boneWorldPositionC,
+            constraint,
+            limbLength
         );
 
-        const delta_contact_c_x = targetPosition.x - boneWorldPositionC.x;
-        const delta_contact_c_y = targetPosition.y - boneWorldPositionC.y;
-        const delta_contact_c_z = targetPosition.z - boneWorldPositionC.z;
-
-        //check if current effector position is above the contact point
-        const dot_contact_side = v3_dot(directionX, directionY, directionZ, delta_contact_c_x, delta_contact_c_y, delta_contact_c_z);
-
-        const delta_contact_c_length = v3_length(delta_contact_c_x, delta_contact_c_y, delta_contact_c_z);
-
-        let influence;
-
-        if (dot_contact_side < 0) {
-            //penetration detected
-            influence = 1;
-
-        } else {
-            //no penetration, hovering case, use hover distance for influence
-            const normalized_effector_distance = inverseLerp(0, limbLength, delta_contact_c_length);
-
-            influence = 1 - clamp01(constraint.distance.normalizeValue(normalized_effector_distance));
-        }
-
         if (influence <= 0) {
-            //no influence
+            //no contact, or no influence
             return;
         }
 

package/src/engine/ecs/ik/ik_probe_terrain_contact.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Find where an IK chain meets the terrain and how strongly the solver should pull towards it.
+ *
+ * Two casts are made. The first travels from `origin` towards `effector` and establishes which
+ * surface the limb is over at all. The second starts just outside that surface, directly above the
+ * effector along the surface normal, and comes back down — that is what actually locates the point
+ * under the effector rather than the point under the limb's root, and it is what `out_contact` and
+ * `out_target` describe on return.
+ *
+ * The returned influence answers "how much of this correction should apply":
+ * - the effector is BELOW the surface (penetrating) → `1`, correct it fully;
+ * - the effector HOVERS above the surface → falls off from `1` to `0` across
+ *   `constraint.distance`, measured as a fraction of `length_scale`, so the same constraint reads
+ *   the same way for a long limb and a short one;
+ * - no surface was found at all → `0`.
+ *
+ * This exists because {@link TwoBoneInverseKinematicsSolver} and
+ * {@link OneBoneSurfaceAlignmentSolver} carried the identical ~70-line probe, comments and variable
+ * names included, differing only in which lengths they scaled by. The solvers now hold nothing but
+ * their rotation math.
+ *
+ * @param {Vector3} out_target receives the world position the effector should be moved to; only
+ * written when a non-zero influence is returned
+ * @param {SurfacePoint3} out_contact receives the surface contact from the SECOND cast; only
+ * written when a non-zero influence is returned. Solvers that need the contact normal (surface
+ * alignment) read it from here
+ * @param {Terrain} terrain
+ * @param {Vector3} origin start of the limb, the root bone's world position
+ * @param {Vector3} effector world position of the bone being placed. The probe direction is
+ * `effector - origin`, so these must not coincide
+ * @param {IKConstraint} constraint supplies `offset` (how far off the surface the effector rests)
+ * and `distance` (the hover band over which influence falls off)
+ * @param {number} length_scale limb length in world units; `constraint.offset` and the hover
+ * distance are both expressed relative to it. Must be greater than 0
+ * @returns {number} influence in `[0,1]`; `0` means "do nothing"
+ */
+export function ik_probe_terrain_contact(out_target: Vector3, out_contact: SurfacePoint3, terrain: Terrain, origin: Vector3, effector: Vector3, constraint: IKConstraint, length_scale: number): number;
+//# sourceMappingURL=ik_probe_terrain_contact.d.ts.map