@series-inc/rundot-syncplay 5.23.0-beta.7 → 5.23.0

package/dist/physics3d-shared.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Leaf numeric kernel + vector/quaternion/matrix helpers for the deterministic
+ * rigid-body solver. This module imports nothing package-local so `physics3d`,
+ * `physics3d-solver`, and `physics3d-joints` can all depend on it in one
+ * direction with no ESM cycle.
+ *
+ * Determinism regime: plain IEEE doubles restricted to `+ - * /` plus integer
+ * rounding/abs/min/max/trunc (no transcendental library calls — the static
+ * checker bans the square-root/power/trig family). Square roots go through
+ * `deterministicSqrt` (quantized, for persisted distances) or `solverSqrt`
+ * (unquantized Newton, for solver-internal math — state is quantized only at the
+ * frame edge, never mid-solve).
+ */
+export interface Point3D {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+}
+export interface Quat3D {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+    readonly w: number;
+}
+/** Row-major 3x3 matrix, length 9. */
+export type Mat3 = readonly number[];
+export declare function quantizeDistance(distance: number): number;
+export declare function quantizeAngle(value: number): number;
+export declare function deterministicSqrt(value: number): number;
+/**
+ * Unquantized Newton square root for solver-internal math. Bit-for-bit identical
+ * to the seed/iteration schedule the validated spike used; every operation is
+ * exactly specified IEEE-754 arithmetic, so all certified V8 peers agree. State
+ * that reaches the canonical world is quantized separately at the frame edge.
+ */
+export declare function solverSqrt(value: number): number;
+export declare function vec3(x: number, y: number, z: number): Point3D;
+export declare function addVec3(a: Point3D, b: Point3D): Point3D;
+export declare function subVec3(a: Point3D, b: Point3D): Point3D;
+export declare function scaleVec3(a: Point3D, s: number): Point3D;
+export declare function dotVec3(a: Point3D, b: Point3D): number;
+export declare function crossVec3(a: Point3D, b: Point3D): Point3D;
+export declare function lengthVec3(a: Point3D): number;
+export declare function normalizeVec3(a: Point3D): Point3D;
+export declare function quatToMat3(q: Quat3D): Mat3;
+export declare function mulMat3Vec(m: Mat3, a: Point3D): Point3D;
+export declare function mulMat3TransposeVec(m: Mat3, a: Point3D): Point3D;
+/** World-space inverse inertia = R · diag(invI) · Rᵀ. */
+export declare function worldInvInertia(rot: Mat3, invI: Point3D): Mat3;
+/**
+ * Trig-free quaternion integration: q += ½·(ω⊗q)·dt, renormalized with
+ * `solverSqrt`. Returns a unit quaternion; degenerate inputs collapse to
+ * identity so no NaN reaches state.
+ */
+export declare function integrateQuat(q: Quat3D, w: Point3D, dt: number): Quat3D;
+export declare function normalizeQuat(q: Quat3D): Quat3D;
+export declare function quatConjugate(q: Quat3D): Quat3D;
+export declare function quatMultiply(a: Quat3D, b: Quat3D): Quat3D;
+/** Compose integer quarter-turn rotations about x, then y, then z into a quaternion. */
+export declare function quaternionFromQuarterTurns(turns: Point3D): Quat3D;
+/** Rotate a vector by a quaternion using only mul/add/cross (no transcendentals). */
+export declare function rotatePointByQuat(q: Quat3D, p: Point3D): Point3D;
+/** Rotate a vector by the inverse (conjugate) of a quaternion. */
+export declare function rotatePointByQuatInverse(q: Quat3D, p: Point3D): Point3D;
+export declare function clampNumber(value: number, lo: number, hi: number): number;
+/** Skew-symmetric (cross-product) matrix of a vector. */
+export declare function skewMat3(v: Point3D): Mat3;
+export declare function mat3Multiply(a: Mat3, b: Mat3): Mat3;
+export declare function mat3Sub(a: Mat3, b: Mat3): Mat3;
+export declare function mat3FromDiag(d: Point3D): Mat3;
+/** Invert a 3x3 matrix; returns a zero matrix if singular (deterministic fallback). */
+export declare function invertMat3(m: Mat3): Mat3;

