reze-engine 0.30.2 → 0.31.0

package/dist/index.d.ts

@@ -14,10 +14,11 @@ export { BODY_GRAPH } from "./graph/presets/body";
 export { STOCKINGS_GRAPH } from "./graph/presets/stockings";
 export { EYE_GRAPH } from "./graph/presets/eye";
 export { FACE_GRAPH } from "./graph/presets/face";
-export { Model } from "./model";
+export { Model, type ClipEventInfo } from "./model";
 export { Vec3, Quat, Mat4, easeInOut, type EulerOrder } from "./math";
 export type { AnimationClip, AnimationPlayOptions, AnimationProgress, BlendEntry, BoneKeyframe, IkKeyframe, MorphKeyframe, BoneInterpolation, ControlPoint, } from "./animation";
-export { LocomotionController, type LocomotionClips, type LocomotionOptions, type LocomotionPose, type StrafeClipEntry, } from "./locomotion";
+export { LocomotionController, type LocomotionClips, type LocomotionOptions, type LocomotionPose, type StrafeClipEntry, type TurnClipEntry, type RunTurnClipEntry, type StopClipEntry, } from "./locomotion";
+export { AnimationStateMachine, type AnimStateDef, type AnimTransitionDef, type StateMachineOptions } from "./state-machine";
 export { FPS, bezierInterpolate, interpolateControlPoints, rawInterpolationToBoneInterpolation, } from "./animation";
 export { VMDLoader, type CameraKeyframe, type IkFrame } from "./vmd-loader";
 export { VMDWriter } from "./vmd-writer";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,GAC5B,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AACvG,OAAO,EACL,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,SAAS,GACf,MAAM,iBAAiB,CAAA;AACxB,YAAY,EACV,WAAW,EACX,SAAS,EACT,SAAS,EACT,YAAY,EACZ,WAAW,EACX,UAAU,GACX,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,KAAK,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAC3E,OAAO,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC7G,YAAY,EACV,UAAU,EACV,eAAe,EACf,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAA;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AAC/D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAC/B,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,QAAQ,CAAA;AACrE,YAAY,EACV,aAAa,EACb,oBAAoB,EACpB,iBAAiB,EACjB,UAAU,EACV,YAAY,EACZ,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,YAAY,GACb,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,GAAG,EACH,iBAAiB,EACjB,wBAAwB,EACxB,mCAAmC,GACpC,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,KAAK,OAAO,EAAE,MAAM,cAAc,CAAA;AAC3E,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,OAAO,EAAE,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAA;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,GAC5B,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AACvG,OAAO,EACL,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,SAAS,GACf,MAAM,iBAAiB,CAAA;AACxB,YAAY,EACV,WAAW,EACX,SAAS,EACT,SAAS,EACT,YAAY,EACZ,WAAW,EACX,UAAU,GACX,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,KAAK,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAC3E,OAAO,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC7G,YAAY,EACV,UAAU,EACV,eAAe,EACf,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAA;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AAC/D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,KAAK,EAAE,KAAK,aAAa,EAAE,MAAM,SAAS,CAAA;AACnD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,QAAQ,CAAA;AACrE,YAAY,EACV,aAAa,EACb,oBAAoB,EACpB,iBAAiB,EACjB,UAAU,EACV,YAAY,EACZ,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,YAAY,GACb,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,aAAa,GACnB,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,qBAAqB,EAAE,KAAK,YAAY,EAAE,KAAK,iBAAiB,EAAE,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAC5H,OAAO,EACL,GAAG,EACH,iBAAiB,EACjB,wBAAwB,EACxB,mCAAmC,GACpC,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,KAAK,OAAO,EAAE,MAAM,cAAc,CAAA;AAC3E,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,OAAO,EAAE,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAA;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA"}

package/dist/index.js

@@ -15,6 +15,7 @@ export { FACE_GRAPH } from "./graph/presets/face";
 export { Model } from "./model";
 export { Vec3, Quat, Mat4, easeInOut } from "./math";
 export { LocomotionController, } from "./locomotion";
