reze-engine 0.16.2 → 0.17.0

package/src/model.ts

@@ -43,6 +43,9 @@ export interface Material {
   sphereTextureIndex: number
   sphereMode: number
   toonTextureIndex: number
+  // True when toonTextureIndex refers to the shared toon set (toon01–10)
+  // instead of the model's texture table.
+  sharedToon: boolean
   edgeFlag: number
   edgeColor: [number, number, number, number]
   edgeSize: number
@@ -235,6 +238,9 @@ export class Model {
   private rigidbodies: Rigidbody[] = []
   private joints: Joint[] = []
 
+  // Non-fatal problems collected while parsing the PMX (see PmxLoader.warn).
+  private loadWarnings: string[] = []
+
   // Runtime skeleton pose state (updated each frame)
   private runtimeSkeleton!: SkeletonRuntime
 
@@ -293,7 +299,8 @@ export class Model {
     skinning: Skinning,
     morphing: Morphing,
     rigidbodies: Rigidbody[] = [],
-    joints: Joint[] = []
+    joints: Joint[] = [],
+    loadWarnings: string[] = []
   ) {
     // Store base vertex data (original positions before morphing)
     this.baseVertexData = new Float32Array(vertexData)
@@ -307,6 +314,7 @@ export class Model {
     this.morphing = morphing
     this.rigidbodies = rigidbodies
     this.joints = joints
+    this.loadWarnings = loadWarnings
 
     if (this.skeleton.bones.length == 0) {
       throw new Error("Model has no bones")
@@ -631,6 +639,18 @@ export class Model {
     return this.skinning
   }
 
+  // True when the PMX carried a usable rigidbody section. False means the
+  // model renders but has no physics — surface this in the UI instead of
+  // letting it read as "physics silently broken".
+  hasPhysicsData(): boolean {
+    return this.rigidbodies.length > 0
+  }
+
+  // Non-fatal PMX parse problems (truncated sections, suspicious counts…).
+  getLoadWarnings(): readonly string[] {
+    return this.loadWarnings
+  }
+
   getRigidbodies(): Rigidbody[] {
     return this.rigidbodies
   }

package/src/physics/body.ts

@@ -12,13 +12,20 @@ export class RigidBodyStore {
   readonly angularVelocities: Float32Array // 3*N
 
   readonly invMass: Float32Array // N (0 for static / kinematic)
-  // Scalar isotropic inverse inertia. The full 3×3 tensor would be more
-  // accurate but PMX shapes are roughly compact, and a single I⁻¹ is far
-  // better than reusing invMass (which under-rotates by 100–1000×).
-  readonly invInertia: Float32Array
+  // Full anisotropic inertia. Local diagonal (body frame, Bullet's shape
+  // formulas) plus the per-substep world tensor I⁻¹ = R·diag·Rᵀ (9 floats
+  // row-major, symmetric). The old scalar approximation deposited constraint
+  // impulses into rotational modes at the wrong rates on elongated capsules
+  // (5:1 skirt/hair bodies are ~25× anisotropic), leaving cloth with several
+  // times the kinetic energy real Bullet retains — visible as perpetual boil.
+  readonly invInertiaLocal: Float32Array // 3*N
+  readonly invInertiaWorld: Float32Array // 9*N
   readonly linearDamping: Float32Array
   readonly angularDamping: Float32Array
   readonly type: Uint8Array
+  // PMX mode-2 bodies: dynamic, but the bone takes rotation only and the
+  // body position re-pins to the animated bone each frame.
+  readonly aligned: Uint8Array
   readonly boneIndex: Int32Array
   readonly friction: Float32Array
   readonly restitution: Float32Array
@@ -55,10 +62,12 @@ export class RigidBodyStore {
     this.linearVelocities = new Float32Array(N * 3)
     this.angularVelocities = new Float32Array(N * 3)
     this.invMass = new Float32Array(N)
-    this.invInertia = new Float32Array(N)
+    this.invInertiaLocal = new Float32Array(N * 3)
+    this.invInertiaWorld = new Float32Array(N * 9)
     this.linearDamping = new Float32Array(N)
     this.angularDamping = new Float32Array(N)
     this.type = new Uint8Array(N)
+    this.aligned = new Uint8Array(N)
     this.boneIndex = new Int32Array(N)
     this.bodyOffsetMatrix = new Float32Array(N * 16)
     this.bodyOffsetInverse = new Float32Array(N * 16)
@@ -88,10 +97,11 @@ export class RigidBodyStore {
 
       const dynamic = rb.type === RigidbodyType.Dynamic && rb.mass > 0
       this.invMass[i] = dynamic ? 1 / rb.mass : 0
-      this.invInertia[i] = dynamic ? computeInvInertia(rb) : 0
+      if (dynamic) computeLocalInvInertia(rb, this.invInertiaLocal, i * 3)
       this.linearDamping[i] = rb.linearDamping
       this.angularDamping[i] = rb.angularDamping
       this.type[i] = rb.type
+      this.aligned[i] = rb.aligned ? 1 : 0
       this.boneIndex[i] = rb.boneIndex
       this.friction[i] = rb.friction
       this.restitution[i] = rb.restitution
@@ -104,6 +114,47 @@ export class RigidBodyStore {
     }
   }
 
+  // Refresh I⁻¹_world = R·diag(invInertiaLocal)·Rᵀ for every dynamic body.
+  // Called once per substep before constraint setup (orientations are
+  // constant during a solve).
+  updateInvInertiaWorld(): void {
+    const N = this.count
+    const ori = this.orientations
+    const local = this.invInertiaLocal
+    const W = this.invInertiaWorld
+    const invMass = this.invMass
+
+    for (let i = 0; i < N; i++) {
+      if (invMass[i] <= 0) continue
+      const i3 = i * 3
+      const i4 = i * 4
+      const i9 = i * 9
+      const qx = ori[i4 + 0], qy = ori[i4 + 1], qz = ori[i4 + 2], qw = ori[i4 + 3]
+      const x2 = qx + qx, y2 = qy + qy, z2 = qz + qz
+      const xx = qx * x2, yy = qy * y2, zz = qz * z2
+      const xy = qx * y2, xz = qx * z2, yz = qy * z2
+      const wx = qw * x2, wy = qw * y2, wz = qw * z2
+      // R columns (column-major rotation matrix)
+      const r00 = 1 - (yy + zz), r01 = xy - wz, r02 = xz + wy
+      const r10 = xy + wz, r11 = 1 - (xx + zz), r12 = yz - wx
+      const r20 = xz - wy, r21 = yz + wx, r22 = 1 - (xx + yy)
+      const d0 = local[i3 + 0], d1 = local[i3 + 1], d2 = local[i3 + 2]
+      // W = R·diag·Rᵀ (symmetric)
+      const a0 = r00 * d0, a1 = r01 * d1, a2 = r02 * d2
+      const b0 = r10 * d0, b1 = r11 * d1, b2 = r12 * d2
+      const c0 = r20 * d0, c1 = r21 * d1, c2 = r22 * d2
+      const w00 = a0 * r00 + a1 * r01 + a2 * r02
+      const w01 = a0 * r10 + a1 * r11 + a2 * r12
+      const w02 = a0 * r20 + a1 * r21 + a2 * r22
+      const w11 = b0 * r10 + b1 * r11 + b2 * r12
+      const w12 = b0 * r20 + b1 * r21 + b2 * r22
+      const w22 = c0 * r20 + c1 * r21 + c2 * r22
+      W[i9 + 0] = w00; W[i9 + 1] = w01; W[i9 + 2] = w02
+      W[i9 + 3] = w01; W[i9 + 4] = w11; W[i9 + 5] = w12
+      W[i9 + 6] = w02; W[i9 + 7] = w12; W[i9 + 8] = w22
+    }
+  }
+
   // World-space AABBs for every body. Inflated by margin so contacts stay
   // paired across small velocity jitter without recomputing per iteration.
   updateAabbs(margin = 0.5): void {
@@ -282,36 +333,48 @@ const _scratchA = new Float32Array(16)
 const _scratchB = new Float32Array(16)
 const _scratchC = new Float32Array(16)
 
-// Scalar isotropic inverse inertia. Returns 0 for static bodies (mass = 0).
-//   Sphere:  I = (2/5)·m·r²
-//   Box:     I = (1/3)·m·max(a,b,c)²
-//   Capsule: I = (1/12)·m·(3r² + h²)  (cylinder transverse axis)
-function computeInvInertia(rb: Rigidbody): number {
+// Diagonal local inverse inertia, matching Bullet's calculateLocalInertia
+// per shape (so behavior tracks Ammo-based MMD engines):
+//   Sphere:  I = (2/5)·m·r² on every axis
+//   Box:     Ix = m/12·(ly²+lz²), … with l = full extents (2·half)
+//   Capsule: Bullet's bounding-box approximation of the Y-axis capsule
+//            (lx = lz = 2r, ly = h + 2r)
+function computeLocalInvInertia(rb: Rigidbody, out: Float32Array, o: number): void {
   const m = rb.mass
-  if (m <= 0) return 0
-  let I: number
+  if (m <= 0) return
+  let Ix: number, Iy: number, Iz: number
   switch (rb.shape) {
     case RigidbodyShape.Sphere: {
-      const r = rb.size.x
-      I = 0.4 * m * r * r
+      const I = 0.4 * m * rb.size.x * rb.size.x
+      Ix = I; Iy = I; Iz = I
       break
     }
     case RigidbodyShape.Box: {
-      // Largest half-extent so the long axis isn't under-rotated.
-      const a = Math.max(rb.size.x, rb.size.y, rb.size.z)
-      I = (1 / 3) * m * a * a
+      const lx2 = 4 * rb.size.x * rb.size.x
+      const ly2 = 4 * rb.size.y * rb.size.y
+      const lz2 = 4 * rb.size.z * rb.size.z
+      Ix = (m / 12) * (ly2 + lz2)
+      Iy = (m / 12) * (lx2 + lz2)
+      Iz = (m / 12) * (lx2 + ly2)
       break
     }
     case RigidbodyShape.Capsule: {
-      const r = rb.size.x
-      const h = rb.size.y
-      I = (1 / 12) * m * (3 * r * r + h * h)
+      const lx = 2 * rb.size.x
+      const ly = rb.size.y + 2 * rb.size.x
+      const lx2 = lx * lx
+      const ly2 = ly * ly
+      Ix = (m / 12) * (ly2 + lx2)
+      Iy = (m / 12) * (lx2 + lx2)
+      Iz = (m / 12) * (lx2 + ly2)
       break
     }
-    default:
-      I = m
+    default: {
+      Ix = m; Iy = m; Iz = m
+    }
   }
-  return I > 0 ? 1 / I : 0
+  out[o + 0] = Ix > 0 ? 1 / Ix : 0
+  out[o + 1] = Iy > 0 ? 1 / Iy : 0
+  out[o + 2] = Iz > 0 ? 1 / Iz : 0
 }
 
 function identity16(out: Float32Array, offset: number): void {

package/src/physics/constraint.ts

@@ -1,5 +1,6 @@
 import { Mat4 } from "../math"
 import type { Joint, Rigidbody } from "./types"
+import { RigidbodyType } from "./types"
 
 // 6DOF spring constraint trimmed to what MMD uses. Connects bodyA and bodyB
 // via local-space anchor frames; at simulate time the world frames are
@@ -26,6 +27,11 @@ export interface SixDofSpringConstraint {
   springEnabled: Uint8Array     // length 6
   springStiffness: Float32Array // length 6 (k)
   equilibriumPoint: Float32Array// length 6, baked at setup time
+  // True for joints that close a cycle in the joint graph (e.g. the
+  // horizontal ring welds of cross-linked skirt lattices). Loop edges get
+  // reduced limit-correction rates in the solver — a cycle over-determines
+  // positions and full-rate corrections chatter (see LOOP_ERP_SCALE).
+  isLoop: boolean
 
   // Per-substep cache. Filled by solver's setup pass once before SI iters,
   // read by the velocity-only iter loop. None of these depend on lv/av — only
@@ -34,8 +40,8 @@ export interface SixDofSpringConstraint {
   cacheLeverA: Float32Array       // 3: rA = anchor − posA (world-space)
   cacheLeverB: Float32Array       // 3
   cacheLinAxes: Float32Array      // 9: 3 linear axes × xyz, world-space
-  cacheLinCrossA: Float32Array    // 9: (rA × ax) per axis
-  cacheLinCrossB: Float32Array    // 9
+  cacheLinCrossA: Float32Array    // 9: I⁻¹A·(rA × ax) per axis
+  cacheLinCrossB: Float32Array    // 9: I⁻¹B·(rB × ax) per axis
   cacheLinJacInv: Float32Array    // 3: 1/(im+im+cA²·ii+cB²·ii) per axis
   // Limit rows are unilateral (Bullet-style): the per-substep accumulated
   // impulse is clamped to the corrective sign, so a limit can push a body
@@ -45,24 +51,54 @@ export interface SixDofSpringConstraint {
   cacheLinActive: Uint8Array      // 3
   cacheLinLimitImp: Float32Array  // 3: accumulated limit impulse (per substep)
   // Spring rows are velocity-target drives; setup clamps k to the deadbeat
-  // stability bound so they cannot pump energy.
+  // stability bound so they cannot pump energy. maxImp bounds the per-substep
+  // accumulated impulse by the real spring force (k·|err|·dt) for rows that
+  // must stay force-limited (loop-edge welds); Infinity for authored springs.
   cacheLinSpringTarget: Float32Array // 3
+  cacheLinSpringMaxImp: Float32Array // 3
+  cacheLinSpringImp: Float32Array    // 3
   cacheLinSpringActive: Uint8Array   // 3
   cacheAngAxes: Float32Array      // 9 (spring rows)
   cacheAngTargetVel: Float32Array // 3 (spring rows)
   cacheAngActive: Uint8Array      // 3 (spring rows)
-  cacheAngJacInv: number          // 1 — same for all angular rows
+  // Per-axis angular Jacobians and tensor-multiplied axes: with full inertia
+  // tensors the effective mass differs per axis, and impulse application
+  // needs I⁻¹·axis per body.
+  cacheAngJacInv: Float32Array    // 3: 1/(axᵀ(I⁻¹A+I⁻¹B)ax) per axis
+  // Angular spring force clamp (|k·err|·dt) + per-substep accumulator —
+  // unclamped spring velocity-drives pump energy slowly (the restoring
+  // magnitude on derived euler axes is orientation-dependent by up to ~25%,
+  // and a mis-scaled oscillator restoring force injects per cycle).
+  cacheAngSpringMaxImp: Float32Array // 3
+  cacheAngSpringImp: Float32Array    // 3
+  cacheAngWA: Float32Array        // 9: I⁻¹A·axis per axis
+  cacheAngWB: Float32Array        // 9
   // Single geodesic limit row: shortest rotation from the current relative
   // orientation to the euler-clamped target. Per-axis euler limit rows are
   // geometrically inconsistent for large violations (asin singularity) and
   // pump energy instead of converging. Unilateral like the linear limits.
   cacheAngLimAxis: Float32Array   // 3, world-space unit axis
+  cacheAngLimWA: Float32Array     // 3: I⁻¹A·axis
+  cacheAngLimWB: Float32Array     // 3
+  cacheAngLimJacInv: number
   cacheAngLimTarget: number       // target relative angular velocity along axis
   cacheAngLimActive: number
   cacheAngLimImp: number          // accumulated impulse (per substep)
+  // Per-axis angular limit rows for the small-violation regime. act:
+  // 1 = bilateral (locked axis), 2 = unilateral stop (ranged axis) — a
+  // bilateral row on a ranged axis brakes natural recovery and pumps
+  // energy into swinging cloth.
+  cacheAngPATarget: Float32Array // 3
+  cacheAngPAActive: Uint8Array   // 3
+  cacheAngPAImp: Float32Array    // 3
 }
 
-export const STOP_ERP = 0.475
+// Stop-limit ERP. PMX rigs are tuned against MMD's stiff limit response;
+// lowering this makes cloth resting against its limits sink visibly deeper
+// (equilibrium penetration scales with 1/ERP). Rest chatter at this
+// stiffness was fixed at the source (spring double-drive, unilateral
+// stops) — don't lower ERP to paper over jitter.
+export const STOP_ERP = 0.45
 
 // Build per-joint constraints from PMX data:
 //   frameA = (bodyA_worldBind)^-1 · jointWorldBind
@@ -136,6 +172,7 @@ export function buildConstraints(
       springEnabled,
       springStiffness,
       equilibriumPoint: new Float32Array(6),
+      isLoop: false,
       cacheSkip: false,
       cacheLeverA: new Float32Array(3),
       cacheLeverB: new Float32Array(3),
@@ -147,18 +184,55 @@ export function buildConstraints(
       cacheLinActive: new Uint8Array(3),
       cacheLinLimitImp: new Float32Array(3),
       cacheLinSpringTarget: new Float32Array(3),
+      cacheLinSpringMaxImp: new Float32Array(3),
+      cacheLinSpringImp: new Float32Array(3),
       cacheLinSpringActive: new Uint8Array(3),
       cacheAngAxes: new Float32Array(9),
       cacheAngTargetVel: new Float32Array(3),
       cacheAngActive: new Uint8Array(3),
-      cacheAngJacInv: 0,
+      cacheAngJacInv: new Float32Array(3),
+      cacheAngSpringMaxImp: new Float32Array(3),
+      cacheAngSpringImp: new Float32Array(3),
+      cacheAngWA: new Float32Array(9),
+      cacheAngWB: new Float32Array(9),
       cacheAngLimAxis: new Float32Array(3),
+      cacheAngLimWA: new Float32Array(3),
+      cacheAngLimWB: new Float32Array(3),
+      cacheAngLimJacInv: 0,
       cacheAngLimTarget: 0,
       cacheAngLimActive: 0,
       cacheAngLimImp: 0,
+      cacheAngPATarget: new Float32Array(3),
+      cacheAngPAActive: new Uint8Array(3),
+      cacheAngPAImp: new Float32Array(3),
     })
   }
 
+  // Mark loop-closing joints via union-find over the joint graph. All
+  // bone-follow bodies count as one "world" component (they're each anchored
+  // to the skeleton), so a joint bridging two separately anchored subtrees
+  // also closes a kinematic cycle. One edge per cycle gets softened, which
+  // releases the over-determination regardless of which edge it is.
+  const parent = new Int32Array(rigidbodies.length + 1)
+  for (let i = 0; i < parent.length; i++) parent[i] = i
+  const find = (x: number): number => {
+    while (parent[x] !== x) {
+      parent[x] = parent[parent[x]]
+      x = parent[x]
+    }
+    return x
+  }
+  const world = rigidbodies.length
+  for (let i = 0; i < rigidbodies.length; i++) {
+    if (rigidbodies[i].type !== RigidbodyType.Dynamic) parent[find(i)] = find(world)
+  }
+  for (const con of out) {
+    const ra = find(con.bodyA)
+    const rb = find(con.bodyB)
+    if (ra === rb) con.isLoop = true
+    else parent[ra] = rb
+  }
+
   return out
 }
 

package/src/physics/physics.ts

@@ -50,6 +50,15 @@ export class RezePhysics {
   private kinRoot: Int32Array
   // Kinematic bodies whose target jumped discontinuously this frame.
   private teleportFlags: Uint8Array
+  // PMX mode-2 bodies jointed *directly* to a bone-follow body (breasts,
+  // chain roots). Only these get MMD's bone-position alignment: their bone's
+  // animated matrix is trustworthy, whereas deeper chain bones' animated
+  // matrices don't include the physics deflection of their parents, so
+  // pinning those would freeze the chain.
+  private alignPinned: Uint8Array
+  // Debug counter: frames on which a teleport (scrub/jump discontinuity)
+  // was detected and settled.
+  teleportCount = 0
 
   constructor(rigidbodies: Rigidbody[], joints: Joint[] = []) {
     this.rigidbodies = rigidbodies
@@ -66,6 +75,17 @@ export class RezePhysics {
     this.kinTargetAngVel = new Float32Array(this.store.count * 3)
     this.kinRoot = this.buildKinematicRoots()
     this.teleportFlags = new Uint8Array(this.store.count)
+
+    this.alignPinned = new Uint8Array(this.store.count)
+    const types = this.store.type
+    for (const c of this.constraints) {
+      const tA = types[c.bodyA]
+      const tB = types[c.bodyB]
+      const aFollows = tA === RigidbodyType.Static || tA === RigidbodyType.Kinematic
+      const bFollows = tB === RigidbodyType.Static || tB === RigidbodyType.Kinematic
+      if (aFollows && this.store.aligned[c.bodyB]) this.alignPinned[c.bodyB] = 1
+      if (bFollows && this.store.aligned[c.bodyA]) this.alignPinned[c.bodyA] = 1
+    }
   }
 
   // BFS over the joint graph from every kinematic body, assigning each
@@ -140,6 +160,13 @@ export class RezePhysics {
     if (this.firstFrame) return
     this.snapBodiesToBones(boneWorldMatrices)
     this.savePrevState() // prev == curr after a snap, so no interpolation jump
+    // Reseed kinematic targets from the snapped pose — otherwise the next
+    // step derives the target-trajectory velocity against the pre-reset
+    // targets and feeds one frame of enormous anchor velocity to the solver.
+    this.kinTargetPos.set(this.store.positions)
+    this.kinTargetOri.set(this.store.orientations)
+    this.kinTargetVel.fill(0)
+    this.kinTargetAngVel.fill(0)
     this.timeAccum = 0
   }
 
@@ -165,6 +192,7 @@ export class RezePhysics {
     // raw derived velocity is what used to explode the solver. Chains under
     // unaffected roots keep their momentum untouched.
     if (this.computeKinematicTargets(boneWorldMatrices, dt)) {
+      this.teleportCount++
       this.carryDynamicThroughTeleport()
       this.snapKinematicToTargets(true)
       this.savePrevState() // prev == curr so interpolation doesn't streak
@@ -197,6 +225,10 @@ export class RezePhysics {
       this.snapKinematicToTargets(false)
     }
 
+    // MMD mode-2 bone alignment for pinned (depth-1) bodies: position
+    // re-pins to the animated bone, rotation stays simulated.
+    this.alignPinnedBodiesToBones(boneWorldMatrices)
+
     // Fraction into the next (not-yet-taken) step; always in [0, 1).
     const alpha = this.fixedTimeStep > 0 ? this.timeAccum / this.fixedTimeStep : 0
     this.applyDynamicsToBones(boneWorldMatrices, alpha)
@@ -500,6 +532,32 @@ export class RezePhysics {
     }
   }
 
+  // Overwrite pinned mode-2 bodies' positions with boneWorld × bodyOffset
+  // from the animated bone pose, keeping simulated orientation and
+  // velocities. prevPositions follows so interpolation doesn't streak.
+  private alignPinnedBodiesToBones(boneWorldMatrices: Mat4[]): void {
+    const N = this.store.count
+    const pinned = this.alignPinned
+    const boneIdx = this.store.boneIndex
+    const offsets = this.store.bodyOffsetMatrix
+    const positions = this.store.positions
+    const prevPos = this.prevPositions
+
+    for (let i = 0; i < N; i++) {
+      if (!pinned[i]) continue
+      const b = boneIdx[i]
+      if (b < 0 || b >= boneWorldMatrices.length) continue
+      Mat4.multiplyArrays(boneWorldMatrices[b].values, 0, offsets, i * 16, _bodyMat, 0)
+      const i3 = i * 3
+      positions[i3 + 0] = _bodyMat[12]
+      positions[i3 + 1] = _bodyMat[13]
+      positions[i3 + 2] = _bodyMat[14]
+      prevPos[i3 + 0] = _bodyMat[12]
+      prevPos[i3 + 1] = _bodyMat[13]
+      prevPos[i3 + 2] = _bodyMat[14]
+    }
+  }
+
   // Backstop: if a dynamic body's state went non-finite despite the velocity
   // caps, restore its previous-substep pose with zero velocity instead of
   // letting NaNs spread through constraints and contacts. Runs after every
@@ -589,7 +647,16 @@ export class RezePhysics {
 
       // Sanity gate against NaN / extreme values — silently drop the update.
       if (Number.isFinite(_boneMat[0]) && Math.abs(_boneMat[0]) < 1e6) {
-        boneWorldMatrices[b].values.set(_boneMat)
+        const v = boneWorldMatrices[b].values
+        if (this.alignPinned[i]) {
+          // Pinned mode-2: the bone keeps its animated position, physics
+          // drives rotation only.
+          v[0] = _boneMat[0]; v[1] = _boneMat[1]; v[2] = _boneMat[2]
+          v[4] = _boneMat[4]; v[5] = _boneMat[5]; v[6] = _boneMat[6]
+          v[8] = _boneMat[8]; v[9] = _boneMat[9]; v[10] = _boneMat[10]
+        } else {
+          v.set(_boneMat)
+        }
       }
     }
   }