reze-engine 0.29.1 → 0.30.1

package/dist/model.js

@@ -101,6 +101,11 @@ export class Model {
         this.boneTrackIndices = new Map();
         this.morphTrackIndices = new Map();
         this.lastAppliedClip = null;
+        // One-shot action layer: plays a clip ONCE over whatever else drives the pose
+        // (locomotion blend, a playing clip, a crossfade, or rest), with fade-in/out
+        // envelopes — the background keeps advancing and is what the fade-out returns to.
+        this.oneShot = null;
+        this.oneShotEntries = [];
         // Blended pose: declarative N-clip mix (setBlendPose) or a running crossfade.
         // Cursor caches are per clip so sampling several clips in one frame doesn't
         // thrash the single-clip caches above; WeakMap so removed clips can collect.
@@ -1018,6 +1023,7 @@ export class Model {
         }
         this.blendEntries = null;
         this.crossfade = null;
+        this.oneShot = null;
         this.resetAllBones();
         this.resetAllMorphs();
         return this.animationState.play(name, options);
@@ -1025,6 +1031,7 @@ export class Model {
     show(name) {
         this.blendEntries = null;
         this.crossfade = null;
+        this.oneShot = null;
         this.resetAllBones();
         this.resetAllMorphs();
         this.animationState.show(name);
@@ -1042,6 +1049,36 @@ export class Model {
     clearBlendPose() {
         this.blendEntries = null;
     }
+    /** Play a clip ONCE over whatever currently drives the pose — the locomotion blend,
+     *  a playing clip, a crossfade, or rest. The background keeps advancing underneath;
+     *  fade-in ramps the one-shot over it and fade-out returns to whatever the
+     *  background is doing by then. Replaces any active one-shot immediately. */
+    playOneShot(name, options) {
+        const clip = this.animationState.getAnimationClip(name);
+        if (!clip || clip.frameCount <= 0 || !Number.isFinite(clip.frameCount))
+            return false;
+        const duration = clip.frameCount / FPS;
+        const fadeIn = Math.max(0, options?.fadeIn ?? 0.15);
+        const fadeOut = Math.max(0, Math.min(options?.fadeOut ?? 0.25, duration));
+        this.oneShot = { name, time: 0, duration, fadeIn, fadeOut, cancelW: 1, cancelling: false, onEnd: options?.onEnd ?? null };
+        this.clipApplySuspended = false;
+        return true;
+    }
+    /** Fade the active one-shot out early over `fadeOut` seconds (default 0.2). */
+    cancelOneShot(fadeOut = 0.2) {
+        if (!this.oneShot)
+            return;
+        if (fadeOut <= 0) {
+            this.oneShot = null;
+            return;
+        }
+        this.oneShot.cancelling = true;
+        this.oneShot.fadeOut = fadeOut;
+    }
+    /** Name of the active one-shot, or null. */
+    getOneShot() {
+        return this.oneShot?.name ?? null;
+    }
     /** 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
@@ -1050,6 +1087,7 @@ export class Model {
         if (!this.animationState.hasAnimation(name))
             return false;
         this.blendEntries = null;
+        this.oneShot = null;
         this.clipApplySuspended = false;
         const fromName = this.animationState.getCurrentAnimation();
         const fromFrame = this.animationState.getCurrentFrame();
@@ -1077,6 +1115,7 @@ export class Model {
     stop() {
         this.blendEntries = null;
         this.crossfade = null;
+        this.oneShot = null;
         this.animationState.stop();
     }
     // @deprecated Use model.stop()
@@ -1089,6 +1128,7 @@ export class Model {
     clearAnimation() {
         this.blendEntries = null;
         this.crossfade = null;
+        this.oneShot = null;
         this.animationState.clear();
     }
     // Seek by absolute timeline seconds, not frame index.
@@ -1381,6 +1421,61 @@ export class Model {
             this.morphsDirty = true;
         }
     }
+    /** One one-shot step: weight envelope from fade-in/out (easeInOut-shaped), the
+     *  background entries scaled by 1-w underneath, the one-shot clip at w on top. */
+    applyOneShot(deltaTime) {
+        const os = this.oneShot;
+        if (os === null)
+            return;
+        os.time += deltaTime;
+        // Envelope: min of the fade-in ramp and the fade-out ramp (or the cancel ramp).
+        const wIn = os.fadeIn > 0 ? Math.min(1, os.time / os.fadeIn) : 1;
+        let wOut = 1;
+        if (os.cancelling) {
+            os.cancelW -= deltaTime / os.fadeOut;
+            wOut = Math.max(0, os.cancelW);
+        }
+        else if (os.fadeOut > 0) {
+            wOut = Math.max(0, Math.min(1, (os.duration - os.time) / os.fadeOut));
+        }
+        const w = easeInOut(Math.min(wIn, wOut));
+        // Background entries at (1 - w): the still-advancing blend, the current clip, or
+        // nothing (rest fill). Copied into a pooled array — never scale caller-owned weights.
+        const pool = this.oneShotEntries;
+        let n = 0;
+        const put = (name, time, weight) => {
+            if (pool.length <= n)
+                pool.push({ name: "", time: 0, weight: 0 });
+            const e = pool[n++];
+            e.name = name;
+            e.time = time;
+            e.weight = weight;
+        };
+        const bg = 1 - w;
+        if (bg > 1e-6) {
+            if (this.blendEntries !== null && this.blendEntries.length > 0) {
+                for (const e of this.blendEntries)
+                    put(e.name, e.time, e.weight * bg);
+            }
+            else {
+                const clip = this.animationState.getCurrentClip();
+                const name = this.animationState.getCurrentAnimation();
+                if (clip !== null && name !== null && name !== os.name) {
+                    put(name, this.animationState.getCurrentFrame() / FPS, bg);
+                }
+                // else: rest pose fills the remainder inside applyBlendedPose
+            }
+        }
+        put(os.name, Math.min(os.time, os.duration), w);
+        for (let i = n; i < pool.length; i++)
+            pool[i].weight = 0;
+        this.applyBlendedPose(pool);
+        if (os.time >= os.duration || (os.cancelling && os.cancelW <= 0)) {
+            const onEnd = os.onEnd;
+            this.oneShot = null;
+            onEnd?.();
+        }
+    }
     /** One crossfade step: advance the outgoing clock (the target's clock lives in
      *  animationState, already ticked by update), shape the weight with easeInOut,
      *  and hand both to the blend sampler. Holds in place while paused. */
@@ -1433,7 +1528,10 @@ export class Model {
         const tweensChangedMorphs = this.updateTweens();
         this.animationState.update(deltaTime);
         if (!this.clipApplySuspended) {
-            if (this.blendEntries !== null && this.blendEntries.length > 0) {
+            if (this.oneShot !== null) {
+                this.applyOneShot(deltaTime);
+            }
+            else if (this.blendEntries !== null && this.blendEntries.length > 0) {
                 this.applyBlendedPose(this.blendEntries);
             }
             else if (this.crossfade !== null) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reze-engine",
-  "version": "0.29.1",
+  "version": "0.30.1",
   "description": "A lightweight WebGPU engine for real-time 3D MMD/PMX model rendering",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/engine.ts

@@ -106,6 +106,13 @@ const PRESET_NAME_HINTS: Array<[MaterialPreset, string[]]> = [
       "尾",
       "套", // 外套 (coat), 手套 (gloves)
       "腿", // 腿环 (leg ring/garter) and other leg-wear accessories
+      "带", // straps and bands: 头带/发带/背带/腰带
+      "绳", // ropes: 背绳/腰绳
+      "纱", // gauze/veils: 头纱
+      "肩布", // shoulder cloth/drape
+      "背球", // back ornament sphere
+      "腰花", // waist flower
+      "花蕊", // flower pistil ornament
       "skirt",
       "dress",
       "ribbon",
@@ -367,6 +374,9 @@ export interface EngineStats {
   frameTimeMax: number // ms — worst frame interval in the window (hitch / stutter indicator)
   fps1PercentLow: number // "1% low" fps = 1000 / 99th-percentile frame interval
   jitter: number // ms — stddev of frame intervals (pacing evenness; high = janky at any mean fps)
+  cpuAnimMs: number // ms/frame (EMA) — model updates: blending, IK, world matrices
+  cpuPhysicsMs: number // ms/frame (EMA) — physics stepping across all instances
+  cpuRenderMs: number // ms/frame (EMA) — the rest of the render thread: uniforms, encoding, submit
 }
 
 type DrawCallType = "opaque" | "transparent" | "ground" | "opaque-outline" | "transparent-outline"
@@ -815,6 +825,9 @@ export class Engine {
     frameTime: 0,
     frameTimeMax: 0,
     fps1PercentLow: 0,
+    cpuAnimMs: 0,
+    cpuPhysicsMs: 0,
+    cpuRenderMs: 0,
     jitter: 0,
   }
   private animationFrameId: number | null = null
@@ -2949,17 +2962,35 @@ export class Engine {
     return { ...this.stats }
   }
 
+  /** Frame-rate cap for the render loop, or null for display-rate. On high-refresh
+   *  displays (144/240Hz) rAF runs the WHOLE pipeline — physics, IK, blending,
+   *  passes — that many times per second for no visible gain over ~120 (VMD content
+   *  is 30fps; blending interpolates). Capping restores the per-second budget. */
+  private maxFPS: number | null = null
+  private lastLoopTime = 0
+
+  setMaxFPS(fps: number | null): void {
+    this.maxFPS = fps !== null && fps > 0 ? fps : null
+  }
+
   runRenderLoop(callback?: () => void) {
     this.renderLoopCallback = callback || null
 
-    const loop = () => {
+    const loop = (now: number) => {
+      this.animationFrameId = requestAnimationFrame(loop)
+
+      if (this.maxFPS !== null) {
+        // Tolerate rAF jitter: accept frames within ~half a display tick early.
+        const minInterval = 1000 / this.maxFPS - 2
+        if (now - this.lastLoopTime < minInterval) return
+        this.lastLoopTime = now
+      }
+
       this.render()
 
       if (this.renderLoopCallback) {
         this.renderLoopCallback()
       }
-
-      this.animationFrameId = requestAnimationFrame(loop)
     }
 
     this.animationFrameId = requestAnimationFrame(loop)
@@ -3220,9 +3251,22 @@ export class Engine {
     for (const inst of this.modelInstances.values()) fn(inst)
   }
 
+  // CPU frame-time breakdown (EMA-smoothed into getStats): where a frame's
+  // milliseconds actually go — animation/IK/blending vs physics vs everything
+  // else on the render thread. The first question of any perf report.
+  private cpuAnimMs = 0
+  private cpuPhysicsMs = 0
+  private cpuRenderMs = 0
+  private frameAnimMsRaw = 0
+  private framePhysicsMsRaw = 0
+
   private updateInstances(deltaTime: number): void {
+    let animMs = 0
+    let physicsMs = 0
     this.forEachInstance((inst) => {
+      const tAnim = performance.now()
       const verticesChanged = inst.model.update(deltaTime, this.ikEnabled)
+      animMs += performance.now() - tAnim
       if (inst.gpuMorph) {
         // GPU path: on a weight change, upload effective weights (thresholding tiny values
         // to 0 to match the CPU skip) and flag the compute dispatch for this frame.
@@ -3241,10 +3285,17 @@ export class Engine {
         inst.vertexBufferNeedsUpdate = true
       }
       if (inst.physics && this.physicsEnabled) {
+        const tPhys = performance.now()
         inst.physics.step(deltaTime, inst.model.getWorldMatrices(), inst.model.getBoneInverseBindMatrices())
+        physicsMs += performance.now() - tPhys
       }
       if (inst.vertexBufferNeedsUpdate) this.updateVertexBuffer(inst)
     })
+    this.frameAnimMsRaw = animMs
+    this.framePhysicsMsRaw = physicsMs
+    const EMA = 0.1
+    this.cpuAnimMs += (animMs - this.cpuAnimMs) * EMA
+    this.cpuPhysicsMs += (physicsMs - this.cpuPhysicsMs) * EMA
   }
 
   private updateVertexBuffer(inst: ModelInstance): void {
@@ -3727,11 +3778,6 @@ export class Engine {
       // misclassified fully-worn opaque dresses (avg 0.69) as veils and stripped
       // their shadows, while any lower cliff would strand the next model.
       const castsShadow = (mat.edgeFlag & 0x04) !== 0
-      // Load-time classification log — one line per material, cheap and
-      // invaluable when a model renders wrong (bucket/outline/shadow disputes).
-      console.info(
-        `[reze] ${mat.name}: alpha=${materialAlpha.toFixed(2)} avg=${stats.avg.toFixed(2)} translucentFrac=${stats.translucentFrac.toFixed(2)} bucket=${isTransparent ? "transparent" : "opaque"} castsShadow=${castsShadow} edge=${(mat.edgeFlag & 0x10) !== 0 && mat.edgeSize > 0 ? "on" : "off"}`,
-      )
 
       // Sphere map (sph=1 multiply / spa=2 add). Mode 3 (sub-texture UV) is
       // rare and not implemented — treated as none, like a failed load.
@@ -4606,6 +4652,9 @@ export class Engine {
   }
 
   private renderWithDelta(deltaTime: number) {
+    const tFrame = performance.now()
+    this.frameAnimMsRaw = 0
+    this.framePhysicsMsRaw = 0
     if (this.resizePending) {
       this.resizePending = false
       this.handleResize()
@@ -4757,6 +4806,10 @@ export class Engine {
 
     this.device.queue.submit([encoder.finish()])
 
+    // Everything this frame that wasn't animation or physics: uniforms, encoding, submit.
+    const renderOnly = performance.now() - tFrame - this.frameAnimMsRaw - this.framePhysicsMsRaw
+    this.cpuRenderMs += (renderOnly - this.cpuRenderMs) * 0.1
+
     if (pick) {
       this.pendingPick = null
       const dpr = window.devicePixelRatio || 1
@@ -5387,5 +5440,8 @@ export class Engine {
     this.stats.frameTimeMax = Math.round(max * 100) / 100
     this.stats.fps1PercentLow = p99 > 0 ? Math.round(1000 / p99) : 0
     this.stats.jitter = Math.round(stddev * 100) / 100
+    this.stats.cpuAnimMs = Math.round(this.cpuAnimMs * 100) / 100
+    this.stats.cpuPhysicsMs = Math.round(this.cpuPhysicsMs * 100) / 100
+    this.stats.cpuRenderMs = Math.round(this.cpuRenderMs * 100) / 100
   }
 }

package/src/index.ts

@@ -70,6 +70,7 @@ export {
   type LocomotionClips,
   type LocomotionOptions,
   type LocomotionPose,
+  type StrafeClipEntry,
 } from "./locomotion"
 export {
   FPS,

package/src/locomotion.ts

@@ -8,11 +8,24 @@ import { Model } from "./model"
 import { FPS, type BlendEntry } from "./animation"
 import { Quat, Vec3 } from "./math"
 
+export interface StrafeClipEntry {
+  /** Clip name previously loaded on the model. */
+  clip: string
+  /** Movement direction relative to the facing, radians: 0 = forward, + = the character's right. */
+  angle: number
+  /** The clip's authored root speed in MMD units/s (post-conversion scale) — drives root motion. */
+  speed: number
+}
+
 export interface LocomotionClips {
   /** Clip names previously loaded on the model (loadVmd/loadClip). */
   idle: string
   run: string
   sprint?: string
+  /** Directional ring for strafe mode (setFacing): body holds a facing while movement
+   *  blends the two ring clips nearest the local move angle. */
+  strafeRun?: StrafeClipEntry[]
+  strafeSprint?: StrafeClipEntry[]
 }
 
 export interface LocomotionOptions {
@@ -93,6 +106,11 @@ export class LocomotionController {
 
   private readonly entries: BlendEntry[]
   private readonly pose: LocomotionPose
+  // Strafe mode: non-null = the world yaw the body holds (movement decoupled from facing).
+  private facingYaw: number | null = null
+  private readonly strafeRun: StrafeClipEntry[] | null
+  private readonly strafeSprint: StrafeClipEntry[] | null
+  private readonly strafeEntries: BlendEntry[]
 
   constructor(model: Model, clips: LocomotionClips, options?: LocomotionOptions) {
     this.model = model
@@ -110,6 +128,11 @@ export class LocomotionController {
       { name: clips.run, time: 0, weight: 0 },
       { name: clips.sprint ?? clips.run, time: 0, weight: 0 },
     ]
+    const byAngle = (a: StrafeClipEntry, b: StrafeClipEntry) => a.angle - b.angle
+    this.strafeRun = clips.strafeRun ? [...clips.strafeRun].sort(byAngle) : null
+    this.strafeSprint = clips.strafeSprint ? [...clips.strafeSprint].sort(byAngle) : null
+    // idle + adjacent pair per gear; unused slots keep weight 0 and are skipped.
+    this.strafeEntries = Array.from({ length: 5 }, () => ({ name: clips.idle, time: 0, weight: 0 }))
     this.pose = { position: this.position, yaw: 0, rotation: this.rotation, speedLevel: 0 }
   }
 
@@ -145,6 +168,13 @@ export class LocomotionController {
     this.yaw = yaw
   }
 
+  /** Strafe mode: hold the body at this world yaw (a camera forward, a lock-on target)
+   *  while setMove's vector drives the directional strafe ring — requires
+   *  clips.strafeRun. null returns to turn-toward-movement. */
+  setFacing(yaw: number | null): void {
+    this.facingYaw = this.strafeRun ? yaw : null
+  }
+
   getPosition(): Vec3 {
     return this.position
   }
@@ -164,6 +194,10 @@ export class LocomotionController {
   update(dt: number): LocomotionPose {
     if (dt > 0.1) dt = 0.1 // tab-switch guard: never integrate a huge step
 
+    if (this.facingYaw !== null && this.strafeRun !== null && !this.tankMode) {
+      return this.updateStrafe(dt)
+    }
+
     const hasSprint = this.clips.sprint !== undefined
     let moving: boolean
     let align = 1
@@ -198,9 +232,11 @@ export class LocomotionController {
     }
 
     // Speed level ramps linearly toward the target; the pose blend follows it.
-    // (No sprint while backpedaling.)
+    // Input magnitude scales the target (analog sticks and arrival steering slow
+    // down instead of overshooting). No sprint while backpedaling.
     const sprinting = this.inputSprint && hasSprint && !(this.tankMode && this.inputForward < 0)
-    const target = moving ? (sprinting ? 2 : 1) : 0
+    const magnitude = this.tankMode ? Math.abs(this.inputForward) : Math.min(1, Math.hypot(this.inputX, this.inputY))
+    const target = moving ? (sprinting ? 2 : 1) * magnitude : 0
     const maxStep = this.speedResponse * dt
     const d = target - this.speedLevel
     this.speedLevel += Math.abs(d) <= maxStep ? d : Math.sign(d) * maxStep
@@ -251,4 +287,112 @@ export class LocomotionController {
     this.pose.speedLevel = this.speedLevel
     return this.pose
   }
+
+  /** The two ring clips straddling `local` (radians rel. facing), with the blend
+   *  fraction between them. The ring is sorted; the last→first gap wraps. */
+  private ringPair(ring: StrafeClipEntry[], local: number): { a: StrafeClipEntry; b: StrafeClipEntry; t: number } {
+    const n = ring.length
+    for (let i = 0; i < n; i++) {
+      const a = ring[i]
+      const b = ring[(i + 1) % n]
+      const gap = (((b.angle - a.angle) % TWO_PI) + TWO_PI) % TWO_PI || TWO_PI
+      const rel = (((local - a.angle) % TWO_PI) + TWO_PI) % TWO_PI
+      if (rel <= gap + 1e-9) return { a, b, t: rel / gap }
+    }
+    return { a: ring[0], b: ring[0], t: 0 }
+  }
+
+  /** Strafe-mode frame: the body holds facingYaw; movement blends the two ring clips
+   *  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(dt: number): LocomotionPose {
+    const runRing = this.strafeRun!
+    const sprintRing = this.strafeSprint
+
+    this.yaw = wrapAngle(this.yaw + wrapAngle(this.facingYaw! - this.yaw) * Math.min(1, this.turnResponse * dt))
+
+    const m = Math.hypot(this.inputX, this.inputY)
+    const moving = m > 0.05
+    const sprinting = this.inputSprint && sprintRing !== null
+    const target = moving ? (sprinting ? 2 : 1) * Math.min(1, m) : 0
+    const maxStep = this.speedResponse * dt
+    const d = target - this.speedLevel
+    this.speedLevel += Math.abs(d) <= maxStep ? d : Math.sign(d) * maxStep
+    const level = this.speedLevel
+
+    let runA = runRing[0]
+    let runB = runRing[0]
+    let runT = 0
+    let sprintA = sprintRing ? sprintRing[0] : runRing[0]
+    let sprintB = sprintA
+    let sprintT = 0
+    if (moving) {
+      const local = wrapAngle(Math.atan2(this.inputX, this.inputY) - this.yaw)
+      const rp = this.ringPair(runRing, local)
+      runA = rp.a
+      runB = rp.b
+      runT = rp.t
+      if (sprintRing) {
+        const sp = this.ringPair(sprintRing, local)
+        sprintA = sp.a
+        sprintB = sp.b
+        sprintT = sp.t
+      }
+      this.dirX = this.inputX / m
+      this.dirZ = this.inputY / m
+    }
+
+    // Root motion at the authored (angle-lerped, gear-lerped) clip speed.
+    const runSpeed = runA.speed + (runB.speed - runA.speed) * runT
+    const topSpeed = sprintRing ? sprintA.speed + (sprintB.speed - sprintA.speed) * sprintT : runSpeed
+    const speed = level <= 1 ? runSpeed * level : runSpeed + (topSpeed - runSpeed) * (level - 1)
+    this.position.x += this.dirX * speed * dt
+    this.position.z += this.dirZ * speed * dt
+
+    // Clocks: idle free-runs; the ring shares one phase (durations are uniform per gear).
+    const idleDur = this.clipDuration(this.clips.idle)
+    const runDur = this.clipDuration(runA.clip)
+    const sprintDur = sprintRing ? this.clipDuration(sprintA.clip) : runDur
+    this.idleTime = (this.idleTime + dt) % idleDur
+    const gaitDur = level <= 1 ? runDur : runDur + (sprintDur - runDur) * (level - 1)
+    this.gaitPhase = (this.gaitPhase + dt / gaitDur) % 1
+
+    let wIdle: number
+    let wRun: number
+    let wSprint: number
+    if (level <= 1) {
+      wIdle = 1 - level
+      wRun = level
+      wSprint = 0
+    } else {
+      wIdle = 0
+      wRun = 2 - level
+      wSprint = level - 1
+    }
+
+    const e = this.strafeEntries
+    e[0].name = this.clips.idle
+    e[0].time = this.idleTime
+    e[0].weight = wIdle
+    e[1].name = runA.clip
+    e[1].time = this.gaitPhase * runDur
+    e[1].weight = wRun * (1 - runT)
+    e[2].name = runB.clip
+    e[2].time = this.gaitPhase * runDur
+    e[2].weight = wRun * runT
+    e[3].name = sprintA.clip
+    e[3].time = this.gaitPhase * sprintDur
+    e[3].weight = wSprint * (1 - sprintT)
+    e[4].name = sprintB.clip
+    e[4].time = this.gaitPhase * sprintDur
+    e[4].weight = wSprint * sprintT
+    this.model.setBlendPose(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 = level
+    return this.pose
+  }
 }