package/dist/physics3d-shared.js

@@ -0,0 +1,257 @@
+/**
+ * Leaf numeric kernel + vector/quaternion/matrix helpers for the deterministic
+ * rigid-body solver. This module imports nothing package-local so `physics3d`,
+ * `physics3d-solver`, and `physics3d-joints` can all depend on it in one
+ * direction with no ESM cycle.
+ *
+ * Determinism regime: plain IEEE doubles restricted to `+ - * /` plus integer
+ * rounding/abs/min/max/trunc (no transcendental library calls — the static
+ * checker bans the square-root/power/trig family). Square roots go through
+ * `deterministicSqrt` (quantized, for persisted distances) or `solverSqrt`
+ * (unquantized Newton, for solver-internal math — state is quantized only at the
+ * frame edge, never mid-solve).
+ */
+export function quantizeDistance(distance) {
+    // Pure integer rounding, not fixed-point string rounding — see physics2d
+    // quantizeDistance (cross-engine half-way divergence on checksummed state).
+    const quantized = Math.round(distance * 1e6) / 1e6;
+    return quantized === 0 ? 0 : quantized;
+}
+export function quantizeAngle(value) {
+    const wrapped = value - Math.floor(value);
+    const quantizedAngle = Math.round(wrapped * 1e6) / 1e6;
+    return quantizedAngle === 0 ? 0 : quantizedAngle;
+}
+export function deterministicSqrt(value) {
+    if (value <= 0) {
+        return 0;
+    }
+    let estimate = 1;
+    let magnitude = value;
+    while (magnitude >= 4) {
+        magnitude /= 4;
+        estimate *= 2;
+    }
+    if (magnitude > 1) {
+        estimate *= 2;
+    }
+    for (let iteration = 0; iteration < 8; iteration += 1) {
+        estimate = (estimate + value / estimate) / 2;
+    }
+    return quantizeDistance(estimate);
+}
+/**
+ * Unquantized Newton square root for solver-internal math. Bit-for-bit identical
+ * to the seed/iteration schedule the validated spike used; every operation is
+ * exactly specified IEEE-754 arithmetic, so all certified V8 peers agree. State
+ * that reaches the canonical world is quantized separately at the frame edge.
+ */
+export function solverSqrt(value) {
+    if (value <= 0) {
+        return 0;
+    }
+    let estimate = 1;
+    let magnitude = value;
+    while (magnitude >= 4) {
+        magnitude /= 4;
+        estimate *= 2;
+    }
+    if (magnitude > 1) {
+        estimate *= 2;
+    }
+    for (let iteration = 0; iteration < 8; iteration += 1) {
+        estimate = (estimate + value / estimate) / 2;
+    }
+    return estimate;
+}
+export function vec3(x, y, z) {
+    return { x, y, z };
+}
+export function addVec3(a, b) {
+    return { x: a.x + b.x, y: a.y + b.y, z: a.z + b.z };
+}
+export function subVec3(a, b) {
+    return { x: a.x - b.x, y: a.y - b.y, z: a.z - b.z };
+}
+export function scaleVec3(a, s) {
+    return { x: a.x * s, y: a.y * s, z: a.z * s };
+}
+export function dotVec3(a, b) {
+    return a.x * b.x + a.y * b.y + a.z * b.z;
+}
+export function crossVec3(a, b) {
+    return {
+        x: a.y * b.z - a.z * b.y,
+        y: a.z * b.x - a.x * b.z,
+        z: a.x * b.y - a.y * b.x,
+    };
+}
+export function lengthVec3(a) {
+    return solverSqrt(dotVec3(a, a));
+}
+export function normalizeVec3(a) {
+    const length = lengthVec3(a);
+    return length === 0 ? { x: 0, y: 0, z: 0 } : scaleVec3(a, 1 / length);
+}
+export function quatToMat3(q) {
+    const { x, y, z, w } = q;
+    return [
+        1 - 2 * (y * y + z * z), 2 * (x * y - w * z), 2 * (x * z + w * y),
+        2 * (x * y + w * z), 1 - 2 * (x * x + z * z), 2 * (y * z - w * x),
+        2 * (x * z - w * y), 2 * (y * z + w * x), 1 - 2 * (x * x + y * y),
+    ];
+}
+export function mulMat3Vec(m, a) {
+    return {
+        x: m[0] * a.x + m[1] * a.y + m[2] * a.z,
+        y: m[3] * a.x + m[4] * a.y + m[5] * a.z,
+        z: m[6] * a.x + m[7] * a.y + m[8] * a.z,
+    };
+}
+export function mulMat3TransposeVec(m, a) {
+    return {
+        x: m[0] * a.x + m[3] * a.y + m[6] * a.z,
+        y: m[1] * a.x + m[4] * a.y + m[7] * a.z,
+        z: m[2] * a.x + m[5] * a.y + m[8] * a.z,
+    };
+}
+/** World-space inverse inertia = R · diag(invI) · Rᵀ. */
+export function worldInvInertia(rot, invI) {
+    const invIArr = [invI.x, invI.y, invI.z];
+    const out = new Array(9).fill(0);
+    for (let row = 0; row < 3; row += 1) {
+        for (let col = 0; col < 3; col += 1) {
+            out[row * 3 + col] =
+                rot[row * 3 + 0] * invIArr[0] * rot[col * 3 + 0] +
+                    rot[row * 3 + 1] * invIArr[1] * rot[col * 3 + 1] +
+                    rot[row * 3 + 2] * invIArr[2] * rot[col * 3 + 2];
+        }
+    }
+    return out;
+}
+/**
+ * Trig-free quaternion integration: q += ½·(ω⊗q)·dt, renormalized with
+ * `solverSqrt`. Returns a unit quaternion; degenerate inputs collapse to
+ * identity so no NaN reaches state.
+ */
+export function integrateQuat(q, w, dt) {
+    const hx = w.x * 0.5 * dt;
+    const hy = w.y * 0.5 * dt;
+    const hz = w.z * 0.5 * dt;
+    const nx = q.x + (hx * q.w + hy * q.z - hz * q.y);
+    const ny = q.y + (hy * q.w + hz * q.x - hx * q.z);
+    const nz = q.z + (hz * q.w + hx * q.y - hy * q.x);
+    const nw = q.w + (-hx * q.x - hy * q.y - hz * q.z);
+    const length = solverSqrt(nx * nx + ny * ny + nz * nz + nw * nw);
+    if (length === 0) {
+        return { x: 0, y: 0, z: 0, w: 1 };
+    }
+    return { x: nx / length, y: ny / length, z: nz / length, w: nw / length };
+}
+export function normalizeQuat(q) {
+    const length = solverSqrt(q.x * q.x + q.y * q.y + q.z * q.z + q.w * q.w);
+    if (length === 0) {
+        return { x: 0, y: 0, z: 0, w: 1 };
+    }
+    return { x: q.x / length, y: q.y / length, z: q.z / length, w: q.w / length };
+}
+export function quatConjugate(q) {
+    return { x: -q.x, y: -q.y, z: -q.z, w: q.w };
+}
+export function quatMultiply(a, b) {
+    return {
+        w: a.w * b.w - a.x * b.x - a.y * b.y - a.z * b.z,
+        x: a.w * b.x + a.x * b.w + a.y * b.z - a.z * b.y,
+        y: a.w * b.y - a.x * b.z + a.y * b.w + a.z * b.x,
+        z: a.w * b.z + a.x * b.y - a.y * b.x + a.z * b.w,
+    };
+}
+const QUARTER_ROOT_HALF = solverSqrt(0.5);
+function axisQuarterTurnQuat(axis, turns) {
+    const c = ((Math.trunc(turns) % 4) + 4) % 4;
+    // half-angle is turns·45°; sin/cos of {0,45,90,135}° are exactly {0/1, ±√½}.
+    const table = [
+        { s: 0, w: 1 },
+        { s: QUARTER_ROOT_HALF, w: QUARTER_ROOT_HALF },
+        { s: 1, w: 0 },
+        { s: QUARTER_ROOT_HALF, w: -QUARTER_ROOT_HALF },
+    ];
+    const entry = table[c];
+    return {
+        x: axis === 0 ? entry.s : 0,
+        y: axis === 1 ? entry.s : 0,
+        z: axis === 2 ? entry.s : 0,
+        w: entry.w,
+    };
+}
+/** Compose integer quarter-turn rotations about x, then y, then z into a quaternion. */
+export function quaternionFromQuarterTurns(turns) {
+    const qx = axisQuarterTurnQuat(0, turns.x);
+    const qy = axisQuarterTurnQuat(1, turns.y);
+    const qz = axisQuarterTurnQuat(2, turns.z);
+    return quatMultiply(quatMultiply(qx, qy), qz);
+}
+/** Rotate a vector by a quaternion using only mul/add/cross (no transcendentals). */
+export function rotatePointByQuat(q, p) {
+    const u = { x: q.x, y: q.y, z: q.z };
+    const t = scaleVec3(crossVec3(u, p), 2);
+    return addVec3(addVec3(p, scaleVec3(t, q.w)), crossVec3(u, t));
+}
+/** Rotate a vector by the inverse (conjugate) of a quaternion. */
+export function rotatePointByQuatInverse(q, p) {
+    return rotatePointByQuat(quatConjugate(q), p);
+}
+export function clampNumber(value, lo, hi) {
+    return value < lo ? lo : value > hi ? hi : value;
+}
+/** Skew-symmetric (cross-product) matrix of a vector. */
+export function skewMat3(v) {
+    return [
+        0, -v.z, v.y,
+        v.z, 0, -v.x,
+        -v.y, v.x, 0,
+    ];
+}
+export function mat3Multiply(a, b) {
+    const out = new Array(9).fill(0);
+    for (let row = 0; row < 3; row += 1) {
+        for (let col = 0; col < 3; col += 1) {
+            out[row * 3 + col] =
+                a[row * 3 + 0] * b[0 * 3 + col] +
+                    a[row * 3 + 1] * b[1 * 3 + col] +
+                    a[row * 3 + 2] * b[2 * 3 + col];
+        }
+    }
+    return out;
+}
+export function mat3Sub(a, b) {
+    return a.map((value, index) => value - b[index]);
+}
+export function mat3FromDiag(d) {
+    return [d.x, 0, 0, 0, d.y, 0, 0, 0, d.z];
+}
+/** Invert a 3x3 matrix; returns a zero matrix if singular (deterministic fallback). */
+export function invertMat3(m) {
+    const a = m[0];
+    const b = m[1];
+    const c = m[2];
+    const d = m[3];
+    const e = m[4];
+    const f = m[5];
+    const g = m[6];
+    const h = m[7];
+    const i = m[8];
+    const co0 = e * i - f * h;
+    const co1 = f * g - d * i;
+    const co2 = d * h - e * g;
+    const det = a * co0 + b * co1 + c * co2;
+    if (det === 0) {
+        return [0, 0, 0, 0, 0, 0, 0, 0, 0];
+    }
+    const inv = 1 / det;
+    return [
+        co0 * inv, (c * h - b * i) * inv, (b * f - c * e) * inv,
+        co1 * inv, (a * i - c * g) * inv, (c * d - a * f) * inv,
+        co2 * inv, (b * g - a * h) * inv, (a * e - b * d) * inv,
+    ];
+}

