@woosh/meep-engine 2.163.1 → 2.163.2

package/package.json

@@ -6,7 +6,7 @@
   "description": "Pure JavaScript game engine. Fully featured and production ready.",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "2.163.1",
+  "version": "2.163.2",
   "main": "build/meep.module.js",
   "module": "build/meep.module.js",
   "exports": {

package/src/engine/graphics/ecs/path/tube/build/build_geometry_catmullrom.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build_geometry_catmullrom.d.ts","sourceRoot":"","sources":["../../../../../../../../src/engine/graphics/ecs/path/tube/build/build_geometry_catmullrom.js"],"names":[],"mappings":"AAoFA;;;;;;;;;;GAUG;AACH,mFAPW,MAAM,EAAE,gBACR,MAAM,EAAE,GAAC,YAAY,mBACrB,MAAM,EAAE,iBACR,MAAM,eACN,MAAM,GACL,MAAM,cAAc,CAoI/B"}
+{"version":3,"file":"build_geometry_catmullrom.d.ts","sourceRoot":"","sources":["../../../../../../../../src/engine/graphics/ecs/path/tube/build/build_geometry_catmullrom.js"],"names":[],"mappings":"AAsJA;;;;;;;;;;GAUG;AACH,mFAPW,MAAM,EAAE,gBACR,MAAM,EAAE,GAAC,YAAY,mBACrB,MAAM,EAAE,iBACR,MAAM,eACN,MAAM,GACL,MAAM,cAAc,CAkJ/B"}

package/src/engine/graphics/ecs/path/tube/build/build_geometry_catmullrom.js

@@ -1,226 +1,306 @@
-import { v3_dot } from "../../../../../../core/geom/vec3/v3_dot.js";
-import { v3_length } from "../../../../../../core/geom/vec3/v3_length.js";
-import { clamp } from "../../../../../../core/math/clamp.js";
-import { max2 } from "../../../../../../core/math/max2.js";
-import {
-    computeNonuniformCaltmullRomSplineDerivative
-} from "../../../../../../core/math/spline/computeNonuniformCaltmullRomSplineDerivative.js";
-import { PathNormalType } from "../PathNormalType.js";
-import { computeFrenetFrames } from "./computeFrenetFrames.js";
-import { makeTubeGeometry } from "./makeTubeGeometry.js";
-
-
-const scratch_array_0 = [];
-const scratch_array_1 = [];
-const scratch_array_2 = [];
-const scratch_array_3 = [];
-
-/**
- *
- * @param {number[]} positions
- * @param {number[]} derivatives
- * @param {number} result_offset
- * @param {Path} path
- * @param {number} offset
- */
-function sample_path(positions, derivatives, result_offset, path, offset) {
-
-
-    if (!path.find_index_and_normalized_distance(scratch_array_0, offset)) {
-        return 0;
-    }
-
-
-    /**
-     *
-     * @type {number}
-     */
-    const i1 = scratch_array_0[0];
-
-    /**
-     *
-     * @type {number}
-     */
-    const t = scratch_array_0[1];
-
-
-    const input_length = path.getPointCount();
-
-    const max_index = input_length - 1;
-
-    const i0 = clamp(i1 - 1, 0, max_index);
-    const i2 = clamp(i1 + 1, 0, max_index);
-    const i3 = clamp(i1 + 2, 0, max_index);
-
-    path.readPositionToArray(i0, scratch_array_0, 0);
-    path.readPositionToArray(i1, scratch_array_1, 0);
-    path.readPositionToArray(i2, scratch_array_2, 0);
-    path.readPositionToArray(i3, scratch_array_3, 0);
-
-    computeNonuniformCaltmullRomSplineDerivative(
-        positions, result_offset,
-        derivatives, result_offset,
-        scratch_array_0, scratch_array_1, scratch_array_2, scratch_array_3,
-        3, t, 0.5
-    );
-
-    // normalize derivative
-    const dx = derivatives[result_offset];
-    const dy = derivatives[result_offset + 1];
-    const dz = derivatives[result_offset + 2];
-
-    const mag = v3_length(dx, dy, dz);
-
-    if (mag !== 0) {
-        const inv_mag = 1 / mag;
-
-        derivatives[result_offset] = dx * inv_mag;
-        derivatives[result_offset + 1] = dy * inv_mag;
-        derivatives[result_offset + 2] = dz * inv_mag;
-    }
-
-    return i1;
-}
-
-/**
- *
- * @param {Path} path
- * @param {TubePathStyle} style
- * @param {number[]} shape
- * @param {number[]|Float32Array} shape_normal
- * @param {number[]} shape_transform
- * @param {number} segment_start
- * @param {number} segment_end
- * @return {THREE.BufferGeometry}
- */
-export function build_geometry_catmullrom(
-    path, style,
-    shape, shape_normal, shape_transform,
-    segment_start, segment_end
-) {
-
-    const point_count = path.getPointCount();
-
-    // resample curve
-    const total_points = Math.ceil(point_count * style.resolution);
-
-    const reference_step_size = 1 / max2(0.00001, style.resolution);
-    const reference_min_step_size = reference_step_size * 0.25;
-
-    let step_size = reference_step_size;
-
-    const path_length = path.length;
-
-    const sample_positions_f32 = [];
-    const sample_derivatives_f32 = [];
-
-    let added_points = 0;
-
-    // initial segment
-    let last_knot_index = sample_path(
-        sample_positions_f32,
-        sample_derivatives_f32,
-        added_points * 3,
-        path,
-        segment_start * path_length
-    );
-
-    added_points++;
-
-    let current_offset = segment_start * path_length;
-
-    let step_resized_direction = 0;
-
-    const absolute_end_offset = segment_end * path_length;
-
-    for (; current_offset < absolute_end_offset; current_offset += step_size) {
-
-
-        const point_address = added_points * 3;
-
-        const knot_index = sample_path(
-            sample_positions_f32,
-            sample_derivatives_f32,
-            point_address,
-            path,
-            current_offset
-        );
-
-        // check difference with previous derivative
-        const previous_point_index = added_points - 1;
-        const previous_point_address = previous_point_index * 3;
-
-        // derivatives are basically normals, and dot product is has Cosine value of angle between two vectors
-        const dot = v3_dot(
-            sample_derivatives_f32[previous_point_address], sample_derivatives_f32[previous_point_address + 1], sample_derivatives_f32[previous_point_address + 2],
-            sample_derivatives_f32[point_address], sample_derivatives_f32[point_address + 1], sample_derivatives_f32[point_address + 2]
-        );
-
-        // angular difference results in larger visual error for longer runs
-        const error_size = (1 - dot) * step_size;
-
-        if (
-            (step_size > reference_min_step_size)
-            && (
-                (
-                    // check if we jumped over a knot, so that we can sample down to get closer to it
-                    knot_index > last_knot_index
-                    && step_size > reference_min_step_size
-                )
-                || (
-                    error_size * 10 > reference_min_step_size
-                    && step_resized_direction <= 0
-                )
-                || (
-                    // check if we're getting too close to the end of the segment, this lets us create a nice end
-                    current_offset + step_size > absolute_end_offset
-                )
-            )
-        ) {
-
-            // step looks to be too large
-            current_offset -= step_size;
-            step_size *= 0.5;
-            step_resized_direction = -1;
-            continue; // retry
-
-        } else if (
-            error_size < 0.02
-            && step_resized_direction >= 0
-        ) {
-
-            // step looks to be too small
-            current_offset -= step_size;
-            step_size *= 2;
-            step_resized_direction = 1;
-            continue; // retry
-
-        }
-
-        // reset adaptive step direction
-        step_resized_direction = 0;
-        // remember the last knot, so we know when we get to the end of the segment
-        last_knot_index = knot_index;
-
-        added_points++
-    }
-
-    if ((absolute_end_offset - current_offset + step_size) > 0.0001) {
-        // end
-
-        sample_path(sample_positions_f32, sample_derivatives_f32, added_points * 3, path, absolute_end_offset);
-
-        added_points++;
-    }
-
-    // console.log(`Total Points ${added_points}`) // DEBUG info
-
-    const normal_hint = style.path_normal_type === PathNormalType.FixedStart ? style.path_normal : undefined;
-
-    const frames = computeFrenetFrames(sample_positions_f32, false, normal_hint);
-
-    return makeTubeGeometry(
-        sample_positions_f32, frames.normals, frames.binormals, frames.tangents,
-        shape, shape_normal, shape.length / 2, shape_transform, false, style.cap_type
-    );
-}
+import { v3_dot } from "../../../../../../core/geom/vec3/v3_dot.js";
+import { v3_length } from "../../../../../../core/geom/vec3/v3_length.js";
+import { clamp } from "../../../../../../core/math/clamp.js";
+import { max2 } from "../../../../../../core/math/max2.js";
+import {
+    computeNonuniformCaltmullRomSplineDerivative
+} from "../../../../../../core/math/spline/computeNonuniformCaltmullRomSplineDerivative.js";
+import { PathNormalType } from "../PathNormalType.js";
+import { computeFrenetFrames } from "./computeFrenetFrames.js";
+import { makeTubeGeometry } from "./makeTubeGeometry.js";
+
+
+const scratch_array_0 = [];
+const scratch_array_1 = [];
+const scratch_array_2 = [];
+const scratch_array_3 = [];
+
+/**
+ *
+ * @param {number[]} positions
+ * @param {number[]} derivatives
+ * @param {number} result_offset
+ * @param {Path} path
+ * @param {number} offset
+ */
+function sample_path(positions, derivatives, result_offset, path, offset) {
+
+
+    if (!path.find_index_and_normalized_distance(scratch_array_0, offset)) {
+        return 0;
+    }
+
+
+    /**
+     *
+     * @type {number}
+     */
+    const i1 = scratch_array_0[0];
+
+    /**
+     *
+     * @type {number}
+     */
+    const t = scratch_array_0[1];
+
+
+    const input_length = path.getPointCount();
+
+    const max_index = input_length - 1;
+
+    const i0 = clamp(i1 - 1, 0, max_index);
+    const i2 = clamp(i1 + 1, 0, max_index);
+    const i3 = clamp(i1 + 2, 0, max_index);
+
+    path.readPositionToArray(i0, scratch_array_0, 0);
+    path.readPositionToArray(i1, scratch_array_1, 0);
+    path.readPositionToArray(i2, scratch_array_2, 0);
+    path.readPositionToArray(i3, scratch_array_3, 0);
+
+    computeNonuniformCaltmullRomSplineDerivative(
+        positions, result_offset,
+        derivatives, result_offset,
+        scratch_array_0, scratch_array_1, scratch_array_2, scratch_array_3,
+        3, t, 0.5
+    );
+
+    // normalize derivative
+    const dx = derivatives[result_offset];
+    const dy = derivatives[result_offset + 1];
+    const dz = derivatives[result_offset + 2];
+
+    const mag = v3_length(dx, dy, dz);
+
+    if (mag !== 0) {
+        const inv_mag = 1 / mag;
+
+        derivatives[result_offset] = dx * inv_mag;
+        derivatives[result_offset + 1] = dy * inv_mag;
+        derivatives[result_offset + 2] = dz * inv_mag;
+    }
+
+    return i1;
+}
+
+/**
+ * Stabilise one open-end frame. computeFrenetFrames derives the tangent at a
+ * path end from the end chord (P1-P0 / P[n]-P[n-1]); the adaptive resampler sets
+ * that neighbour's spacing, so on a curve the chord direction jumps frame to
+ * frame and swings the end cap (a small wobble becomes a >100-degree flip as an
+ * animated dash slides across a path knot). The analytic spline derivative is
+ * smooth in the path parameter and resampling-independent, so adopt it for the
+ * end tangent and re-orthogonalise the end normal/binormal around it.
+ *
+ * @param {{normals:Vector3[],binormals:Vector3[],tangents:Vector3[]}} frames
+ * @param {number[]|Float32Array} derivatives normalised per-sample spline derivatives
+ * @param {number} i sample index whose frame is stabilised
+ * @param {number} derivative_index sample to read the spline derivative from
+ *        (use an interior neighbour: the analytic derivative is bogus at the
+ *        path's exact parametric ends, param 0/1, where the spline clamps its
+ *        control points)
+ */
+function stabilize_end_frame(frames, derivatives, i, derivative_index) {
+    const d3 = derivative_index * 3;
+
+    let tx = derivatives[d3];
+    let ty = derivatives[d3 + 1];
+    let tz = derivatives[d3 + 2];
+
+    const tl = Math.sqrt(tx * tx + ty * ty + tz * tz);
+    if (!(tl > 1e-8)) {
+        // derivative unavailable/degenerate: keep the Frenet frame
+        return;
+    }
+    tx /= tl; ty /= tl; tz /= tl;
+
+    const N = frames.normals[i];
+
+    // The spline derivative already points 'forward' (towards increasing
+    // samples), the same orientation computeFrenetFrames uses, so adopt it as-is.
+    // (Aligning it to the OLD end tangent would re-import that tangent's jitter -
+    // when the jittery chord swings past 90 degrees the sign would flip and the
+    // cap axis would reverse.)
+    frames.tangents[i].set(tx, ty, tz);
+
+    // re-orthogonalise the existing normal against the new tangent (Gram-Schmidt)
+    const dot = N.x * tx + N.y * ty + N.z * tz;
+    let nx = N.x - dot * tx;
+    let ny = N.y - dot * ty;
+    let nz = N.z - dot * tz;
+    let nl = Math.sqrt(nx * nx + ny * ny + nz * nz);
+
+    if (!(nl > 1e-6)) {
+        // old normal was ~parallel to the new tangent: pick any perpendicular axis
+        const ax = Math.abs(tx), ay = Math.abs(ty), az = Math.abs(tz);
+        if (ax <= ay && ax <= az) { nx = 0; ny = -tz; nz = ty; }
+        else if (ay <= az) { nx = -tz; ny = 0; nz = tx; }
+        else { nx = -ty; ny = tx; nz = 0; }
+        nl = Math.sqrt(nx * nx + ny * ny + nz * nz);
+    }
+    nx /= nl; ny /= nl; nz /= nl;
+    N.set(nx, ny, nz);
+
+    // binormal = tangent x normal (matches computeFrenetFrames' convention)
+    frames.binormals[i].set(
+        ty * nz - tz * ny,
+        tz * nx - tx * nz,
+        tx * ny - ty * nx
+    );
+}
+
+/**
+ *
+ * @param {Path} path
+ * @param {TubePathStyle} style
+ * @param {number[]} shape
+ * @param {number[]|Float32Array} shape_normal
+ * @param {number[]} shape_transform
+ * @param {number} segment_start
+ * @param {number} segment_end
+ * @return {THREE.BufferGeometry}
+ */
+export function build_geometry_catmullrom(
+    path, style,
+    shape, shape_normal, shape_transform,
+    segment_start, segment_end
+) {
+
+    const point_count = path.getPointCount();
+
+    // resample curve
+    const total_points = Math.ceil(point_count * style.resolution);
+
+    const reference_step_size = 1 / max2(0.00001, style.resolution);
+    const reference_min_step_size = reference_step_size * 0.25;
+
+    let step_size = reference_step_size;
+
+    const path_length = path.length;
+
+    const sample_positions_f32 = [];
+    const sample_derivatives_f32 = [];
+
+    let added_points = 0;
+
+    // initial segment
+    let last_knot_index = sample_path(
+        sample_positions_f32,
+        sample_derivatives_f32,
+        added_points * 3,
+        path,
+        segment_start * path_length
+    );
+
+    added_points++;
+
+    let current_offset = segment_start * path_length;
+
+    let step_resized_direction = 0;
+
+    const absolute_end_offset = segment_end * path_length;
+
+    for (; current_offset < absolute_end_offset; current_offset += step_size) {
+
+
+        const point_address = added_points * 3;
+
+        const knot_index = sample_path(
+            sample_positions_f32,
+            sample_derivatives_f32,
+            point_address,
+            path,
+            current_offset
+        );
+
+        // check difference with previous derivative
+        const previous_point_index = added_points - 1;
+        const previous_point_address = previous_point_index * 3;
+
+        // derivatives are basically normals, and dot product is has Cosine value of angle between two vectors
+        const dot = v3_dot(
+            sample_derivatives_f32[previous_point_address], sample_derivatives_f32[previous_point_address + 1], sample_derivatives_f32[previous_point_address + 2],
+            sample_derivatives_f32[point_address], sample_derivatives_f32[point_address + 1], sample_derivatives_f32[point_address + 2]
+        );
+
+        // angular difference results in larger visual error for longer runs
+        const error_size = (1 - dot) * step_size;
+
+        if (
+            (step_size > reference_min_step_size)
+            && (
+                (
+                    // check if we jumped over a knot, so that we can sample down to get closer to it
+                    knot_index > last_knot_index
+                    && step_size > reference_min_step_size
+                )
+                || (
+                    error_size * 10 > reference_min_step_size
+                    && step_resized_direction <= 0
+                )
+                || (
+                    // check if we're getting too close to the end of the segment, this lets us create a nice end
+                    current_offset + step_size > absolute_end_offset
+                )
+            )
+        ) {
+
+            // step looks to be too large
+            current_offset -= step_size;
+            step_size *= 0.5;
+            step_resized_direction = -1;
+            continue; // retry
+
+        } else if (
+            error_size < 0.02
+            && step_resized_direction >= 0
+        ) {
+
+            // step looks to be too small
+            current_offset -= step_size;
+            step_size *= 2;
+            step_resized_direction = 1;
+            continue; // retry
+
+        }
+
+        // reset adaptive step direction
+        step_resized_direction = 0;
+        // remember the last knot, so we know when we get to the end of the segment
+        last_knot_index = knot_index;
+
+        added_points++
+    }
+
+    if ((absolute_end_offset - current_offset + step_size) > 0.0001) {
+        // end
+
+        sample_path(sample_positions_f32, sample_derivatives_f32, added_points * 3, path, absolute_end_offset);
+
+        added_points++;
+    }
+
+    // console.log(`Total Points ${added_points}`) // DEBUG info
+
+    const normal_hint = style.path_normal_type === PathNormalType.FixedStart ? style.path_normal : undefined;
+
+    const frames = computeFrenetFrames(sample_positions_f32, false, normal_hint);
+
+    // Stabilise the START frame so its round cap doesn't twitch as the adaptive
+    // resampling shifts. Only the start needs it: computeFrenetFrames' start
+    // tangent is the first chord (P1-P0), and the resampler's first-segment
+    // length/direction jitters frame to frame; the analytic derivative at the
+    // start sample is smooth in the path parameter. The END frame's tangent is
+    // already stable (the sampler approaches the end with a small, consistent
+    // final segment) and the analytic derivative is unreliable at the path's
+    // exact parametric end (param 1, where the spline clamps control points), so
+    // the end is deliberately left on its chord-based frame.
+    const last_sample_index = (sample_positions_f32.length / 3) - 1;
+    if (last_sample_index >= 2) {
+        stabilize_end_frame(frames, sample_derivatives_f32, 0, 0);
+    }
+
+    return makeTubeGeometry(
+        sample_positions_f32, frames.normals, frames.binormals, frames.tangents,
+        shape, shape_normal, shape.length / 2, shape_transform, false, style.cap_type
+    );
+}

package/src/engine/graphics/ecs/path/tube/build/make_cap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"make_cap.d.ts","sourceRoot":"","sources":["../../../../../../../../src/engine/graphics/ecs/path/tube/build/make_cap.js"],"names":[],"mappings":"AAwQA;;;;;;;;;;;;;;GAcG;AACH,4DAbW,MAAM,gBACN,YAAY,GAAC,MAAM,EAAE,cACrB,OAAO,EAAE,gBACT,OAAO,EAAE,eAET,OAAO,EAAE,SACT,MAAM,EAAE,gBACR,MAAM,EAAE,GAAC,YAAY,gBACrB,MAAM,mBACN,MAAM,EAAE,GAAC,YAAY,aACrB,MAAM,QACN,OAAO,QA6BjB;AAED;;;;;;GAMG;AACH,wDALW,MAAM,OACN;IAAC,aAAa,EAAC,MAAM,CAAC;IAAC,YAAY,EAAC,MAAM,CAAA;CAAC,mBAC3C,MAAM,QACN,OAAO,QAiBjB;wBA1UuB,OAAO;wBAMP,eAAe"}
+{"version":3,"file":"make_cap.d.ts","sourceRoot":"","sources":["../../../../../../../../src/engine/graphics/ecs/path/tube/build/make_cap.js"],"names":[],"mappings":"AAiRA;;;;;;;;;;;;;;GAcG;AACH,4DAbW,MAAM,gBACN,YAAY,GAAC,MAAM,EAAE,cACrB,OAAO,EAAE,gBACT,OAAO,EAAE,eAET,OAAO,EAAE,SACT,MAAM,EAAE,gBACR,MAAM,EAAE,GAAC,YAAY,gBACrB,MAAM,mBACN,MAAM,EAAE,GAAC,YAAY,aACrB,MAAM,QACN,OAAO,QA6BjB;AAED;;;;;;GAMG;AACH,wDALW,MAAM,OACN;IAAC,aAAa,EAAC,MAAM,CAAC;IAAC,YAAY,EAAC,MAAM,CAAA;CAAC,mBAC3C,MAAM,QACN,OAAO,QAiBjB;wBAnVuB,OAAO;wBAMP,eAAe"}

