reze-engine 0.27.4 → 0.29.0

package/dist/locomotion.js

@@ -0,0 +1,179 @@
+// Game-style locomotion over the blend primitive: idle ↔ run ↔ sprint mixed by a
+// smoothed speed level, yaw eased toward the input heading, root motion integrated
+// in code (the clips are in-place). Zero renderer coupling — the controller only
+// talks to Model.setBlendPose and returns the root transform for the host to apply
+// via engine.setModelTransform.
+import { FPS } from "./animation";
+import { Quat, Vec3 } from "./math";
+const TWO_PI = Math.PI * 2;
+function wrapAngle(a) {
+    while (a > Math.PI)
+        a -= TWO_PI;
+    while (a < -Math.PI)
+        a += TWO_PI;
+    return a;
+}
+export class LocomotionController {
+    constructor(model, clips, options) {
+        this.inputX = 0;
+        this.inputY = 0;
+        this.inputSprint = false;
+        // Tank mode: forward/steer relative to the CURRENT facing, camera never involved.
+        this.tankMode = false;
+        this.inputForward = 0;
+        this.inputSteer = 0;
+        this.speedLevel = 0;
+        this.yaw = 0;
+        // Movement direction = the INPUT heading, not the body yaw. The body turns
+        // cosmetically toward it; translating along the (sweeping) body yaw instead
+        // would nudge the character through the forward arc on every L↔R reversal.
+        this.dirX = 0;
+        this.dirZ = 1;
+        this.position = new Vec3(0, 0, 0);
+        this.rotation = new Quat(0, 0, 0, 1);
+        this.idleTime = 0;
+        this.gaitPhase = 0; // 0..1, shared by run and sprint so legs stay aligned across the blend
+        this.model = model;
+        this.clips = clips;
+        this.runSpeed = options?.runSpeed ?? 67;
+        this.sprintSpeed = options?.sprintSpeed ?? 92;
+        this.speedResponse = options?.speedResponse ?? 5;
+        this.turnResponse = options?.turnResponse ?? 10;
+        this.cosTurnThreshold = Math.cos(options?.turnInPlaceThreshold ?? Math.PI / 4);
+        this.steerRate = options?.steerRate ?? 2.5;
+        this.backpedalScale = options?.backpedalScale ?? 0.5;
+        this.yawOffset = options?.yawOffset ?? Math.PI;
+        this.entries = [
+            { name: clips.idle, time: 0, weight: 1 },
+            { name: clips.run, time: 0, weight: 0 },
+            { name: clips.sprint ?? clips.run, time: 0, weight: 0 },
+        ];
+        this.pose = { position: this.position, yaw: 0, rotation: this.rotation, speedLevel: 0 };
+    }
+    /** World-vector move input: x = +right (+X), y = +forward (+Z), magnitude clamped
+     *  to 1. The character turns toward the vector, then runs along it. Call whenever
+     *  input changes — the value holds between calls. */
+    setMove(x, y, sprint = false) {
+        const m = Math.hypot(x, y);
+        if (m > 1) {
+            x /= m;
+            y /= m;
+        }
+        this.tankMode = false;
+        this.inputX = x;
+        this.inputY = y;
+        this.inputSprint = sprint;
+    }
+    /** Tank-style input relative to the CURRENT facing, camera-independent and fully
+     *  deterministic: `steer` (−1..1, + = her right) rotates at steerRate whether
+     *  standing or moving, `forward` (+1 run ahead — curving while steering — or −1
+     *  backpedal at backpedalScale). Holds between calls, like setMove. */
+    setDrive(forward, steer, sprint = false) {
+        this.tankMode = true;
+        this.inputForward = Math.max(-1, Math.min(1, forward));
+        this.inputSteer = Math.max(-1, Math.min(1, steer));
+        this.inputSprint = sprint;
+    }
+    /** Place the character (initial spawn or respawn). */
+    teleport(x, y, z, yaw = 0) {
+        this.position.setXYZ(x, y, z);
+        this.yaw = yaw;
+    }
+    getPosition() {
+        return this.position;
+    }
+    /** Stop driving the model's pose (the blend is cleared; the single-clip player resumes). */
+    detach() {
+        this.model.clearBlendPose();
+    }
+    clipDuration(name) {
+        const frames = this.model.getClip(name)?.frameCount ?? 0;
+        return frames > 0 ? frames / FPS : 1;
+    }
+    /** Advance one frame: integrates yaw + position, updates the clip clocks, hands the
+     *  weighted pose to the model, and returns the root transform to apply. */
+    update(dt) {
+        if (dt > 0.1)
+            dt = 0.1; // tab-switch guard: never integrate a huge step
+        const hasSprint = this.clips.sprint !== undefined;
+        let moving;
+        let align = 1;
+        let speedScale = 1;
+        if (this.tankMode) {
+            // Steering rotates the facing directly — standing or moving — and the travel
+            // direction IS the facing, so no pivot gate and no drift by construction.
+            this.yaw = wrapAngle(this.yaw + this.inputSteer * this.steerRate * dt);
+            const fwd = this.inputForward;
+            moving = Math.abs(fwd) > 0.05;
+            if (moving) {
+                const back = fwd < 0;
+                this.dirX = Math.sin(this.yaw) * Math.sign(fwd);
+                this.dirZ = Math.cos(this.yaw) * Math.sign(fwd);
+                speedScale = Math.abs(fwd) * (back ? this.backpedalScale : 1);
+            }
+        }
+        else {
+            const m = Math.hypot(this.inputX, this.inputY);
+            moving = m > 0.05;
+            // Yaw eases toward the input heading only while there is one. Turns are strictly
+            // in place: zero translation outside the threshold cone, ramping smoothly to full
+            // speed as the body aligns — so direction reversals (L-R-L) cannot drift.
+            if (moving) {
+                const desired = Math.atan2(this.inputX, this.inputY);
+                const err = wrapAngle(desired - this.yaw);
+                this.yaw = wrapAngle(this.yaw + err * Math.min(1, this.turnResponse * dt));
+                align = Math.max(0, (Math.cos(err) - this.cosTurnThreshold) / (1 - this.cosTurnThreshold));
+                this.dirX = this.inputX / m;
+                this.dirZ = this.inputY / m;
+            }
+        }
+        // Speed level ramps linearly toward the target; the pose blend follows it.
+        // (No sprint while backpedaling.)
+        const sprinting = this.inputSprint && hasSprint && !(this.tankMode && this.inputForward < 0);
+        const target = moving ? (sprinting ? 2 : 1) : 0;
+        const maxStep = this.speedResponse * dt;
+        const d = target - this.speedLevel;
+        this.speedLevel += Math.abs(d) <= maxStep ? d : Math.sign(d) * maxStep;
+        // Root motion along the travel direction. In-place clips carry no horizontal root.
+        const speed = (this.speedLevel <= 1
+            ? this.runSpeed * this.speedLevel
+            : this.runSpeed + (this.sprintSpeed - this.runSpeed) * (this.speedLevel - 1)) *
+            align *
+            speedScale;
+        this.position.x += this.dirX * speed * dt;
+        this.position.z += this.dirZ * speed * dt;
+        // Clocks: idle free-runs; run/sprint share one normalized gait phase so a
+        // mid-blend stride stays on the same feet.
+        const idleDur = this.clipDuration(this.clips.idle);
+        const runDur = this.clipDuration(this.clips.run);
+        const sprintDur = hasSprint ? this.clipDuration(this.clips.sprint) : runDur;
+        this.idleTime = (this.idleTime + dt) % idleDur;
+        const gaitDur = this.speedLevel <= 1 ? runDur : runDur + (sprintDur - runDur) * (this.speedLevel - 1);
+        this.gaitPhase = (this.gaitPhase + dt / gaitDur) % 1;
+        // Weights along the 1D speed axis.
+        let wIdle, wRun, wSprint;
+        if (this.speedLevel <= 1) {
+            wIdle = 1 - this.speedLevel;
+            wRun = this.speedLevel;
+            wSprint = 0;
+        }
+        else {
+            wIdle = 0;
+            wRun = 2 - this.speedLevel;
+            wSprint = this.speedLevel - 1;
+        }
+        this.entries[0].time = this.idleTime;
+        this.entries[0].weight = wIdle;
+        this.entries[1].time = this.gaitPhase * runDur;
+        this.entries[1].weight = wRun;
+        this.entries[2].time = this.gaitPhase * sprintDur;
+        this.entries[2].weight = wSprint;
+        this.model.setBlendPose(this.entries);
+        const ry = this.yaw + this.yawOffset;
+        const half = ry * 0.5;
+        this.rotation.setXYZW(0, Math.sin(half), 0, Math.cos(half));
+        this.pose.yaw = this.yaw;
+        this.pose.speedLevel = this.speedLevel;
+        return this.pose;
+    }
+}

