@driftengine/core 3.61.0

package/dist/geometry/shellFill.js

@@ -0,0 +1,203 @@
+/**
+ * Closing the inside of a model that is only a surface.
+ *
+ * **The problem is common and it is not a defect in any one asset.** A great many bought models
+ * are exterior shells: a car with no cabin, a building with no rooms, a figure that is skin and
+ * nothing under it. Drawn on their own they are correct, and the moment a viewer can see through
+ * an opening in them — a grille, a vent, a window aperture, a doorway — they look straight
+ * through the object and out the far side. It reads as a rendering fault and is not one.
+ *
+ * Two pieces are needed and neither replaces the other, which is the whole design here:
+ *
+ * - **A copy of the model, drawn inside itself.** It follows every curve exactly, because it *is*
+ *   every curve, so it backs each panel with no tuning and no knowledge of what the model is. It
+ *   cannot help with an opening, because a copy of a shell has the same hole in the same place.
+ * - **A generated solid, behind it.** It has no holes, so it is what a viewer sees through one.
+ *   It cannot follow a surface, so it is held well inside and never asked to.
+ *
+ * **Everything here takes sizes and numbers.** What a subject looks like is the caller's to state,
+ * through `profile`: this module knows about bounds and fractions and nothing about cars.
+ */
+import { MeshBuilder } from './meshBuilder.js';
+/**
+ * A plain inset block, which is the safe answer for a shape nothing is known about.
+ *
+ * Deliberately not clever. A profile that guessed at a silhouette would be wrong for most models
+ * and wrong in the one direction that shows: standing out through the surface it is meant to sit
+ * behind. A caller that knows what its subject looks like passes a better one.
+ */
+export const DEFAULT_SHELL_PROFILE = [
+    { at: 0, width: 0.7, waist: 0.8, roofWidth: 0, top: 0.8 },
+    { at: 0.2, width: 1, waist: 0.95, roofWidth: 0, top: 0.95 },
+    { at: 0.8, width: 1, waist: 0.95, roofWidth: 0, top: 0.95 },
+    { at: 1, width: 0.7, waist: 0.8, roofWidth: 0, top: 0.8 },
+];
+const DEFAULT_COLOR = [0.012, 0.012, 0.014];
+/** The profile between its stations, so the slice count and the shape stay independent. */
+function stationAt(profile, t) {
+    for (let i = 1; i < profile.length; i++) {
+        const b = profile[i];
+        if (t > b.at)
+            continue;
+        const a = profile[i - 1];
+        const span = b.at - a.at;
+        const k = span <= 0 ? 0 : (t - a.at) / span;
+        const mix = (from, to) => from + (to - from) * k;
+        return {
+            at: t,
+            width: mix(a.width, b.width),
+            waist: mix(a.waist, b.waist),
+            /*
+             * Between a station with an upper mass and one without, the narrower wins rather than the
+             * average: half an upper mass standing out of the surface is worse than a little less fill.
+             */
+            roofWidth: a.roofWidth === 0 || b.roofWidth === 0 ? 0 : mix(a.roofWidth, b.roofWidth),
+            top: mix(a.top, b.top),
+        };
+    }
+    return profile[profile.length - 1];
+}
+/**
+ * One box, with every face emitted twice so it is solid from either side.
+ *
+ * A box is only opaque from outside it: its faces point away from its centre, so a camera within
+ * one has every face turned away and sees nothing at all. Reversing the corner order reverses
+ * which side is drawn, and emitting both is what closes the volume from any position.
+ */
+function addSolidBox(builder, min, max, color) {
+    const [x0, y0, z0] = min;
+    const [x1, y1, z1] = max;
+    const faces = [
+        [
+            [x0, y0, z1],
+            [x1, y0, z1],
+            [x1, y1, z1],
+            [x0, y1, z1],
+        ],
+        [
+            [x1, y0, z0],
+            [x0, y0, z0],
+            [x0, y1, z0],
+            [x1, y1, z0],
+        ],
+        [
+            [x1, y0, z1],
+            [x1, y0, z0],
+            [x1, y1, z0],
+            [x1, y1, z1],
+        ],
+        [
+            [x0, y0, z0],
+            [x0, y0, z1],
+            [x0, y1, z1],
+            [x0, y1, z0],
+        ],
+        [
+            [x0, y1, z1],
+            [x1, y1, z1],
+            [x1, y1, z0],
+            [x0, y1, z0],
+        ],
+        [
+            [x0, y0, z0],
+            [x1, y0, z0],
+            [x1, y0, z1],
+            [x0, y0, z1],
+        ],
+    ];
+    for (const [a, b, c, d] of faces) {
+        builder.addQuad(a, b, c, d, color, 0, 0.05);
+        builder.addQuad(d, c, b, a, color, 0, 0.05);
+    }
+}
+/**
+ * A solid to stand inside a hollow model, sized from the space it has to fill.
+ *
+ * `size` is the model's own extent in metres and `baseY` where its underside sits, which is all
+ * this needs: the solid is centred on the origin in x and z, as a fitted model is.
+ */
+export function buildShellFill(size, baseY, options = {}) {
+    const color = options.color ?? DEFAULT_COLOR;
+    const inset = options.inset ?? 0.78;
+    const lengthInset = options.lengthInset ?? 0.86;
+    const slices = Math.max(1, Math.floor(options.slices ?? 24));
+    const profile = options.profile ?? DEFAULT_SHELL_PROFILE;
+    const builder = new MeshBuilder();
+    builder.setRoughness(0.95);
+    const halfWidth = (size.x / 2) * inset;
+    const bottom = baseY + size.y * (options.floor ?? 0.1);
+    const usableZ = size.z * lengthInset;
+    const step = usableZ / slices;
+    for (let i = 0; i < slices; i++) {
+        /* Sampled at the slice's middle, so its box is the profile there rather than at an edge. */
+        const t = (i + 0.5) / slices;
+        const shape = stationAt(profile, t);
+        const centreZ = -usableZ / 2 + (i + 0.5) * step;
+        /* Half a step of overlap each side, so neighbouring slices leave no seam to see through. */
+        const halfZ = step * 0.6;
+        const waist = baseY + size.y * shape.waist * inset;
+        if (waist > bottom) {
+            const halfX = halfWidth * shape.width;
+            addSolidBox(builder, [-halfX, bottom, centreZ - halfZ], [halfX, waist, centreZ + halfZ], color);
+        }
+        const top = baseY + size.y * shape.top * inset;
+        if (shape.roofWidth > 0.02 && top > waist) {
+            const halfX = halfWidth * shape.roofWidth;
+            addSolidBox(builder, [-halfX, waist, centreZ - halfZ], [halfX, top, centreZ + halfZ], color);
+        }
+    }
+    return builder.build();
+}
+/**
+ * The same surface, in one flat colour and facing both ways.
+ *
+ * This is the half that follows the model exactly. Drawn slightly smaller and inside the original
+ * it backs every panel with no tuning at all, and it is given a single colour because otherwise
+ * an opening shows the model's own brightwork through it, which is what it exists to hide.
+ *
+ * Both windings are emitted for the reason `addSolidBox` emits both: a shell is opaque only from
+ * the side its triangles face, and this one is looked at from inside as often as out. Normals are
+ * negated with the reversed copy, or the inward face is shaded as though lit from within.
+ */
+export function shellSkin(mesh, color = DEFAULT_COLOR) {
+    const vertices = mesh.positions.length / 3;
+    const count = mesh.indices.length;
+    const positions = new Float32Array(mesh.positions.length * 2);
+    positions.set(mesh.positions, 0);
+    positions.set(mesh.positions, mesh.positions.length);
+    const normals = new Float32Array(mesh.normals.length * 2);
+    normals.set(mesh.normals, 0);
+    for (let i = 0; i < mesh.normals.length; i++) {
+        normals[mesh.normals.length + i] = -mesh.normals[i];
+    }
+    const colors = new Float32Array(vertices * 2 * 3);
+    for (let i = 0; i < vertices * 2; i++) {
+        colors[i * 3] = color[0];
+        colors[i * 3 + 1] = color[1];
+        colors[i * 3 + 2] = color[2];
+    }
+    const indices = new Uint32Array(count * 2);
+    indices.set(mesh.indices, 0);
+    for (let i = 0; i + 2 < count; i += 3) {
+        indices[count + i] = mesh.indices[i];
+        indices[count + i + 1] = mesh.indices[i + 2];
+        indices[count + i + 2] = mesh.indices[i + 1];
+    }
+    return { positions, normals, colors, indices, emissive: new Float32Array(vertices * 2) };
+}
+/**
+ * A uniform scale about a height, for drawing a skin just inside the model it came from.
+ *
+ * The translation column is what keeps the shrink centred on the model rather than on the world
+ * origin: scaling about zero would drop it through whatever it stands on by a fraction of its own
+ * height, which is small enough to look like a shadow fault rather than like this.
+ */
+export function shellFillMatrix(scale, centreY, out) {
+    out.fill(0);
+    out[0] = scale;
+    out[5] = scale;
+    out[10] = scale;
+    out[13] = centreY * (1 - scale);
+    out[15] = 1;
+    return out;
+}