package/src/engine/graphics/ecs/path/tube/build/make_cap.js

@@ -79,31 +79,40 @@ function make_cap_round(
     const B = in_binormals[index];
     const T = in_tangents[index];
 
-    // Outward cap axis. Derive it from the PATH itself (the segment between the
-    // cap and its neighbour sample) rather than from N x B: the Frenet frame's
-    // tangent can flip sign at curvature features, and an N x B-derived axis
-    // would then make the cap bulge inward for a frame ("cap twists off-axis").
-    // The path direction is always well-defined and outward. Fall back to the
-    // frame only if the neighbour sample is coincident (degenerate segment).
+    // Outward cap axis. The dome bulges along the tube tangent at the cap; the
+    // axis must point outward (away from the body) and be stable frame to frame.
+    // T is the per-sample curve tangent, oriented towards increasing samples
+    // ("forward"). Outward is therefore backward at the start cap and forward at
+    // the end cap - i.e. -direction * T - a sign that depends only on which end
+    // this is, never on the neighbour sample. The old code derived the axis from
+    // the neighbour chord (cap point minus the adjacent sample); that points
+    // outward but its DIRECTION jitters, because the adaptive resampler sets the
+    // neighbour's spacing and on a curve a longer/shorter first segment points a
+    // different way - so the chord, and the dome with it, swung as animated
+    // dashes slid across path knots (the "twitch"). The neighbour chord is now
+    // only a fallback for when T is unavailable.
     const point_count = in_positions.length / 3;
     const neighbour = direction > 0
         ? Math.min(index + 1, point_count - 1)
         : Math.max(index - 1, 0);
     const n3 = neighbour * 3;
 
-    const tangent = new Vector3(
-        Px - in_positions[n3],
-        Py - in_positions[n3 + 1],
-        Pz - in_positions[n3 + 2]
-    );
+    const tangent = new Vector3();
 
-    if (tangent.lengthSq() > 1e-12) {
-        tangent.normalize();
+    if (T !== undefined && T.lengthSq() > 1e-12) {
+        tangent.copy(T).normalize().multiplyScalar(-direction);
     } else {
-        // degenerate: neighbour coincides with the cap point, use the frame
-        tangent.crossVectors(N, B);
-        tangent.normalize();
-        tangent.multiplyScalar(-direction);
+        const out_x = Px - in_positions[n3];
+        const out_y = Py - in_positions[n3 + 1];
+        const out_z = Pz - in_positions[n3 + 2];
+
+        if ((out_x * out_x + out_y * out_y + out_z * out_z) > 1e-12) {
+            // no usable tangent: the neighbour chord already points outward
+            tangent.set(out_x, out_y, out_z).normalize();
+        } else {
+            // fully degenerate: derive the axis from the frame
+            tangent.crossVectors(N, B).normalize().multiplyScalar(-direction);
+        }
     }
 
     // Use the path frame's N/B directly for BOTH ends. The profile orientation