reze-engine 0.36.0 → 0.37.0

package/src/model.ts

@@ -32,6 +32,10 @@ const _convMat = new Float32Array(16)
 // Blend-path scratch: per-entry sample target and the crossfade's two fixed entries.
 const _blendQ = new Quat(0, 0, 0, 1)
 const _blendT = new Vec3(0, 0, 0)
+
+// Bone-morph scratch: the weighted rotation, slerped out of identity.
+const _boneMorphQ = new Quat(0, 0, 0, 1)
+const _boneMorphIdentity = new Quat(0, 0, 0, 1)
 export interface ClipEventInfo {
   clip: string
   /** The registered event time, seconds. */
@@ -131,12 +135,56 @@ export interface GroupMorphReference {
   ratio: number
 }
 
+// Bone morph offset data (type 2). A stage's doors, platforms and hatches are
+// posed with these — there is no VMD to drive them, so the weight IS the pose.
+export interface BoneMorphOffset {
+  boneIndex: number
+  translation: [number, number, number]
+  /** Rotation quaternion (x, y, z, w). */
+  rotation: [number, number, number, number]
+}
+
+/** PMX material-morph blend mode. Multiply lerps toward base*morph; add offsets from base. */
+export const MATERIAL_MORPH_MULTIPLY = 0
+export const MATERIAL_MORPH_ADD = 1
+
+// Material morph offset data (type 8). Stage artists ship colour and on/off
+// switches this way: alpha to 0 hides a part, a diffuse tint recolours a set.
+export interface MaterialMorphOffset {
+  /** -1 targets EVERY material in the model, per the PMX spec. */
+  materialIndex: number
+  /** MATERIAL_MORPH_MULTIPLY | MATERIAL_MORPH_ADD */
+  offsetType: number
+  diffuse: [number, number, number, number]
+  specular: [number, number, number]
+  shininess: number
+  ambient: [number, number, number]
+  edgeColor: [number, number, number, number]
+  edgeSize: number
+  textureCoeff: [number, number, number, number]
+  sphereCoeff: [number, number, number, number]
+  toonCoeff: [number, number, number, number]
+}
+
+// UV morph offset data (types 3–7). Type 3 is the base UV channel; 4–7 are the
+// additional UV channels, which this engine does not carry — kept so the panel
+// can tell "unsupported" from "absent".
+export interface UvMorphOffset {
+  vertexIndex: number
+  /** (u, v, z, w) — only u/v apply to the base channel. */
+  offset: [number, number, number, number]
+}
+
 // Morph definition
 export interface Morph {
   name: string
-  type: number // 0=group, 1=vertex, 2=bone, 3=UV, 8=material
+  /** 0=group, 1=vertex, 2=bone, 3–7=UV, 8=material, 9=flip, 10=impulse. */
+  type: number
   vertexOffsets: VertexMorphOffset[] // Only for type 1 (vertex morph)
   groupReferences?: GroupMorphReference[] // Only for type 0 (group morph)
+  boneOffsets?: BoneMorphOffset[] // Only for type 2
+  materialOffsets?: MaterialMorphOffset[] // Only for type 8
+  uvOffsets?: UvMorphOffset[] // Only for types 3–7
 }
 
 export interface Morphing {
@@ -286,6 +334,24 @@ export class Model {
   private runtimeMorph!: MorphRuntime
   private morphsDirty: boolean = false // Flag indicating if morphs need to be applied
 
+  // Bone morphs (type 2), flattened once at load so the per-frame pass is a
+  // straight walk with no allocation. Empty for models without them, which is
+  // most characters — a stage's doors and platforms are the common case.
+  private boneMorphPlan: { morphIndex: number; boneIndex: number; translation: Vec3; rotation: Quat }[] = []
+  // Bones any bone morph touches, plus their locals as they were BEFORE the last
+  // application. A pose source rewrites the locals it owns every frame, but a
+  // stage usually has no clip at all — nothing would reset these, and the offset
+  // would compound frame after frame into a slow drift.
+  private boneMorphBones: number[] = []
+  private boneMorphRestoreR: Quat[] = []
+  private boneMorphRestoreT: Vec3[] = []
+  private boneMorphApplied = false
+  /** A full pose pass has run, so the world matrices are real. See isIdle. */
+  private posedOnce = false
+  // Set whenever effective weights change, for material/UV consumers that live
+  // outside this class. Vertex morphs use morphWeightsDirty (GPU) instead.
+  private auxMorphDirty = true
+
   // Root transform — model's placement in world space, independent of bones.
   // Folded into skin matrices (see getSkinMatrices) so every pass (main VS,
   // shadow VS, any future skinned pass) sees it without per-shader plumbing.
@@ -567,6 +633,119 @@ export class Model {
       }, {} as Record<string, number>),
       weights: new Float32Array(morphCount),
     }
+    const boneCount = this.skeleton.bones.length
+    this.boneMorphPlan = []
+    for (let i = 0; i < morphCount; i++) {
+      const morph = this.morphing.morphs[i]
+      if (morph.type !== 2 || !morph.boneOffsets) continue
+      for (const off of morph.boneOffsets) {
+        if (off.boneIndex < 0 || off.boneIndex >= boneCount) continue
+        this.boneMorphPlan.push({
+          morphIndex: i,
+          boneIndex: off.boneIndex,
+          translation: new Vec3(off.translation[0], off.translation[1], off.translation[2]),
+          rotation: new Quat(off.rotation[0], off.rotation[1], off.rotation[2], off.rotation[3]),
+        })
+      }
+    }
+    const touched = new Set(this.boneMorphPlan.map((e) => e.boneIndex))
+    this.boneMorphBones = [...touched]
+    this.boneMorphRestoreR = this.boneMorphBones.map(() => Quat.identity())
+    this.boneMorphRestoreT = this.boneMorphBones.map(() => Vec3.zeros())
+    this.boneMorphApplied = false
+  }
+
+  /**
+   * Bone morphs (type 2) compose over whatever the pose sources produced, the
+   * same way boneRotationOffsets do — they are an offset on the animated local
+   * transform, not a replacement for it. Re-applied every frame because each
+   * pose source rewrites the locals it touches.
+   *
+   * Stages are the reason this exists: a door or a lift is rigged as a bone
+   * morph and there is no VMD anywhere that drives it.
+   */
+  private applyBoneMorphs(): void {
+    if (this.boneMorphPlan.length === 0) return
+
+    // Undo the previous application first. With a clip running this is a no-op
+    // in effect — the pose source already overwrote these bones — but a stage
+    // has no clip, so without it the same offset would be re-added every frame.
+    if (this.boneMorphApplied) {
+      for (let i = 0; i < this.boneMorphBones.length; i++) {
+        const b = this.boneMorphBones[i]
+        this.runtimeSkeleton.localRotations[b].set(this.boneMorphRestoreR[i])
+        this.runtimeSkeleton.localTranslations[b].set(this.boneMorphRestoreT[i])
+      }
+    }
+    for (let i = 0; i < this.boneMorphBones.length; i++) {
+      const b = this.boneMorphBones[i]
+      this.boneMorphRestoreR[i].set(this.runtimeSkeleton.localRotations[b])
+      this.boneMorphRestoreT[i].set(this.runtimeSkeleton.localTranslations[b])
+    }
+    this.boneMorphApplied = true
+
+    const weights = this.getEffectiveMorphWeights()
+    for (const entry of this.boneMorphPlan) {
+      const w = weights[entry.morphIndex]
+      if (w < 0.0001) continue
+      const t = this.runtimeSkeleton.localTranslations[entry.boneIndex]
+      t.x += entry.translation.x * w
+      t.y += entry.translation.y * w
+      t.z += entry.translation.z * w
+      // Scale the rotation by weight the way MMD does — slerp out of identity,
+      // then compose. Multiplying components would not stay a unit quaternion.
+      const r = this.runtimeSkeleton.localRotations[entry.boneIndex]
+      Quat.slerpInto(_boneMorphIdentity, entry.rotation, w, _boneMorphQ)
+      Quat.multiplyInto(r, _boneMorphQ, r)
+    }
+  }
+
+  /** True (once) when effective morph weights changed — the engine re-derives
+   *  material-morph uniforms from it. Separate from the GPU vertex path's flag
+   *  so both can consume the same change. */
+  consumeAuxMorphDirty(): boolean {
+    const d = this.auxMorphDirty
+    this.auxMorphDirty = false
+    return d
+  }
+
+  /**
+   * Morph indices this model can actually act on, so a UI never offers a control
+   * that moves nothing.
+   *
+   * Driven directly: vertex (1), bone (2), material (8). Excluded: UV (3–7),
+   * which are parsed and kept but not yet applied; flip (9) and impulse (10),
+   * which are PMX 2.1 and would need the rigidbody solver.
+   *
+   * A group morph (0) is only as alive as what it points at — one referencing
+   * nothing but UV morphs is just as dead as the UV morphs themselves, so it is
+   * resolved rather than assumed.
+   */
+  getSupportedMorphIndices(): number[] {
+    const morphs = this.morphing.morphs
+    const drivable = (t: number) => t === 1 || t === 2 || t === 8
+    // Groups can reference groups, so walk with a seen-set rather than recursing.
+    const resolves = (start: number): boolean => {
+      const seen = new Set<number>()
+      const stack = [start]
+      while (stack.length > 0) {
+        const i = stack.pop()!
+        if (seen.has(i) || i < 0 || i >= morphs.length) continue
+        seen.add(i)
+        const m = morphs[i]
+        if (drivable(m.type)) return true
+        if (m.type === 0 && m.groupReferences) {
+          for (const ref of m.groupReferences) stack.push(ref.morphIndex)
+        }
+      }
+      return false
+    }
+    const out: number[] = []
+    for (let i = 0; i < morphs.length; i++) {
+      const t = morphs[i].type
+      if (drivable(t) || (t === 0 && resolves(i))) out.push(i)
+    }
+    return out
   }
 
   // Tween update - processes all tweens together with a single time reference
