@woosh/meep-engine 2.163.0 → 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.0",
+  "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/makeTubeGeometry.js

@@ -1,202 +1,218 @@
-import { BufferGeometry, Vector3 } from "three";
-import { assert } from "../../../../../../core/assert.js";
-import { v3_angle_cos_between } from "../../../../../../core/geom/vec3/v3_angle_cos_between.js";
-import { v3_length } from "../../../../../../core/geom/vec3/v3_length.js";
-import { CapType } from "../CapType.js";
-import { append_compute_cap_geometry_size, make_cap } from "./make_cap.js";
-import { make_ring_faces } from "./make_ring_faces.js";
-import { make_ring_vertices } from "./make_ring_vertices.js";
-import { StreamGeometryBuilder } from "./StreamGeometryBuilder.js";
-
-
-const v4_array = new Float32Array(4);
-
-/**
- * @see https://github.com/mrdoob/three.js/blob/master/src/geometries/TubeGeometry.js
- * @see https://github.com/hofk/THREEg.js/blob/488f1128a25321a76888aa1fa19db64750318444/THREEg.js#L3483
- * @param {Float32Array|number[]} in_positions
- * @param {Vector3[]} in_normals
- * @param {Vector3[]} in_binormals
- * @param {Vector3[]} in_tangents
- * @param {number[]} shape
- * @param {number[]|Float32Array} shape_normal
- * @param {number} shape_length
- * @param {number[]|Float32Array} shape_transform
- * @param {boolean} [closed]
- * @param {CapType} [cap_type]
- * @returns {BufferGeometry}
- */
-export function makeTubeGeometry(
-    in_positions, in_normals, in_binormals, in_tangents,
-    shape, shape_normal, shape_length, shape_transform, closed = false, cap_type = CapType.Round
-) {
-    assert.enum(cap_type, CapType, 'cap_type');
-    assert.isBoolean(closed, 'closed');
-
-    assert.isNumber(shape_length, 'shape_length');
-    assert.isArrayLike(shape, 'shape');
-
-    const out = new StreamGeometryBuilder();
-
-    // helper variables
-
-    const point_count = in_positions.length / 3;
-    const tubular_segments = point_count - 1;
-
-
-    const geometry_size = {
-        vertex_count: (tubular_segments + 1) * (shape_length + 1),
-        polygon_count: tubular_segments * shape_length * 2
-    };
-
-    if (!closed) {
-        append_compute_cap_geometry_size(2, geometry_size, shape_length, cap_type);
-    }
-
-    out.allocate(
-        geometry_size.vertex_count,
-        geometry_size.polygon_count
-    );
-
-    // create buffer data
-
-    if (!closed) {
-        // start cap
-        make_cap(
-            out, 0,
-            in_positions, in_normals, in_binormals, in_tangents,
-            shape, shape_normal, shape_length, shape_transform, 1, cap_type
-        );
-    }
-
-    const index_offset = out.cursor_vertices;
-
-    for (let i = 0; i < tubular_segments; i++) {
-
-        generateSegment(i);
-
-    }
-
-    // if the geometry is not closed, generate the last row of vertices and normals
-    // at the regular position on the given path
-    //
-    // if the geometry is closed, duplicate the first row of vertices and normals (uvs will differ)
-
-    generateSegment((closed === false) ? tubular_segments : 0);
-
-    // finally create faces
-    make_ring_faces(out, index_offset, tubular_segments, shape_length);
-
-    if (!closed) {
-        // end cap
-        make_cap(
-            out, point_count - 1,
-            in_positions, in_normals, in_binormals, in_tangents,
-            shape, shape_normal, shape_length, shape_transform, -1, cap_type
-        );
-    }
-
-    /**
-     *
-     * @param {number} i
-     */
-    function generateSegment(i) {
-
-        // we use getPointAt to sample evenly distributed points from the given path
-
-        const i3 = i * 3;
-
-        const Px = in_positions[i3];
-        const Py = in_positions[i3 + 1];
-        const Pz = in_positions[i3 + 2];
-
-        // retrieve corresponding normal and binormal
-
-        const N = in_normals[i];
-        const B = in_binormals[i];
-
-        // generate normals and vertices for the current segment
-        compute_bend_normal(v4_array, i, tubular_segments, in_positions);
-
-        make_ring_vertices(
-            out,
-            Px, Py, Pz,
-            N, B, in_tangents[i],
-            i / tubular_segments, v4_array,
-            shape, shape_normal, shape_length, shape_transform
-        );
-
-    }
-
-
-    return out.build();
-}
-
-
-/**
- *
- * @param {number[]|Float32Array} out
- * @param {number} index
- * @param {number} index_count
- * @param {number[]|Float32Array} positions
- */
-function compute_bend_normal(
-    out,
-    index,
-    index_count,
-    positions
-) {
-    if (index <= 0 || index >= index_count - 1) {
-        // end points, no bending
-
-        out[0] = 0;
-        out[1] = 1;
-        out[2] = 0;
-        out[3] = 0;
-
-        return;
-    }
-
-    const index_next = index + 1;
-    const index_prev = index - 1;
-
-    const address_current = index * 3;
-    const address_next = index_next * 3;
-    const address_prev = index_prev * 3;
-
-    const i0_x = positions[address_prev];
-    const i0_y = positions[address_prev + 1];
-    const i0_z = positions[address_prev + 2];
-
-    const i1_x = positions[address_current];
-    const i1_y = positions[address_current + 1];
-    const i1_z = positions[address_current + 2];
-
-    const i2_x = positions[address_next];
-    const i2_y = positions[address_next + 1];
-    const i2_z = positions[address_next + 2];
-
-    const d0_x = i0_x - i1_x;
-    const d0_y = i0_y - i1_y;
-    const d0_z = i0_z - i1_z;
-
-    const d1_x = i1_x - i2_x;
-    const d1_y = i1_y - i2_y;
-    const d1_z = i1_z - i2_z;
-
-    // compute rotation axis
-    const cross_x = d0_y * d1_z - d0_z * d1_y;
-    const cross_y = d0_z * d1_x - d0_x * d1_z;
-    const cross_z = d0_x * d1_y - d0_y * d1_x;
-
-    const angle = v3_angle_cos_between(d0_x, d0_y, d0_z, d1_x, d1_y, d1_z);
-
-    const length_inv = 1 / v3_length(cross_x, cross_y, cross_z);
-
-    out[0] = cross_x * length_inv;
-    out[1] = cross_y * length_inv;
-    out[2] = cross_z * length_inv;
-
-    // bend amount
-    out[3] = (1 - Math.abs(angle)) * 0.5;
-}
+import { BufferGeometry, Vector3 } from "three";
+import { assert } from "../../../../../../core/assert.js";
+import { v3_angle_cos_between } from "../../../../../../core/geom/vec3/v3_angle_cos_between.js";
+import { v3_length } from "../../../../../../core/geom/vec3/v3_length.js";
+import { CapType } from "../CapType.js";
+import { append_compute_cap_geometry_size, make_cap } from "./make_cap.js";
+import { make_ring_faces } from "./make_ring_faces.js";
+import { make_ring_vertices } from "./make_ring_vertices.js";
+import { StreamGeometryBuilder } from "./StreamGeometryBuilder.js";
+
+
+const v4_array = new Float32Array(4);
+
+/**
+ * @see https://github.com/mrdoob/three.js/blob/master/src/geometries/TubeGeometry.js
+ * @see https://github.com/hofk/THREEg.js/blob/488f1128a25321a76888aa1fa19db64750318444/THREEg.js#L3483
+ * @param {Float32Array|number[]} in_positions
+ * @param {Vector3[]} in_normals
+ * @param {Vector3[]} in_binormals
+ * @param {Vector3[]} in_tangents
+ * @param {number[]} shape
+ * @param {number[]|Float32Array} shape_normal
+ * @param {number} shape_length
+ * @param {number[]|Float32Array} shape_transform
+ * @param {boolean} [closed]
+ * @param {CapType} [cap_type]
+ * @returns {BufferGeometry}
+ */
+export function makeTubeGeometry(
+    in_positions, in_normals, in_binormals, in_tangents,
+    shape, shape_normal, shape_length, shape_transform, closed = false, cap_type = CapType.Round
+) {
+    assert.enum(cap_type, CapType, 'cap_type');
+    assert.isBoolean(closed, 'closed');
+
+    assert.isNumber(shape_length, 'shape_length');
+    assert.isArrayLike(shape, 'shape');
+
+    const out = new StreamGeometryBuilder();
+
+    // helper variables
+
+    const point_count = in_positions.length / 3;
+    const tubular_segments = point_count - 1;
+
+
+    const geometry_size = {
+        vertex_count: (tubular_segments + 1) * (shape_length + 1),
+        polygon_count: tubular_segments * shape_length * 2
+    };
+
+    if (!closed) {
+        append_compute_cap_geometry_size(2, geometry_size, shape_length, cap_type);
+    }
+
+    out.allocate(
+        geometry_size.vertex_count,
+        geometry_size.polygon_count
+    );
+
+    // create buffer data
+
+    if (!closed) {
+        // start cap
+        make_cap(
+            out, 0,
+            in_positions, in_normals, in_binormals, in_tangents,
+            shape, shape_normal, shape_length, shape_transform, 1, cap_type
+        );
+    }
+
+    const index_offset = out.cursor_vertices;
+
+    for (let i = 0; i < tubular_segments; i++) {
+
+        generateSegment(i);
+
+    }
+
+    // if the geometry is not closed, generate the last row of vertices and normals
+    // at the regular position on the given path
+    //
+    // if the geometry is closed, duplicate the first row of vertices and normals (uvs will differ)
+
+    generateSegment((closed === false) ? tubular_segments : 0);
+
+    // finally create faces
+    make_ring_faces(out, index_offset, tubular_segments, shape_length);
+
+    if (!closed) {
+        // end cap
+        make_cap(
+            out, point_count - 1,
+            in_positions, in_normals, in_binormals, in_tangents,
+            shape, shape_normal, shape_length, shape_transform, -1, cap_type
+        );
+    }
+
+    /**
+     *
+     * @param {number} i
+     */
+    function generateSegment(i) {
+
+        // we use getPointAt to sample evenly distributed points from the given path
+
+        const i3 = i * 3;
+
+        const Px = in_positions[i3];
+        const Py = in_positions[i3 + 1];
+        const Pz = in_positions[i3 + 2];
+
+        // retrieve corresponding normal and binormal
+
+        const N = in_normals[i];
+        const B = in_binormals[i];
+
+        // generate normals and vertices for the current segment
+        compute_bend_normal(v4_array, i, tubular_segments, in_positions);
+
+        make_ring_vertices(
+            out,
+            Px, Py, Pz,
+            N, B, in_tangents[i],
+            i / tubular_segments, v4_array,
+            shape, shape_normal, shape_length, shape_transform
+        );
+
+    }
+
+
+    return out.build();
+}
+
+
+/**
+ *
+ * @param {number[]|Float32Array} out
+ * @param {number} index
+ * @param {number} index_count
+ * @param {number[]|Float32Array} positions
+ */
+function compute_bend_normal(
+    out,
+    index,
+    index_count,
+    positions
+) {
+    if (index <= 0 || index >= index_count - 1) {
+        // end points, no bending
+
+        out[0] = 0;
+        out[1] = 1;
+        out[2] = 0;
+        out[3] = 0;
+
+        return;
+    }
+
+    const index_next = index + 1;
+    const index_prev = index - 1;
+
+    const address_current = index * 3;
+    const address_next = index_next * 3;
+    const address_prev = index_prev * 3;
+
+    const i0_x = positions[address_prev];
+    const i0_y = positions[address_prev + 1];
+    const i0_z = positions[address_prev + 2];
+
+    const i1_x = positions[address_current];
+    const i1_y = positions[address_current + 1];
+    const i1_z = positions[address_current + 2];
+
+    const i2_x = positions[address_next];
+    const i2_y = positions[address_next + 1];
+    const i2_z = positions[address_next + 2];
+
+    const d0_x = i0_x - i1_x;
+    const d0_y = i0_y - i1_y;
+    const d0_z = i0_z - i1_z;
+
+    const d1_x = i1_x - i2_x;
+    const d1_y = i1_y - i2_y;
+    const d1_z = i1_z - i2_z;
+
+    // compute rotation axis
+    const cross_x = d0_y * d1_z - d0_z * d1_y;
+    const cross_y = d0_z * d1_x - d0_x * d1_z;
+    const cross_z = d0_x * d1_y - d0_y * d1_x;
+
+    const angle = v3_angle_cos_between(d0_x, d0_y, d0_z, d1_x, d1_y, d1_z);
+
+    const cross_length = v3_length(cross_x, cross_y, cross_z);
+
+    if (cross_length < 1e-10) {
+        // Collinear (or duplicate) neighbours: zero curvature, so no bend.
+        // The rotation axis is undefined here and computing it would be
+        // 0 / 0 = NaN, poisoning this ring's vertices (visible as shattered
+        // geometry on short / straight resampled segments, e.g. the animated
+        // marching dashes). Emit the same no-bend value the path ends use.
+        out[0] = 0;
+        out[1] = 1;
+        out[2] = 0;
+        out[3] = 0;
+
+        return;
+    }
+
+    const length_inv = 1 / cross_length;
+
+    out[0] = cross_x * length_inv;
+    out[1] = cross_y * length_inv;
+    out[2] = cross_z * length_inv;
+
+    // bend amount
+    out[3] = (1 - Math.abs(angle)) * 0.5;
+}

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