package/dist/geometry/spline.d.ts

@@ -0,0 +1,162 @@
+/**
+ * An arc-length parameterised curve with a rotation-minimising frame — the
+ * spine every banked surface in the engine is built on.
+ *
+ * Two properties do all the work, and both are the difference between a track
+ * and a mess:
+ *
+ * **Sampled by distance, not by parameter.** A Catmull-Rom curve evaluated at
+ * evenly spaced `t` bunches its samples where the curve is tight and stretches
+ * them on the straights. A surface built that way has triangles the size of a
+ * room on the fast sections and a width that pulses through every bend.
+ *
+ * **The frame is transported, not recomputed.** Deriving an up-vector from
+ * world up at each sample flips it the moment the tangent passes vertical, and
+ * the surface turns inside out for one segment — a hole that appears on exactly
+ * one shape and is invisible everywhere else. Carrying the frame forward from
+ * the previous sample cannot flip, because there is nothing to flip relative to.
+ *
+ * The engine never learns what this curve is *for*. It takes numbers.
+ */
+import type { Vec3 } from '../math/color.ts';
+export interface SplinePoint {
+    x: number;
+    y: number;
+    z: number;
+    /**
+     * Roll about the direction of travel, radians. Positive lifts the right-hand
+     * edge — the bank of a left-hand corner.
+     */
+    bankRad: number;
+    /** Full width of the surface here, metres. */
+    widthM: number;
+}
+/**
+ * One evaluated point. Written into by `sampleAt`, never returned, because this
+ * runs inside the fixed tick.
+ */
+export interface SplineSample {
+    x: number;
+    y: number;
+    z: number;
+    /** Unit direction of travel. */
+    tangentX: number;
+    tangentY: number;
+    tangentZ: number;
+    /** Unit surface up, after banking. */
+    normalX: number;
+    normalY: number;
+    normalZ: number;
+    /** Unit across-surface, after banking. Points to the character's right. */
+    rightX: number;
+    rightY: number;
+    rightZ: number;
+    bankRad: number;
+    widthM: number;
+}
+export declare function createSplineSample(): SplineSample;
+export declare class Spline {
+    private readonly px;
+    private readonly py;
+    private readonly pz;
+    private readonly bank;
+    private readonly width;
+    /** Number of curve segments: one fewer than the control points. */
+    private readonly segments;
+    /**
+     * The control points with a reflected phantom at each end, so a segment reads its
+     * four points as `ex[s] … ex[s + 3]` with no bounds test and no end case.
+     *
+     * The reflection is what makes the curve reach its own endpoints rather than
+     * stopping one control point short, and it used to be recomputed — with its two
+     * branches — inside every evaluation. It is a property of the point list, so it is
+     * computed once with the point list.
+     */
+    private readonly ex;
+    private readonly ey;
+    private readonly ez;
+    /**
+     * Centripetal knots per segment, as the three non-zero values: `t0` is always 0.
+     *
+     * These cost three `hypot`s and three square roots, and they depend only on which
+     * segment you are in — never on where you are inside it. Evaluating the curve
+     * recomputed them every time regardless, which was the single most expensive thing
+     * the engine did: **`sampleAt` alone evaluates three times** (the point, and one
+     * either side for the central-difference tangent), so one sample paid for nine of
+     * each. The arc-length table is thousands of evaluations per curve, `buildRibbon`
+     * is thousands more, and the simulation samples the route every tick.
+     *
+     * Hoisting them changes no arithmetic: the same expression on the same inputs, run
+     * once per segment instead of once per ask.
+     */
+    private readonly knot1;
+    private readonly knot2;
+    private readonly knot3;
+    /** Arc-length table, in parallel columns. */
+    private readonly tableParam;
+    private readonly tableDist;
+    private readonly tableX;
+    private readonly tableY;
+    private readonly tableZ;
+    private readonly tableUpX;
+    private readonly tableUpY;
+    private readonly tableUpZ;
+    private readonly length;
+    constructor(points: readonly SplinePoint[]);
+    get lengthM(): number;
+    /** Control points, for callers that need the authored shape back. */
+    get pointCount(): number;
+    /**
+     * Where an arc length falls in control-point terms: `index + fraction`.
+     *
+     * The inverse of `distanceAtPoint`, for a caller that measured something along
+     * the curve and needs to write the answer back onto the points that produced it.
+     * The fraction matters as much as the index — bank and width are blended between
+     * two control points, so attributing a measurement to one of them without
+     * knowing which one dominates there gets the wrong point by half the time.
+     */
+    pointParamAt(distanceM: number): number;
+    /**
+     * Arc length at control point `index`.
+     *
+     * A generator authors in control points — "the gap runs from the sixth point
+     * to the eighth" — but everything downstream is in metres, and the conversion
+     * is only knowable once the curve exists. Without this the caller has to
+     * guess, and a guessed hole is a hole in the wrong place.
+     */
+    distanceAtPoint(index: number): number;
+    /**
+     * Carry an up-vector along the curve rather than deriving one at each sample.
+     *
+     * Each step rotates the previous up by the rotation that takes the previous
+     * tangent onto this one — the discrete rotation-minimising frame. On a planar
+     * curve it holds up exactly constant; through a climb past vertical it simply
+     * follows, because it never consults world up again after the first sample.
+     */
+    private transportFrames;
+    /** Unit tangent at table entry `i`, from its neighbours' positions. */
+    private tangentAt;
+    /**
+     * Curve position at segment `s`, local parameter `u`, into `out[0..2]`.
+     *
+     * Nothing here depends on anything but `u`: the four points are read straight out
+     * of the phantom-extended arrays and the knots were measured when the curve was
+     * built. What is left is the interpolation itself, which is the only part that
+     * could not have been done in advance.
+     */
+    private evaluate;
+    /** Curve position at a global parameter (segment index plus local u). */
+    private evaluateParam;
+    /** Largest table index whose distance is at most `d`. */
+    private findCell;
+    /**
+     * Evaluate the curve at an arc length, clamped to its ends.
+     *
+     * Allocation-free by contract: it is called from the simulation, from the
+     * generator and from the mesh builder, and the first of those makes it a hot
+     * path rule rather than a preference.
+     */
+    sampleAt(distanceM: number, out: SplineSample): void;
+}
+/** Convenience for callers building control points from a colour-carrying path. */
+export type SplineColor = Vec3;