@@ -983,6 +1162,11 @@ export class Model {
       this.runtimeMorph.weights[idx] = clampedWeight
       this.tweenState.morphActive[idx] = 0
       this.applyMorphs()
+      // Vertex and material morphs are done by applyMorphs alone, but a bone
+      // morph lands in the pose pass — and a model with no clip (every stage)
+      // reports idle, so without this the pass never runs and the switch does
+      // nothing. Costs one redundant applyMorphs on the next frame.
+      if (this.boneMorphPlan.length > 0) this.morphsDirty = true
       try {
         Engine.getInstance().markVertexBufferDirty(this)
       } catch {
@@ -1047,6 +1231,11 @@ export class Model {
       effectiveWeights[i] = Math.max(0, Math.min(1, effectiveWeights[i]))
     }
 
+    // Bone morphs read these every frame, but material/UV consumers live outside
+    // this class and need telling. Set on BOTH paths — a model whose only morphs
+    // are material morphs never enables the GPU vertex path at all.
+    this.auxMorphDirty = true
+
     // GPU path: the compute pass applies the vertex offsets from these weights.
     if (this.gpuMorphEnabled) {
       this.morphWeightsDirty = true
@@ -1913,6 +2102,42 @@ export class Model {
   // within that. A host driving bones directly — motion capture writing FK
   // rotations every frame with no clip playing — turns it off wholesale, because
   // there is no motion present to carry the per-chain answer.
+  /**
+   * Nothing can have moved this frame: no clip, no blend, no live tween, no
+   * morph weight change.
+   *
+   * Environment geometry is in this state almost every frame, so the engine
+   * skips the whole pose pass — sampling, world matrices, and the skin-matrix
+   * upload — for a stage that reports idle. A stage is usually the heaviest mesh
+   * in the scene and the one that never moves; paying a full pose pass for it
+   * every frame is the thing worth not doing.
+   */
+  isIdle(): boolean {
+    // Never idle before the first pose pass. The constructor leaves the world
+    // matrices identity, so skin = world × inverseBind collapses every vertex
+    // into bone-local space — the mesh piles up at the origin. A cast member is
+    // saved by running update() on frame 1 regardless; a stage that reported
+    // idle immediately would render as a heap and never recover.
+    if (!this.posedOnce) return false
+    return (
+      !this.morphsDirty &&
+      this.oneShot === null &&
+      this.crossfade === null &&
+      (this.blendEntries === null || this.blendEntries.length === 0) &&
+      this.animationState.getCurrentClip() === null &&
+      !this.hasActiveTweens()
+    )
+  }
+
+  /** Any live rotation / translation / morph tween. */
+  private hasActiveTweens(): boolean {
+    const s = this.tweenState
+    for (let i = 0; i < s.rotActive.length; i++) if (s.rotActive[i] === 1) return true
+    for (let i = 0; i < s.transActive.length; i++) if (s.transActive[i] === 1) return true
+    for (let i = 0; i < s.morphActive.length; i++) if (s.morphActive[i] === 1) return true
+    return false
+  }
+
   update(deltaTime: number, ikEnabled = true): boolean {
     // Update tween time (in milliseconds)
     this.tweenTimeMs += deltaTime * 1000
@@ -1955,8 +2180,13 @@ export class Model {
       this.morphsDirty = false
     }
 
+    // After the pose sources and the constant offsets, before the world pass —
+    // bone morphs must survive into the world matrices IK then reads.
+    this.applyBoneMorphs()
+
     // Compute world matrices (needed for IK solving to read bone positions)
     this.computeWorldMatrices()
+    this.posedOnce = true
 
     // Solve IK chains (modifies localRotations with final IK rotations). Chains
     // the clip switched off are skipped inside.

package/src/physics/contact.ts

@@ -51,11 +51,18 @@ export interface Contact {
   cBxN: number; cByN: number; cBzN: number   // rB × n
   jacInvN: number
   bounceVel: number   // restitution reference, captured at setup from initial relVelN
-  /** Per-contact relaxation gain, 1/max(rows on A, rows on B). See CONTACT_SOR_MIN. */
-  sorGain: number
-  // Approach speed this row is allowed to leave alone: gap / dt for a
-  // speculative row, 0 once the shapes actually touch. See setupContactRow.
-  allowedApproachVel: number
+  /** Substeps this contact point has persisted (from the manifold cache).
+   *  Bullet kills restitution past m_restingContactRestitutionThreshold = 2. */
+  age: number
+  /** Penetration term routed to the SPLIT (pseudo-velocity) channel instead of
+   *  the real one, when the contact is deeper than the split threshold. */
+  rhsPenetration: number
+  /** Accumulated impulse on the split channel — Bullet's m_appliedPushImpulse. */
+  appliedPushImpulse: number
+  /** Baumgarte bias, depth·ERP/dt — Bullet 2.75's positionalError. Positive
+   *  when penetrating (pushes apart), negative when separated (allows the
+   *  approach that closes the gap). See CONTACT_ERP. */
+  biasVel: number
   // Friction tangent 1:
   t1x: number; t1y: number; t1z: number
   cAxT1: number; cAyT1: number; cAzT1: number
@@ -84,8 +91,10 @@ function makeContact(): Contact {
     cBxN: 0, cByN: 0, cBzN: 0,
     jacInvN: 0,
     bounceVel: 0,
-    sorGain: 1,
-    allowedApproachVel: 0,
+    age: 0,
+    rhsPenetration: 0,
+    appliedPushImpulse: 0,
+    biasVel: 0,
     t1x: 0, t1y: 0, t1z: 0,
     cAxT1: 0, cAyT1: 0, cAzT1: 0,
     cBxT1: 0, cByT1: 0, cBzT1: 0,
@@ -108,6 +117,7 @@ export class ContactPool {
       c.appliedNormalImpulse = 0
       c.appliedFrictionImpulse1 = 0
       c.appliedFrictionImpulse2 = 0
+      c.appliedPushImpulse = 0
       this.count++
       return c
     }

package/src/physics/manifold.ts

@@ -0,0 +1,151 @@
+// Persistent contact manifolds — the cache that makes warm starting possible.
+//
+// Bullet 2.75 keeps a btPersistentManifold per body pair holding up to 4 points,
+// each carrying the impulse it converged to last step. At setup the solver seeds
+// each row with `cp.m_appliedImpulse * m_warmstartingFactor` (0.85) and applies
+// it immediately, so a resting stack starts the substep already holding roughly
+// the load it needs instead of rediscovering it from zero every time.
+//
+// That is not a nicety here: penetration recovery rides in the contact velocity
+// row as a Baumgarte term, and a row rebuilt from zero each substep overshoots
+// it. Warm starting on its own was measured WORSE on this engine — but that was
+// against a solver with no bias term and a position-correction pass, which is a
+// different system. The two are one design in Bullet and are ported as one.
+//
+// Points are matched by proximity in each body's own local frame, which is what
+// btPersistentManifold does — a world-space match would drift with the body.
+
+const MAX_POINTS = 4
+/** Match radius, in model units. Bullet's gContactBreakingThreshold is 0.02;
+ *  ours is the contact margin, so a point that merely slid along a face is
+ *  still recognised as the same point rather than dropped and rebuilt. */
+const MATCH_DIST_SQ = 0.04 * 0.04
+
+interface Point {
+  /** Contact point in each body's local frame (lever arms are world-space and
+   *  rotate with the body, so they cannot be compared across substeps). */
+  lax: number; lay: number; laz: number
+  lbx: number; lby: number; lbz: number
+  normalImpulse: number
+  frictionImpulse1: number
+  frictionImpulse2: number
+  /** Substeps this point has survived — Bullet disables restitution past
+   *  m_restingContactRestitutionThreshold (2) so resting contacts stop bouncing. */
+  age: number
+  /** Marks points seen this substep; unseen ones are dropped. */
+  seen: boolean
+}
+
+export class ManifoldCache {
+  private pairs = new Map<number, Point[]>()
+  private touched = new Set<number>()
+
+  private static key(a: number, b: number): number {
+    return a < b ? a * 65536 + b : b * 65536 + a
+  }
+
+  /** Look up what this contact point converged to last substep. Returns null
+   *  when it is new. */
+  find(a: number, b: number, lax: number, lay: number, laz: number): Point | null {
+    const list = this.pairs.get(ManifoldCache.key(a, b))
+    if (list === undefined) return null
+    let best: Point | null = null
+    let bestD = MATCH_DIST_SQ
+    for (let i = 0; i < list.length; i++) {
+      const p = list[i]
+      const dx = p.lax - lax, dy = p.lay - lay, dz = p.laz - laz
+      const d = dx * dx + dy * dy + dz * dz
+      if (d < bestD) { bestD = d; best = p }
+    }
+    return best
+  }
+
+  /** Record what this point converged to, for the next substep to start from. */
+  store(
+    a: number, b: number,
+    lax: number, lay: number, laz: number,
+    lbx: number, lby: number, lbz: number,
+    normalImpulse: number, frictionImpulse1: number, frictionImpulse2: number,
+    age: number,
+  ): void {
+    const k = ManifoldCache.key(a, b)
+    this.touched.add(k)
+    let list = this.pairs.get(k)
+    if (list === undefined) { list = []; this.pairs.set(k, list) }
+    // Replace the nearest existing point, else append; past MAX_POINTS drop the
+    // shallowest-held one so the manifold keeps the load-bearing corners.
+    let best = -1
+    let bestD = MATCH_DIST_SQ
+    for (let i = 0; i < list.length; i++) {
+      const p = list[i]
+      const dx = p.lax - lax, dy = p.lay - lay, dz = p.laz - laz
+      const d = dx * dx + dy * dy + dz * dz
+      if (d < bestD) { bestD = d; best = i }
+    }
+    if (best < 0) {
+      if (list.length < MAX_POINTS) {
+        list.push({ lax, lay, laz, lbx, lby, lbz, normalImpulse, frictionImpulse1, frictionImpulse2, age, seen: true })
+        return
+      }
+      // btPersistentManifold::sortCachedPoints — when a 5th point arrives, drop
+      // whichever of the 5 leaves the largest quadrilateral. Area is what keeps
+      // a resting box from pivoting; dropping the shallowest instead can leave
+      // four nearly-collinear points that pin position but not orientation.
+      best = worstAreaIndex(list, lax, lay, laz)
+    }
+    const p = list[best]
+    p.lax = lax; p.lay = lay; p.laz = laz
+    p.lbx = lbx; p.lby = lby; p.lbz = lbz
+    p.normalImpulse = normalImpulse
+    p.frictionImpulse1 = frictionImpulse1
+    p.frictionImpulse2 = frictionImpulse2
+    p.age = age
+    p.seen = true
+  }
+
+  /** Drop every point not re-seen this substep, and every pair left empty.
+   *  Without this a separated pair keeps handing back a stale impulse. */
+  endStep(): void {
+    for (const [k, list] of this.pairs) {
+      if (!this.touched.has(k)) { this.pairs.delete(k); continue }
+      let w = 0
+      for (let i = 0; i < list.length; i++) {
+        const p = list[i]
+        if (!p.seen) continue
+        p.seen = false
+        list[w++] = p
+      }
+      list.length = w
+      if (w === 0) this.pairs.delete(k)
+    }
+    this.touched.clear()
+  }
+
+  clear(): void {
+    this.pairs.clear()
+    this.touched.clear()
+  }
+}
+
+
+/** Which of the 4 cached points to replace so the surviving quad keeps the most
+ *  area once the new point joins it. */
+function worstAreaIndex(list: Point[], nx: number, ny: number, nz: number): number {
+  let bestIdx = 0
+  let bestArea = -1
+  for (let drop = 0; drop < list.length; drop++) {
+    // The quad is: the new point plus the three survivors.
+    const pts: number[][] = [[nx, ny, nz]]
+    for (let i = 0; i < list.length; i++) if (i !== drop) pts.push([list[i].lax, list[i].lay, list[i].laz])
+    if (pts.length < 4) continue
+    // |d0 × d1| over the diagonals — Bullet's area proxy.
+    const d0x = pts[0][0] - pts[2][0], d0y = pts[0][1] - pts[2][1], d0z = pts[0][2] - pts[2][2]
+    const d1x = pts[1][0] - pts[3][0], d1y = pts[1][1] - pts[3][1], d1z = pts[1][2] - pts[3][2]
+    const cx = d0y * d1z - d0z * d1y
+    const cy = d0z * d1x - d0x * d1z
+    const cz = d0x * d1y - d0y * d1x
+    const area = cx * cx + cy * cy + cz * cz
+    if (area > bestArea) { bestArea = area; bestIdx = drop }
+  }
+  return bestIdx
+}