package/dist/physics3d-solver.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Deterministic rigid-body solver core (geometry half): SAT + face-clipping
+ * manifolds for boxes, closed-form manifolds for sphere/capsule pairs,
+ * one-sided triangle contacts for dynamic-shape-vs-static-mesh, and compound
+ * decomposition. The velocity/position solver, contact cache matching, islands
+ * and sleeping live alongside in this module (see solveRigidStep).
+ *
+ * Numeric regime: unquantized solver math via the shared kernel; every constant
+ * here is load-bearing (each was earned by a failure mode in the validated
+ * spike) — do not "simplify" them without re-running the stack/tumble/
+ * determinism scenarios.
+ */
+import { Mat3, Point3D, Quat3D } from './physics3d-shared.js';
+export type SolverPrimitiveShape = {
+    readonly kind: 'box';
+    readonly half: Point3D;
+} | {
+    readonly kind: 'sphere';
+    readonly radius: number;
+} | {
+    readonly kind: 'capsule';
+    readonly radius: number;
+    readonly halfHeight: number;
+};
+export interface SolverCompoundChild {
+    readonly shape: SolverPrimitiveShape;
+    readonly offset: Point3D;
+    readonly q: Quat3D;
+}
+export type SolverShape = SolverPrimitiveShape | {
+    readonly kind: 'compound';
+    readonly children: readonly SolverCompoundChild[];
+} | {
+    readonly kind: 'mesh';
+    readonly triangles: readonly (readonly [Point3D, Point3D, Point3D])[];
+};
+export interface SolverGeomBody {
+    readonly index: number;
+    readonly p: Point3D;
+    readonly q: Quat3D;
+    readonly shape: SolverShape;
+}
+export interface SolverContactPoint {
+    /** Anchor relative to body A center, world axes. */
+    readonly rA: Point3D;
+    readonly rB: Point3D;
+    /** >= 0 real contact; < 0 speculative (CCD). */
+    readonly penetration: number;
+    /** Stable feature id used for deterministic point ordering. */
+    readonly feature: number;
+}
+export interface SolverManifold {
+    readonly a: number;
+    readonly b: number;
+    /** Unit, points A -> B. */
+    readonly normal: Point3D;
+    readonly points: readonly SolverContactPoint[];
+}
+export declare function generateManifold(a: SolverGeomBody, b: SolverGeomBody, speculativeMargin?: number): SolverManifold | undefined;
+declare function closestPointOnSegment(point: Point3D, start: Point3D, end: Point3D): Point3D;
+declare function closestSegmentSegment(p1: Point3D, q1: Point3D, p2: Point3D, q2: Point3D): {
+    c1: Point3D;
+    c2: Point3D;
+};
+declare function triangleNormal(a: Point3D, b: Point3D, c: Point3D): Point3D;
+declare function closestPointOnTriangle(p: Point3D, a: Point3D, b: Point3D, c: Point3D): Point3D;
+export declare const SOLVER_CONSTANTS: {
+    readonly BAUMGARTE: 0.2;
+    readonly SLOP: 0.005;
+    readonly WAKE_VEL2: 0.005;
+    readonly SLEEP_VEL2: 0.005;
+    readonly SLEEP_FRAMES: 20;
+    readonly RESTITUTION_THRESHOLD: 1;
+    readonly WARM_MATCH_TOL2: 0.01;
+    readonly LINEAR_DAMPING: 0.995;
+    readonly ANGULAR_DAMPING: 0.98;
+};
+/** Solver-owned velocity vector — mutated in place on the hot impulse path. */
+export interface SolverVec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+export interface SolverBody {
+    readonly index: number;
+    readonly id: string;
+    readonly isDynamic: boolean;
+    sleeping: boolean;
+    p: Point3D;
+    q: Quat3D;
+    v: SolverVec3;
+    w: SolverVec3;
+    vb: SolverVec3;
+    wb: SolverVec3;
+    /** Per-axis inverse mass (axis locks zero individual components). */
+    readonly invMassVec: Point3D;
+    /** Body-space diagonal inverse inertia. */
+    readonly invInertiaLocal: Point3D;
+    /** Per-world-axis angular lock multiplier (0 locked, 1 free). */
+    readonly angularLock: Point3D;
+    /** 0..1 material coefficients (already divided from 0-10 ints). */
+    readonly matFriction: number;
+    readonly matRestitution: number;
+    readonly linearDamping: number;
+    readonly angularDamping: number;
+    /** Multiplies world gravity for this body in solver step 1; default 1. */
+    readonly gravityScale: number;
+    readonly hasOrientation: boolean;
+    readonly shape: SolverShape;
+    lowVelFrames: number;
+    wakeForced: boolean;
+    readonly ccd: boolean;
+    readonly layer: number;
+    readonly mask: number;
+    /** Trigger/sensor bodies integrate but never generate solved contacts. */
+    readonly noCollide: boolean;
+}
+export interface SolverJointCacheEntry {
+    readonly jointId: string;
+    readonly impulseX: number;
+    readonly impulseY: number;
+    readonly impulseZ: number;
+    readonly axialImpulse: number;
+    readonly hingeAngle: number;
+    /** Set once a breakable joint exceeded its breakImpulse; sticky via the cache. */
+    readonly broken?: boolean;
+}
+export interface SolverJointContext {
+    readonly bodies: readonly SolverBody[];
+    readonly invMass: readonly Point3D[];
+    readonly invInertia: readonly Mat3[];
+    readonly dt: number;
+    apply(a: number, b: number, rA: Point3D, rB: Point3D, impulse: Point3D): void;
+    /** Angular-only impulse (no linear component), e.g. hinge motor/limit rows. */
+    applyAngular(a: number, b: number, angularImpulse: Point3D): void;
+    /** Apply an impulse to a single body at anchor `r` (grab / world-target joints). */
+    applyToBody(index: number, r: Point3D, impulse: Point3D): void;
+    /** Split-impulse position correction on pseudo-velocities (no real momentum). */
+    applyBias(a: number, b: number, rA: Point3D, rB: Point3D, impulse: Point3D): void;
+    /** Relative pseudo-velocity at the anchor pair, for split-impulse joint solves. */
+    biasRelativeVelocity(a: number, b: number, rA: Point3D, rB: Point3D): Point3D;
+}
+export interface SolverJointSolve {
+    /** Compute effective masses + apply warm-start impulses (called once per step). */
+    prepare(ctx: SolverJointContext): void;
+    /** One velocity iteration. */
+    iterate(ctx: SolverJointContext): void;
+    /** Bodies coupled by this joint (for islands + wake propagation). */
+    readonly bodyIndices: readonly number[];
+    /** Emit the joint cache entry after solving. */
+    emitCache(): SolverJointCacheEntry;
+}
+export interface SolverWarmPoint {
+    readonly anchor: Point3D;
+    readonly normalImpulse: number;
+    readonly tangentImpulse1: number;
+    readonly tangentImpulse2: number;
+}
+export interface SolverStepOptions {
+    readonly dt: number;
+    readonly gravityY: number;
+    readonly velocityIterations: number;
+    /** Packed index-pair key `a * 2**20 + b` (a<b) → warm points from last frame. */
+    readonly warm: Map<number, SolverWarmPoint[]>;
+    /** Candidate index pairs (i<j, canonical order) to narrow-phase, or undefined = O(n²). */
+    readonly pairs?: readonly (readonly [number, number])[];
+    readonly joints?: readonly SolverJointSolve[];
+    /** Packed index pairs (min * WARM_KEY_BASE + max) whose contacts are suppressed (jointed pairs). */
+    readonly noCollidePairs?: ReadonlySet<number>;
+}
+export interface SolverContactImpulse {
+    readonly a: number;
+    readonly b: number;
+    readonly normalImpulse: number;
+    readonly pair: string;
+}
+export interface SolverStepResult {
+    readonly manifolds: readonly SolverManifold[];
+    readonly contactImpulses: readonly SolverContactImpulse[];
+    /** New warm cache, packed index-pair keyed (`a * 2**20 + b`). */
+    readonly warm: Map<number, SolverWarmPoint[]>;
+    readonly jointCache: readonly SolverJointCacheEntry[];
+}
+/**
+ * Warm-cache maps pack the canonical index pair (a<b) into one exact integer
+ * `a * WARM_KEY_BASE + b` — string pair keys were measurable churn on large piles.
+ */
+export declare const WARM_KEY_BASE: number;
+/** Runs one deterministic rigid-body step in place over `bodies`. */
+export declare function solveRigidStep(bodies: SolverBody[], options: SolverStepOptions): SolverStepResult;
+export declare const __solverInternals: {
+    closestPointOnSegment: typeof closestPointOnSegment;
+    closestSegmentSegment: typeof closestSegmentSegment;
+    closestPointOnTriangle: typeof closestPointOnTriangle;
+    triangleNormal: typeof triangleNormal;
+};
+export {};