package/dist/math.d.ts

@@ -1,4 +1,5 @@
 export declare function easeInOut(t: number): number;
+export type EulerOrder = "XYZ" | "XZY" | "YXZ" | "YZX" | "ZXY" | "ZYX";
 export declare class Vec3 {
     x: number;
     y: number;
@@ -18,6 +19,8 @@ export declare class Vec3 {
     static crossInto(a: Vec3, b: Vec3, out: Vec3): Vec3;
     static setFromMat4Translation(m: Float32Array, out: Vec3): Vec3;
     static transformMat4RotationInto(normal: Vec3, m: Float32Array, out: Vec3): Vec3;
+    static mirrorZInto(v: Vec3, out: Vec3): Vec3;
+    static mirrorZ(v: Vec3): Vec3;
     normalizeInPlace(): Vec3;
 }
 export declare class Quat {
@@ -43,6 +46,29 @@ export declare class Quat {
     setXYZW(x: number, y: number, z: number, w: number): Quat;
     setIdentity(): Quat;
     static fromEuler(rotX: number, rotY: number, rotZ: number): Quat;
+    static dot(a: Quat, b: Quat): number;
+    static angleTo(a: Quat, b: Quat): number;
+    static conjugateInto(q: Quat, out: Quat): Quat;
+    static nlerpInto(a: Quat, b: Quat, t: number, out: Quat): Quat;
+    static nlerp(a: Quat, b: Quat, t: number): Quat;
+    static rotateVecInto(q: Quat, v: Vec3, out: Vec3): Vec3;
+    static rotateVec(q: Quat, v: Vec3): Vec3;
+    static rotateVecInvInto(q: Quat, v: Vec3, out: Vec3): Vec3;
+    static rotateVecInv(q: Quat, v: Vec3): Vec3;
+    static fromUnitVectorsInto(from: Vec3, to: Vec3, out: Quat): Quat;
+    static fromUnitVectors(from: Vec3, to: Vec3): Quat;
+    static fromBasisInto(x: Vec3, y: Vec3, z: Vec3, out: Quat): Quat;
+    static fromBasis(x: Vec3, y: Vec3, z: Vec3): Quat;
+    static twistAroundAxisInto(q: Quat, a: Vec3, out: Quat): Quat;
+    static twistAroundAxis(q: Quat, a: Vec3): Quat;
+    static lookRotationInto(forward: Vec3, up: Vec3, out: Quat): Quat;
+    static lookRotation(forward: Vec3, up: Vec3): Quat;
+    static mirrorZInto(q: Quat, out: Quat): Quat;
+    static mirrorZ(q: Quat): Quat;
+    static fromEulerOrderInto(x: number, y: number, z: number, order: EulerOrder, out: Quat): Quat;
+    static fromEulerOrder(x: number, y: number, z: number, order: EulerOrder): Quat;
+    static toEulerOrderInto(q: Quat, order: EulerOrder, out: Vec3): Vec3;
+    static toEulerOrder(q: Quat, order: EulerOrder): Vec3;
 }
 export declare class Mat4 {
     values: Float32Array;

package/dist/math.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"math.d.ts","sourceRoot":"","sources":["../src/math.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"math.d.ts","sourceRoot":"","sources":["../src/math.ts"],"names":[],"mappings":"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"}

package/dist/math.js

@@ -90,6 +90,16 @@ export class Vec3 {
         out.z = m[2] * nx + m[6] * ny + m[10] * nz;
         return out;
     }
+    // out = (x, y, -z): right-handed Y-up ↔ left-handed Y-up (involutive). Safe when out === v.
+    static mirrorZInto(v, out) {
+        out.x = v.x;
+        out.y = v.y;
+        out.z = -v.z;
+        return out;
+    }
+    static mirrorZ(v) {
+        return new Vec3(v.x, v.y, -v.z);
+    }
     // In-place normalize returning length squared info via Vec3. Alias for normalize() but explicit.
     normalizeInPlace() {
         return this.normalize();
@@ -286,6 +296,318 @@ export class Quat {
         const z = cy * cx * sz - sy * sx * cz;
         return new Quat(x, y, z, w).normalize();
     }
+    // 4D dot product. Negative means a and b are on opposite hemispheres (same rotation
+    // when |dot| ≈ 1 either way — quaternion double cover).
+    static dot(a, b) {
+        return a.x * b.x + a.y * b.y + a.z * b.z + a.w * b.w;
+    }
+    // Rotation angle between a and b in radians, insensitive to double cover.
+    static angleTo(a, b) {
+        const d = Math.abs(a.x * b.x + a.y * b.y + a.z * b.z + a.w * b.w);
+        return 2 * Math.acos(Math.min(1, d));
+    }
+    // out = conjugate of q (inverse for unit quaternions), without mutating q. Safe when out === q.
+    static conjugateInto(q, out) {
+        out.x = -q.x;
+        out.y = -q.y;
+        out.z = -q.z;
+        out.w = q.w;
+        return out;
+    }
+    // out = normalized lerp from a to b, taking the shorter path (negates b when dot < 0).
+    // Cheaper than slerp; non-constant angular velocity. Safe when out === a or out === b.
+    static nlerpInto(a, b, t, out) {
+        const d = a.x * b.x + a.y * b.y + a.z * b.z + a.w * b.w;
+        const s = d < 0 ? -1 : 1;
+        const x = a.x + (b.x * s - a.x) * t;
+        const y = a.y + (b.y * s - a.y) * t;
+        const z = a.z + (b.z * s - a.z) * t;
+        const w = a.w + (b.w * s - a.w) * t;
+        const invLen = 1 / Math.hypot(x, y, z, w);
+        out.x = x * invLen;
+        out.y = y * invLen;
+        out.z = z * invLen;
+        out.w = w * invLen;
+        return out;
+    }
+    static nlerp(a, b, t) {
+        return Quat.nlerpInto(a, b, t, new Quat(0, 0, 0, 1));
+    }
+    // out = v rotated by unit quaternion q (no matrix, no allocation). Safe when out === v.
+    static rotateVecInto(q, v, out) {
+        // v' = v + 2*qw*(qv × v) + 2*(qv × (qv × v))
+        const qx = q.x, qy = q.y, qz = q.z, qw = q.w;
+        const vx = v.x, vy = v.y, vz = v.z;
+        // t = 2 * (qv × v)
+        const tx = 2 * (qy * vz - qz * vy);
+        const ty = 2 * (qz * vx - qx * vz);
+        const tz = 2 * (qx * vy - qy * vx);
+        out.x = vx + qw * tx + qy * tz - qz * ty;
+        out.y = vy + qw * ty + qz * tx - qx * tz;
+        out.z = vz + qw * tz + qx * ty - qy * tx;
+        return out;
+    }
+    static rotateVec(q, v) {
+        return Quat.rotateVecInto(q, v, new Vec3(0, 0, 0));
+    }
+    // out = v rotated by the inverse (conjugate) of unit quaternion q. Safe when out === v.
+    static rotateVecInvInto(q, v, out) {
+        const qx = -q.x, qy = -q.y, qz = -q.z, qw = q.w;
+        const vx = v.x, vy = v.y, vz = v.z;
+        const tx = 2 * (qy * vz - qz * vy);
+        const ty = 2 * (qz * vx - qx * vz);
+        const tz = 2 * (qx * vy - qy * vx);
+        out.x = vx + qw * tx + qy * tz - qz * ty;
+        out.y = vy + qw * ty + qz * tx - qx * tz;
+        out.z = vz + qw * tz + qx * ty - qy * tx;
+        return out;
+    }
+    static rotateVecInv(q, v) {
+        return Quat.rotateVecInvInto(q, v, new Vec3(0, 0, 0));
+    }
+    // out = shortest-arc rotation taking unit vector `from` to unit vector `to`.
+    // Matches Babylon's FromUnitVectorsToRef exactly, including the near-antiparallel
+    // branch (w = 1 + dot < 0.001 → 180° about a perpendicular picked the same way).
+    static fromUnitVectorsInto(from, to, out) {
+        const r = from.x * to.x + from.y * to.y + from.z * to.z + 1;
+        if (r < 0.001) {
+            if (Math.abs(from.x) > Math.abs(from.z)) {
+                out.setXYZW(-from.y, from.x, 0, 0);
+            }
+            else {
+                out.setXYZW(0, -from.z, from.y, 0);
+            }
+        }
+        else {
+            // q = (from × to, 1 + from·to)
+            out.setXYZW(from.y * to.z - from.z * to.y, from.z * to.x - from.x * to.z, from.x * to.y - from.y * to.x, r);
+        }
+        const invLen = 1 / Math.sqrt(out.x * out.x + out.y * out.y + out.z * out.z + out.w * out.w);
+        out.setXYZW(out.x * invLen, out.y * invLen, out.z * invLen, out.w * invLen);
+        return out;
+    }
+    static fromUnitVectors(from, to) {
+        return Quat.fromUnitVectorsInto(from, to, new Quat(0, 0, 0, 1));
+    }
+    // out = rotation taking the standard basis onto the orthonormal axes x, y, z
+    // (the columns of the column-major rotation matrix): rotateVec(out, (1,0,0)) = x, etc.
+    static fromBasisInto(x, y, z, out) {
+        // Shepperd's method on the 3x3 with columns x, y, z.
+        const m00 = x.x, m01 = x.y, m02 = x.z;
+        const m10 = y.x, m11 = y.y, m12 = y.z;
+        const m20 = z.x, m21 = z.y, m22 = z.z;
+        const trace = m00 + m11 + m22;
+        if (trace > 0) {
+            const s = 0.5 / Math.sqrt(trace + 1);
+            out.setXYZW((m12 - m21) * s, (m20 - m02) * s, (m01 - m10) * s, 0.25 / s);
+        }
+        else if (m00 > m11 && m00 > m22) {
+            const s = 2 * Math.sqrt(1 + m00 - m11 - m22);
+            out.setXYZW(0.25 * s, (m10 + m01) / s, (m20 + m02) / s, (m12 - m21) / s);
+        }
+        else if (m11 > m22) {
+            const s = 2 * Math.sqrt(1 + m11 - m00 - m22);
+            out.setXYZW((m10 + m01) / s, 0.25 * s, (m21 + m12) / s, (m20 - m02) / s);
+        }
+        else {
+            const s = 2 * Math.sqrt(1 + m22 - m00 - m11);
+            out.setXYZW((m20 + m02) / s, (m21 + m12) / s, 0.25 * s, (m01 - m10) / s);
+        }
+        return out;
+    }
+    static fromBasis(x, y, z) {
+        return Quat.fromBasisInto(x, y, z, new Quat(0, 0, 0, 1));
+    }
+    // out = twist component of q around unit axis `a`, so that q = swing · twist
+    // (swing = Quat.multiply(q, conjugate(twist))). Singular when q is ~180° about an
+    // axis perpendicular to `a` — returns identity there.
+    static twistAroundAxisInto(q, a, out) {
+        const d = q.x * a.x + q.y * a.y + q.z * a.z;
+        const px = a.x * d;
+        const py = a.y * d;
+        const pz = a.z * d;
+        const len = Math.sqrt(px * px + py * py + pz * pz + q.w * q.w);
+        if (len < 1e-8) {
+            out.setIdentity();
+            return out;
+        }
+        out.setXYZW(px / len, py / len, pz / len, q.w / len);
+        return out;
+    }
+    static twistAroundAxis(q, a) {
+        return Quat.twistAroundAxisInto(q, a, new Quat(0, 0, 0, 1));
+    }
+    // out = orientation looking along `forward` (mapped to local +Z, the engine's LH forward)
+    // with local +Y toward `up`. Falls back to a reference up when forward ∥ up.
+    static lookRotationInto(forward, up, out) {
+        let zx = forward.x, zy = forward.y, zz = forward.z;
+        const zl = Math.sqrt(zx * zx + zy * zy + zz * zz);
+        if (zl === 0)
+            return out.setIdentity();
+        const zi = 1 / zl;
+        zx *= zi;
+        zy *= zi;
+        zz *= zi;
+        // x = up × z
+        let xx = up.y * zz - up.z * zy;
+        let xy = up.z * zx - up.x * zz;
+        let xz = up.x * zy - up.y * zx;
+        let xl = Math.sqrt(xx * xx + xy * xy + xz * xz);
+        if (xl < 1e-8) {
+            // forward ∥ up: substitute a reference up not parallel to forward
+            const uy = Math.abs(zy) < 0.99 ? 1 : 0;
+            const ux = 1 - uy;
+            xx = uy * zz;
+            xy = -ux * zz;
+            xz = ux * zy - uy * zx;
+            xl = Math.sqrt(xx * xx + xy * xy + xz * xz);
+        }
+        const xi = 1 / xl;
+        xx *= xi;
+        xy *= xi;
+        xz *= xi;
+        // y = z × x (unit: z ⊥ x)
+        const yx = zy * xz - zz * xy;
+        const yy = zz * xx - zx * xz;
+        const yz = zx * xy - zy * xx;
+        _lookX.setXYZ(xx, xy, xz);
+        _lookY.setXYZ(yx, yy, yz);
+        _lookZ.setXYZ(zx, zy, zz);
+        return Quat.fromBasisInto(_lookX, _lookY, _lookZ, out);
+    }
+    static lookRotation(forward, up) {
+        return Quat.lookRotationInto(forward, up, new Quat(0, 0, 0, 1));
+    }
+    // out = q with the Z axis mirrored: right-handed Y-up ↔ left-handed Y-up
+    // (conjugation by the Z-mirror; involutive). Pairs with Vec3.mirrorZInto. Safe when out === q.
+    static mirrorZInto(q, out) {
+        out.x = -q.x;
+        out.y = -q.y;
+        out.z = q.z;
+        out.w = q.w;
+        return out;
+    }
+    static mirrorZ(q) {
+        return new Quat(-q.x, -q.y, q.z, q.w);
+    }
+    // out = quaternion from euler angles (radians) applied in the given intrinsic order.
+    // fromEulerOrderInto(x, y, z, "YXZ", out) matches Quat.fromEuler (the MMD/PMX convention).
+    static fromEulerOrderInto(x, y, z, order, out) {
+        out.setIdentity();
+        for (let i = 0; i < 3; i++) {
+            const axis = order.charCodeAt(i) - 88; // "X" → 0, "Y" → 1, "Z" → 2
+            const angle = axis === 0 ? x : axis === 1 ? y : z;
+            const half = angle * 0.5;
+            const s = Math.sin(half);
+            const c = Math.cos(half);
+            const ax = out.x, ay = out.y, az = out.z, aw = out.w;
+            if (axis === 0) {
+                out.x = aw * s + ax * c;
+                out.y = ay * c + az * s;
+                out.z = az * c - ay * s;
+                out.w = aw * c - ax * s;
+            }
+            else if (axis === 1) {
+                out.x = ax * c - az * s;
+                out.y = aw * s + ay * c;
+                out.z = az * c + ax * s;
+                out.w = aw * c - ay * s;
+            }
+            else {
+                out.x = ax * c + ay * s;
+                out.y = ay * c - ax * s;
+                out.z = aw * s + az * c;
+                out.w = aw * c - az * s;
+            }
+        }
+        return out;
+    }
+    static fromEulerOrder(x, y, z, order) {
+        return Quat.fromEulerOrderInto(x, y, z, order, new Quat(0, 0, 0, 1));
+    }
+    // Extract euler angles (radians) in the given intrinsic order into out (out.x/y/z = rotation
+    // about X/Y/Z). At gimbal lock (middle angle ±90°) the split between first and third angle is
+    // ambiguous; the third is set to 0.
+    static toEulerOrderInto(q, order, out) {
+        Mat4.fromQuatInto(q.x, q.y, q.z, q.w, _eulerMat, 0);
+        const m = _eulerMat;
+        const m11 = m[0], m12 = m[4], m13 = m[8];
+        const m21 = m[1], m22 = m[5], m23 = m[9];
+        const m31 = m[2], m32 = m[6], m33 = m[10];
+        const clamp = (v) => (v < -1 ? -1 : v > 1 ? 1 : v);
+        switch (order) {
+            case "XYZ":
+                out.y = Math.asin(clamp(m13));
+                if (Math.abs(m13) < 0.9999999) {
+                    out.x = Math.atan2(-m23, m33);
+                    out.z = Math.atan2(-m12, m11);
+                }
+                else {
+                    out.x = Math.atan2(m32, m22);
+                    out.z = 0;
+                }
+                break;
+            case "YXZ":
+                out.x = Math.asin(-clamp(m23));
+                if (Math.abs(m23) < 0.9999999) {
+                    out.y = Math.atan2(m13, m33);
+                    out.z = Math.atan2(m21, m22);
+                }
+                else {
+                    out.y = Math.atan2(-m31, m11);
+                    out.z = 0;
+                }
+                break;
+            case "ZXY":
+                out.x = Math.asin(clamp(m32));
+                if (Math.abs(m32) < 0.9999999) {
+                    out.y = Math.atan2(-m31, m33);
+                    out.z = Math.atan2(-m12, m22);
+                }
+                else {
+                    out.y = 0;
+                    out.z = Math.atan2(m21, m11);
+                }
+                break;
+            case "ZYX":
+                out.y = Math.asin(-clamp(m31));
+                if (Math.abs(m31) < 0.9999999) {
+                    out.x = Math.atan2(m32, m33);
+                    out.z = Math.atan2(m21, m11);
+                }
+                else {
+                    out.x = 0;
+                    out.z = Math.atan2(-m12, m22);
+                }
+                break;
+            case "YZX":
+                out.z = Math.asin(clamp(m21));
+                if (Math.abs(m21) < 0.9999999) {
+                    out.x = Math.atan2(-m23, m22);
+                    out.y = Math.atan2(-m31, m11);
+                }
+                else {
+                    out.x = 0;
+                    out.y = Math.atan2(m13, m33);
+                }
+                break;
+            case "XZY":
+                out.z = Math.asin(-clamp(m12));
+                if (Math.abs(m12) < 0.9999999) {
+                    out.x = Math.atan2(m32, m22);
+                    out.y = Math.atan2(m13, m11);
+                }
+                else {
+                    out.x = Math.atan2(-m23, m33);
+                    out.y = 0;
+                }
+                break;
+        }
+        return out;
+    }
+    static toEulerOrder(q, order) {
+        return Quat.toEulerOrderInto(q, order, new Vec3(0, 0, 0));
+    }
 }
 export class Mat4 {
     constructor(values) {
@@ -762,6 +1084,12 @@ export class Mat4 {
         return new Mat4(out);
     }
 }
+// Module-private scratch for Quat.toEulerOrderInto / lookRotationInto (never handed out,
+// so no cross-call stomping with the public pools below).
+const _eulerMat = new Float32Array(16);
+const _lookX = new Vec3(0, 0, 0);
+const _lookY = new Vec3(0, 0, 0);
+const _lookZ = new Vec3(0, 0, 0);
 // Preallocated scratch instances for hot paths. Each subsystem should use its own
 // slot to avoid cross-call stomping. Bump the count if more call sites need scratch.
 export const scratchMat4Values = [