+export { AnimationStateMachine } from "./state-machine";
 export { FPS, bezierInterpolate, interpolateControlPoints, rawInterpolationToBoneInterpolation, } from "./animation";
 export { VMDLoader } from "./vmd-loader";
 export { VMDWriter } from "./vmd-writer";

package/dist/locomotion.d.ts

@@ -1,4 +1,5 @@
 import { Model } from "./model";
+import { type BlendEntry } from "./animation";
 import { Quat, Vec3 } from "./math";
 export interface StrafeClipEntry {
     /** Clip name previously loaded on the model. */
@@ -8,6 +9,38 @@ export interface StrafeClipEntry {
     /** The clip's authored root speed in MMD units/s (post-conversion scale) — drives root motion. */
     speed: number;
 }
+export interface TurnClipEntry {
+    /** Clip name previously loaded on the model. */
+    clip: string;
+    /** Signed yaw the clip turns through, radians (+ = the character's right). */
+    angle: number;
+    /** Clip-local seconds at which the yaw is complete (the settle tail is skipped). */
+    exitTime: number;
+}
+export interface RunTurnClipEntry {
+    /** Clip name previously loaded on the model. */
+    clip: string;
+    /** Signed total yaw, radians (+ = the character's right; reversals are ±PI). */
+    angle: number;
+    /** Clip-local seconds at which the yaw is complete (settle tail skipped). */
+    exitTime: number;
+    /** Uniform samples over [0, exitTime] of the clip's authored forward displacement
+     *  (MMD units along the heading at trigger) — the overrun-plant-return curve. */
+    forward: number[];
+    gear: "run" | "sprint";
+    foot: "L" | "R";
+}
+export interface StopClipEntry {
+    /** Clip name previously loaded on the model. */
+    clip: string;
+    /** Clip-local seconds at which the deceleration settles (idle tail skipped). */
+    exitTime: number;
+    /** Uniform samples over [0, exitTime] of the authored forward displacement
+     *  (MMD units along the heading at release) — the skid-to-plant curve. */
+    forward: number[];
+    gear: "run" | "sprint";
+    foot: "L" | "R";
+}
 export interface LocomotionClips {
     /** Clip names previously loaded on the model (loadVmd/loadClip). */
     idle: string;
@@ -17,8 +50,25 @@ export interface LocomotionClips {
      *  blends the two ring clips nearest the local move angle. */
     strafeRun?: StrafeClipEntry[];
     strafeSprint?: StrafeClipEntry[];
+    /** Authored turn-in-place clips: reversal-class direction changes from near-
+     *  standstill play the nearest clip (yaw baked in the bones, root held) and
+     *  transfer its angle to the root at exitTime — instead of the eased pivot. */
+    turnInPlace?: TurnClipEntry[];
+    /** Authored RUNNING reversals (plant-and-turn): while moving fast with a
+     *  reversal-class heading error, the matching clip plays with the root driven
+     *  along its measured forward profile; yaw transfers at exitTime and she runs
+     *  out along the new heading. */
+    runTurn?: RunTurnClipEntry[];
+    /** Authored stops: releasing input at speed plays the gear/foot-matched stop with
+     *  the root driven along its measured skid profile, instead of a blend to idle.
+     *  Re-pressing input interrupts the stop and resumes locomotion. */
+    stop?: StopClipEntry[];
 }
 export interface LocomotionOptions {
+    /** When false, update() computes the pose but does NOT call setBlendPose —
+     *  read it with getBlendEntries(). For embedding in an AnimationStateMachine
+     *  delegate state, which owns the final blend. Default true. */
+    autoApply?: boolean;
     /** Ground speed in MMD units/second at full run (default 67 — measured from the Unity
      *  locomotion pack's root motion before the in-place strip; ≈5.4 m/s at MMD scale).
      *  Match this to the clips or the feet slide. */
@@ -32,6 +82,14 @@ export interface LocomotionOptions {
     /** Heading error (radians) beyond which the character pivots strictly in place —
      *  no translation until the body is back within this cone (default PI/4). */
     turnInPlaceThreshold?: number;
+    /** Minimum heading error (radians) for an authored turn clip to fire (default
+     *  ~100°: reversals only — smaller corrections keep the instant pivot). */
+    turnClipMinAngle?: number;
+    /** Playback rate for turn clips (default 1.4 — the authored turns are deliberate;
+     *  game pacing wants them brisker). */
+    turnTimeScale?: number;
+    /** Playback rate for stop clips (default 1.25) — same reasoning. */
+    stopTimeScale?: number;
     /** Tank-mode steering rate, radians/second (default 2.5 ≈ 143°/s). */
     steerRate?: number;
     /** Backpedal speed as a fraction of run speed in tank mode (default 0.5). */
@@ -54,12 +112,24 @@ export interface LocomotionPose {
 }
 export declare class LocomotionController {
     private readonly model;
+    private readonly autoApply;
+    private lastEntries;
     private readonly clips;
     private readonly runSpeed;
     private readonly sprintSpeed;
     private readonly speedResponse;
     private readonly turnResponse;
     private readonly cosTurnThreshold;
+    private readonly turnClipMinAngle;
+    private readonly turnTimeScale;
+    private readonly stopTimeScale;
+    private turning;
+    private runTurning;
+    /** An interrupted authored clip fading out OVER resumed locomotion, so breaking
+     *  out of a stop is instantly responsive without a pose pop. */
+    private exitGhost;
+    private stopping;
+    private readonly turnEntries;
     private readonly yawOffset;
     private inputX;
     private inputY;
@@ -70,6 +140,10 @@ export declare class LocomotionController {
     private readonly steerRate;
     private readonly backpedalScale;
     private speedLevel;
+    /** Peak-hold of speedLevel (decays ~1.5/s): reversal triggers read this, because
+     *  keyboard direction flips pass through a dead moment (W+S cancel, key gap) that
+     *  dips the instantaneous level right when the reversal input lands. */
+    private recentSpeed;
     private yaw;
     private dirX;
     private dirZ;
@@ -102,6 +176,10 @@ export declare class LocomotionController {
     getPosition(): Vec3;
     /** Stop driving the model's pose (the blend is cleared; the single-clip player resumes). */
     detach(): void;
+    /** The most recent update()'s blend entries (null before the first update or
+     *  after detach). The array is reused between frames — read, don't hold. */
+    getBlendEntries(): BlendEntry[] | null;
+    private emit;
     private clipDuration;
     /** Advance one frame: integrates yaw + position, updates the clip clocks, hands the
      *  weighted pose to the model, and returns the root transform to apply. */
@@ -113,5 +191,21 @@ export declare class LocomotionController {
      *  nearest the local move angle, per gear, all sharing one gait phase. Root motion
      *  follows the input direction at the pair's authored (angle-lerped) speed. */
     private updateStrafe;
+    /** Authored turn-in-place frame: the clip rotates the body through its bones while
+     *  the root yaw stays frozen; at exitTime the measured angle transfers to the root
+     *  in the same instant the pose hands back to idle — the same orientation expressed
+     *  two ways, so the cut is seamless. No translation during the turn. */
+    private updateTurnClip;
+    /** Authored-stop frame: root follows the clip's measured skid profile along the
+     *  release heading; input returning interrupts and resumes locomotion at a level
+     *  proportional to how much of the stop remains. */
+    private updateStop;
+    /** Linear interpolation over a uniformly sampled profile at t in [0, 1]. */
+    private static profileAt;
+    /** Running-reversal frame: bones carry the turn while the root travels the clip's
+     *  AUTHORED forward profile along the trigger heading (overrun, plant, return) —
+     *  no fabricated motion, so the feet stay glued. At exitTime the yaw transfers
+     *  and the normal path runs her out along the new heading. */
+    private updateRunTurn;
 }
 //# sourceMappingURL=locomotion.d.ts.map

package/dist/locomotion.d.ts.map

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

package/dist/locomotion.js

@@ -15,6 +15,13 @@ function wrapAngle(a) {
 }
 export class LocomotionController {
     constructor(model, clips, options) {
+        this.lastEntries = null;
+        this.turning = null;
+        this.runTurning = null;
+        /** An interrupted authored clip fading out OVER resumed locomotion, so breaking
+         *  out of a stop is instantly responsive without a pose pop. */
+        this.exitGhost = null;
+        this.stopping = null;
         this.inputX = 0;
         this.inputY = 0;
         this.inputSprint = false;
@@ -23,6 +30,10 @@ export class LocomotionController {
         this.inputForward = 0;
         this.inputSteer = 0;
         this.speedLevel = 0;
+        /** Peak-hold of speedLevel (decays ~1.5/s): reversal triggers read this, because
+         *  keyboard direction flips pass through a dead moment (W+S cancel, key gap) that
+         *  dips the instantaneous level right when the reversal input lands. */
+        this.recentSpeed = 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
@@ -40,8 +51,17 @@ export class LocomotionController {
         this.runSpeed = options?.runSpeed ?? 67;
         this.sprintSpeed = options?.sprintSpeed ?? 92;
         this.speedResponse = options?.speedResponse ?? 5;
+        this.autoApply = options?.autoApply ?? true;
         this.turnResponse = options?.turnResponse ?? 10;
         this.cosTurnThreshold = Math.cos(options?.turnInPlaceThreshold ?? Math.PI / 4);
+        this.turnClipMinAngle = options?.turnClipMinAngle ?? (100 * Math.PI) / 180;
+        this.turnTimeScale = options?.turnTimeScale ?? 1.4;
+        this.stopTimeScale = options?.stopTimeScale ?? 1.25;
+        this.turnEntries = [
+            { name: clips.idle, time: 0, weight: 0 },
+            { name: clips.idle, time: 0, weight: 1 },
+            { name: clips.idle, time: 0, weight: 0 },
+        ];
         this.steerRate = options?.steerRate ?? 2.5;
         this.backpedalScale = options?.backpedalScale ?? 0.5;
         this.yawOffset = options?.yawOffset ?? Math.PI;
@@ -49,6 +69,7 @@ export class LocomotionController {
             { name: clips.idle, time: 0, weight: 1 },
             { name: clips.run, time: 0, weight: 0 },
             { name: clips.sprint ?? clips.run, time: 0, weight: 0 },
+            { name: clips.idle, time: 0, weight: 0 }, // fading ghost of an interrupted clip
         ];
         const byAngle = (a, b) => a.angle - b.angle;
         this.strafeRun = clips.strafeRun ? [...clips.strafeRun].sort(byAngle) : null;
@@ -97,7 +118,19 @@ export class LocomotionController {
     }
     /** Stop driving the model's pose (the blend is cleared; the single-clip player resumes). */
     detach() {
-        this.model.clearBlendPose();
+        this.lastEntries = null;
+        if (this.autoApply)
+            this.model.clearBlendPose();
+    }
+    /** The most recent update()'s blend entries (null before the first update or
+     *  after detach). The array is reused between frames — read, don't hold. */
+    getBlendEntries() {
+        return this.lastEntries;
+    }
+    emit(entries) {
+        this.lastEntries = entries;
+        if (this.autoApply)
+            this.model.setBlendPose(entries);
     }
     clipDuration(name) {
         const frames = this.model.getClip(name)?.frameCount ?? 0;
@@ -111,6 +144,15 @@ export class LocomotionController {
         if (this.facingYaw !== null && this.strafeRun !== null && !this.tankMode) {
             return this.updateStrafe(dt);
         }
+        if (this.turning !== null) {
+            return this.updateTurnClip(dt);
+        }
+        if (this.runTurning !== null) {
+            return this.updateRunTurn(dt);
+        }
+        if (this.stopping !== null) {
+            return this.updateStop(dt);
+        }
         const hasSprint = this.clips.sprint !== undefined;
         let moving;
         let align = 1;
@@ -131,12 +173,99 @@ export class LocomotionController {
         else {
             const m = Math.hypot(this.inputX, this.inputY);
             moving = m > 0.05;
+            this.recentSpeed = Math.max(this.speedLevel, this.recentSpeed - dt * 1.5);
+            // Release at speed: play the authored stop instead of blending to idle.
+            const stops = this.clips.stop;
+            // Gate on the peak-hold speed: the release decay (throttle/analog) drains the
+            // instantaneous level below any threshold before `moving` goes false. The
+            // small floor on the actual level keeps standstill taps from faking a skid.
+            if (!moving && stops && stops.length > 0 && this.recentSpeed >= 0.7 && this.speedLevel >= 0.35) {
+                const gear = this.recentSpeed > 1.4 ? "sprint" : "run";
+                const foot = this.gaitPhase < 0.5 ? "L" : "R";
+                // Gear must match exactly: supplying stops for only one gear means the
+                // other gear keeps the default quick blend-to-idle.
+                let best = null;
+                let bestScore = -1;
+                for (const e of stops) {
+                    if (e.gear !== gear)
+                        continue;
+                    const score = e.foot === foot ? 1 : 0;
+                    if (score > bestScore) {
+                        best = e;
+                        bestScore = score;
+                    }
+                }
+                if (best) {
+                    const fromClip = gear === "sprint" && this.clips.sprint ? this.clips.sprint : this.clips.run;
+                    this.stopping = {
+                        entry: best,
+                        time: 0,
+                        startX: this.position.x,
+                        startZ: this.position.z,
+                        dirX: this.dirX,
+                        dirZ: this.dirZ,
+                        startLevel: Math.min(this.recentSpeed, 2),
+                        fromIdleW: Math.max(0, 1 - this.speedLevel),
+                        fromClip,
+                        fromTime: this.gaitPhase * this.clipDuration(fromClip),
+                    };
+                    return this.updateStop(dt);
+                }
+            }
             // 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);
+                // Running reversal: while moving fast with a reversal-class error, play the
+                // authored plant-and-turn for the current gear and gait foot.
+                const runTurns = this.clips.runTurn;
+                if (runTurns && runTurns.length > 0 && this.recentSpeed >= 0.6 && Math.abs(err) >= (130 * Math.PI) / 180) {
+                    const gear = this.recentSpeed > 1.4 ? "sprint" : "run";
+                    const foot = this.gaitPhase < 0.5 ? "L" : "R";
+                    const side = err < 0 ? -1 : 1;
+                    let best = null;
+                    let bestScore = -1;
+                    for (const e of runTurns) {
+                        if (Math.sign(e.angle) !== side)
+                            continue;
+                        const score = (e.gear === gear ? 2 : 0) + (e.foot === foot ? 1 : 0);
+                        if (score > bestScore) {
+                            best = e;
+                            bestScore = score;
+                        }
+                    }
+                    if (best) {
+                        // Restore the pre-dip speed so she runs OUT of the turn at pace.
+                        this.speedLevel = Math.max(this.speedLevel, Math.min(this.recentSpeed, 2));
+                        this.runTurning = {
+                            entry: best,
+                            time: 0,
+                            startX: this.position.x,
+                            startZ: this.position.z,
+                            dirX: Math.sin(this.yaw),
+                            dirZ: Math.cos(this.yaw),
+                        };
+                        return this.updateRunTurn(dt);
+                    }
+                }
+                // Reversal-class turn from near-standstill: play the authored turn clip
+                // whose angle is nearest the error instead of the eased pivot.
+                const turnClips = this.clips.turnInPlace;
+                if (turnClips && turnClips.length > 0 && this.speedLevel < 0.3 && Math.abs(err) >= this.turnClipMinAngle) {
+                    let best = turnClips[0];
+                    let bestD = Math.abs(wrapAngle(err - best.angle));
+                    for (const e of turnClips) {
+                        const d = Math.abs(wrapAngle(err - e.angle));
+                        if (d < bestD) {
+                            best = e;
+                            bestD = d;
+                        }
+                    }
+                    this.turning = { entry: best, time: 0 };
+                    return this.updateTurnClip(dt);
+                }
                 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;
@@ -186,7 +315,28 @@ export class LocomotionController {
         this.entries[1].weight = wRun;
         this.entries[2].time = this.gaitPhase * sprintDur;
         this.entries[2].weight = wSprint;
-        this.model.setBlendPose(this.entries);
+        const GHOST_FADE = 0.25;
+        if (this.exitGhost) {
+            const g = this.exitGhost;
+            g.elapsed += dt;
+            const wGhost = Math.max(0, 1 - g.elapsed / GHOST_FADE);
+            if (wGhost <= 0) {
+                this.exitGhost = null;
+                this.entries[3].weight = 0;
+            }
+            else {
+                this.entries[0].weight *= 1 - wGhost;
+                this.entries[1].weight *= 1 - wGhost;
+                this.entries[2].weight *= 1 - wGhost;
+                this.entries[3].name = g.clip;
+                this.entries[3].time = g.clipTime + g.elapsed; // the clip's real tail keeps playing
+                this.entries[3].weight = wGhost;
+            }
+        }
+        else {
+            this.entries[3].weight = 0;
+        }
+        this.emit(this.entries);
         const ry = this.yaw + this.yawOffset;
         const half = ry * 0.5;
         this.rotation.setXYZW(0, Math.sin(half), 0, Math.cos(half));
@@ -286,7 +436,7 @@ export class LocomotionController {
         e[4].name = sprintB.clip;
         e[4].time = this.gaitPhase * sprintDur;
         e[4].weight = wSprint * sprintT;
-        this.model.setBlendPose(e);
+        this.emit(e);
         const ry = this.yaw + this.yawOffset;
         const half = ry * 0.5;
         this.rotation.setXYZW(0, Math.sin(half), 0, Math.cos(half));
@@ -294,4 +444,183 @@ export class LocomotionController {
         this.pose.speedLevel = level;
         return this.pose;
     }
+    /** Authored turn-in-place frame: the clip rotates the body through its bones while
+     *  the root yaw stays frozen; at exitTime the measured angle transfers to the root
+     *  in the same instant the pose hands back to idle — the same orientation expressed
+     *  two ways, so the cut is seamless. No translation during the turn. */
+    updateTurnClip(dt) {
+        const t = this.turning;
+        t.time += dt * this.turnTimeScale;
+        // Speed level settles toward 0 while turning (we were near-standstill already).
+        const maxStep = this.speedResponse * dt;
+        this.speedLevel += Math.abs(-this.speedLevel) <= maxStep ? -this.speedLevel : -Math.sign(this.speedLevel) * maxStep;
+        const idleDur = this.clipDuration(this.clips.idle);
+        this.idleTime = (this.idleTime + dt) % idleDur;
+        if (t.time >= t.entry.exitTime) {
+            // Transfer the angle to the root and hand the pose to idle IN THE SAME frame —
+            // leaving the previous blend up would double the rotation for one frame.
+            this.yaw = wrapAngle(this.yaw + t.entry.angle);
+            this.turning = null;
+            const e = this.turnEntries;
+            e[0].weight = 0;
+            e[1].name = this.clips.idle;
+            e[1].time = this.idleTime;
+            e[1].weight = 1;
+            e[2].weight = 0;
+            this.emit(e);
+        }
+        else {
+            // Fade the turn clip over idle at the edges so entry doesn't pop.
+            const w = Math.min(1, t.time / 0.12);
+            const e = this.turnEntries;
+            e[0].name = t.entry.clip;
+            e[0].time = Math.min(t.time, t.entry.exitTime);
+            e[0].weight = w;
+            e[1].name = this.clips.idle;
+            e[1].time = this.idleTime;
+            e[1].weight = 1 - w;
+            e[2].weight = 0;
+            this.emit(e);
+        }
+        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;
+    }
+    /** Authored-stop frame: root follows the clip's measured skid profile along the
+     *  release heading; input returning interrupts and resumes locomotion at a level
+     *  proportional to how much of the stop remains. */
+    updateStop(dt) {
+        const t = this.stopping;
+        const entry = t.entry;
+        // Interrupt: input came back — locomotion resumes instantly from a LOW level
+        // (a stop is committed; breaking out is a fresh walk-up, never a drift), while
+        // the stop pose fades out as a ghost instead of hard-cutting.
+        if (Math.hypot(this.inputX, this.inputY) > 0.05) {
+            this.speedLevel = Math.min(t.startLevel * (1 - Math.min(1, t.time / entry.exitTime)), 0.3);
+            this.recentSpeed = this.speedLevel;
+            this.exitGhost = { clip: entry.clip, clipTime: Math.min(t.time, entry.exitTime), elapsed: 0 };
+            this.stopping = null;
+            return this.update(dt);
+        }
+        t.time += dt * this.stopTimeScale;
+        const clipT = Math.min(t.time, entry.exitTime);
+        const fwd = LocomotionController.profileAt(entry.forward, clipT / entry.exitTime);
+        this.position.x = t.startX + t.dirX * fwd;
+        this.position.z = t.startZ + t.dirZ * fwd;
+        this.speedLevel = t.startLevel * Math.max(0, 1 - t.time / entry.exitTime);
+        const idleDur = this.clipDuration(this.clips.idle);
+        this.idleTime = (this.idleTime + dt) % idleDur;
+        const FADE_OUT = 0.35;
+        if (t.time >= entry.exitTime + FADE_OUT) {
+            this.stopping = null;
+            this.speedLevel = 0;
+            this.gaitPhase = 0;
+            const e = this.turnEntries;
+            e[0].weight = 0;
+            e[1].name = this.clips.idle;
+            e[1].time = this.idleTime;
+            e[1].weight = 1;
+            e[2].weight = 0;
+            this.emit(e);
+        }
+        else if (t.time >= entry.exitTime) {
+            // Settle tail: the root is already still, so keep playing the clip's own
+            // recovery (it exists past exitTime) while fading to idle — no hard cut.
+            const wOut = (t.time - entry.exitTime) / FADE_OUT;
+            const e = this.turnEntries;
+            e[0].name = entry.clip;
+            e[0].time = t.time; // real tail frames beyond exitTime
+            e[0].weight = 1 - wOut;
+            e[1].name = this.clips.idle;
+            e[1].time = this.idleTime;
+            e[1].weight = wOut;
+            e[2].weight = 0;
+            this.emit(e);
+        }
+        else {
+            const fromDur = this.clipDuration(t.fromClip);
+            t.fromTime = (t.fromTime + dt) % fromDur;
+            const w = Math.min(1, t.time / 0.25);
+            const e = this.turnEntries;
+            e[0].name = entry.clip;
+            e[0].time = clipT;
+            e[0].weight = w;
+            e[1].name = t.fromClip;
+            e[1].time = t.fromTime;
+            e[1].weight = (1 - w) * (1 - t.fromIdleW);
+            e[2].name = this.clips.idle;
+            e[2].time = this.idleTime;
+            e[2].weight = (1 - w) * t.fromIdleW;
+            this.emit(e);
+        }
+        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;
+    }
+    /** Linear interpolation over a uniformly sampled profile at t in [0, 1]. */
+    static profileAt(samples, t) {
+        const n = samples.length - 1;
+        if (n <= 0)
+            return 0;
+        const x = Math.min(Math.max(t, 0), 1) * n;
+        const i = Math.min(n - 1, Math.floor(x));
+        return samples[i] + (samples[i + 1] - samples[i]) * (x - i);
+    }
+    /** Running-reversal frame: bones carry the turn while the root travels the clip's
+     *  AUTHORED forward profile along the trigger heading (overrun, plant, return) —
+     *  no fabricated motion, so the feet stay glued. At exitTime the yaw transfers
+     *  and the normal path runs her out along the new heading. */
+    updateRunTurn(dt) {
+        const t = this.runTurning;
+        t.time += dt;
+        const entry = t.entry;
+        const clipT = Math.min(t.time, entry.exitTime);
+        const fwd = LocomotionController.profileAt(entry.forward, clipT / entry.exitTime);
+        this.position.x = t.startX + t.dirX * fwd;
+        this.position.z = t.startZ + t.dirZ * fwd;
+        const idleDur = this.clipDuration(this.clips.idle);
+        this.idleTime = (this.idleTime + dt) % idleDur;
+        if (t.time >= entry.exitTime) {
+            this.yaw = wrapAngle(this.yaw + entry.angle);
+            this.runTurning = null;
+            // She exits mid-stride: keep the speed level, restart the gait cleanly, and
+            // point the travel direction along the new heading so the next frame runs out.
+            this.gaitPhase = 0;
+            this.dirX = Math.sin(this.yaw);
+            this.dirZ = Math.cos(this.yaw);
+            const e = this.turnEntries;
+            e[0].name = this.clips.run;
+            e[0].time = 0;
+            e[0].weight = Math.min(1, this.speedLevel);
+            e[1].name = this.clips.idle;
+            e[1].time = this.idleTime;
+            e[1].weight = 1 - Math.min(1, this.speedLevel);
+            e[2].weight = 0;
+            this.emit(e);
+        }
+        else {
+            const w = Math.min(1, t.time / 0.1);
+            const e = this.turnEntries;
+            e[0].name = entry.clip;
+            e[0].time = clipT;
+            e[0].weight = w;
+            e[1].name = this.clips.run;
+            e[1].time = this.gaitPhase * this.clipDuration(this.clips.run);
+            e[1].weight = 1 - w;
+            e[2].weight = 0;
+            this.emit(e);
+        }
+        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/model.d.ts

@@ -2,6 +2,13 @@ import { Mat4, Quat, Vec3 } from "./math";
 import { type AssetReader } from "./asset-reader";
 import { Rigidbody, Joint } from "./physics";
 import { AnimationClip, AnimationPlayOptions, AnimationProgress, BlendEntry } from "./animation";
+export interface ClipEventInfo {
+    clip: string;
+    /** The registered event time, seconds. */
+    time: number;
+    /** The clip's blend weight at the moment of firing. */
+    weight: number;
+}
 export interface Texture {
     path: string;
     name: string;
@@ -157,6 +164,10 @@ export declare class Model {
     private lastAppliedClip;
     private oneShot;
     private readonly oneShotEntries;
+    /** Time-triggered clip callbacks (footsteps, skill timing). Fired by every
+     *  playback path when a clip's cursor crosses the event time with weight. */
+    private readonly clipEvents;
+    private readonly entryEventPrev;
     private blendEntries;
     private crossfade;
     private readonly blendBoneCursors;
@@ -253,6 +264,18 @@ export declare class Model {
     cancelOneShot(fadeOut?: number): void;
     /** Name of the active one-shot, or null. */
     getOneShot(): string | null;
+    /** Fire `callback` whenever `clip`'s playback crosses `time` (seconds) with at
+     *  least `minWeight` influence (default 0.1) — on any path: blend entries,
+     *  one-shots, crossfades, or plain play. Loop wraps fire correctly; hard cursor
+     *  jumps may occasionally fire or skip (events are for sfx-grade timing, not
+     *  logic). Returns an unsubscribe function. */
+    addClipEvent(clip: string, time: number, callback: (e: ClipEventInfo) => void, options?: {
+        minWeight?: number;
+    }): () => void;
+    private fireClipEvents;
+    /** Per-entry cursor memory for event crossing detection; keyed on entry object
+     *  identity (controllers reuse their arrays, so this stays warm). */
+    private trackEntryEvents;
     /** Fade from the currently playing clip (or from the rest pose when nothing plays)
      *  into `name` over `seconds`. The target starts at frame 0 and becomes the current
      *  clip immediately — progress, looping and the camera clock report the target for