reze-engine 0.15.0 → 0.16.0

package/src/model.ts

@@ -19,6 +19,14 @@ import {
 
 const VERTEX_STRIDE = 8
 
+// Animation-sampling scratch (applyPoseFromClip → convertVMDTranslationToLocal). These
+// run sequentially and are not reentrant with the world-matrix scratch in math.ts, so
+// plain module singletons are safe and let the per-bone sample path allocate nothing.
+const _animSlerp = new Quat(0, 0, 0, 1)
+const _animInterpT = new Vec3(0, 0, 0)
+const _convOut = new Vec3(0, 0, 0)
+const _convMat = new Float32Array(16)
+
 export interface Texture {
   path: string
   name: string
@@ -112,7 +120,17 @@ export interface Morph {
 
 export interface Morphing {
   morphs: Morph[]
-  offsetsBuffer: Float32Array // Dense buffer: morphCount * vertexCount * 3 floats
+}
+
+// CSR inversion of vertex-morph offsets for the GPU compute pass (built once at load).
+export interface MorphComputeData {
+  basePositions: Float32Array // vertexCount * 3
+  rowStart: Uint32Array // vertexCount + 1 (prefix offsets into the entry arrays)
+  colMorph: Uint32Array // entryCount (morph index per entry)
+  colOffset: Float32Array // entryCount * 3 (xyz offset per entry)
+  morphCount: number
+  vertexCount: number
+  entryCount: number
 }
 
 // Runtime skeleton pose state (updated each frame)
@@ -192,6 +210,18 @@ export class Model {
   private baseVertexData: Float32Array<ArrayBuffer> // Original vertex data before morphing
   private vertexCount: number
   private indexData: Uint32Array<ArrayBuffer>
+
+  // Morph state reused across frames (S1) + partial vertex-upload range tracking (S2, CPU path).
+  private morphEffectiveWeights?: Float32Array
+  private morphPrevMinVert = -1 // vertices touched by last applyMorphs (reset to base this pass)
+  private morphPrevMaxVert = -1
+  private morphPendingMinVert = -1 // accumulated range awaiting a GPU upload
+  private morphPendingMaxVert = -1
+  private morphUploadFull = true // first upload after load pushes the whole buffer once
+  // GPU morph path: when enabled (engine set up the compute buffers), applyMorphs only
+  // resolves effective weights and flags them dirty — the compute pass does the vertex work.
+  private gpuMorphEnabled = false
+  private morphWeightsDirty = false
   private textures: Texture[] = []
   private materials: Material[] = []
   // Static skeleton/skinning (not necessarily serialized yet)
@@ -225,6 +255,17 @@ export class Model {
   // Cached skin matrices array to avoid allocations in getSkinMatrices
   private skinMatricesArray?: Float32Array
 
+  // Static bone traversal order (parents before children), precomputed once at load.
+  // computeWorldMatrices replays this flat instead of recursing with a per-call
+  // visited-array + closure. Order depends only on parentIndex (static), so this
+  // reproduces the old recursion's finishing order exactly. See buildDeformOrder.
+  private deformOrder!: Int32Array
+
+  // Bind-pose absolute (world) position per bone, xyz packed. Static (bindTranslation
+  // accumulated down the hierarchy). Precomputed once so convertVMDTranslationToLocal
+  // stops re-deriving it recursively (with per-ancestor allocations) every frame.
+  private bindWorldPos!: Float32Array
+
   private tweenState!: TweenState
   private tweenTimeMs: number = 0 // Time tracking for tweens (milliseconds)
 
@@ -338,6 +379,59 @@ export class Model {
 
     this.runtimeSkeleton.ikChainInfo = ikChainInfo
     this.runtimeSkeleton.ikSolvers = ikSolvers
+
+    this.buildDeformOrder()
+  }
+
+  // Precompute the bone order that computeWorldMatrices iterates every frame: every
+  // bone appears after its parent. This is the exact finishing order the previous
+  // recursive computeWorld() produced (walk up the not-yet-emitted ancestor chain,
+  // then emit it top-down; ties broken by ascending index) — so behavior is identical,
+  // minus the per-frame closure + visited-array allocation and the recursion overhead.
+  private buildDeformOrder(): void {
+    const bones = this.skeleton.bones
+    const n = bones.length
+    const order = new Int32Array(n)
+    const done = new Uint8Array(n)
+    const stack: number[] = []
+    let k = 0
+    for (let i = 0; i < n; i++) {
+      if (done[i]) continue
+      stack.length = 0
+      let cur = i
+      // Collect the chain of not-yet-emitted ancestors up to the root (or a done one).
+      while (cur >= 0 && cur < n && !done[cur]) {
+        stack.push(cur)
+        cur = bones[cur].parentIndex
+      }
+      // Emit from the topmost ancestor down so parents precede children.
+      for (let s = stack.length - 1; s >= 0; s--) {
+        const b = stack[s]
+        done[b] = 1
+        order[k++] = b
+      }
+    }
+    this.deformOrder = order
+
+    // Accumulate bind-pose world positions in the same parent-before-child order and
+    // with the same add order as the old recursive computeBindPoseWorldPosition, so the
+    // downstream arithmetic stays bit-identical.
+    const bindWorld = new Float32Array(n * 3)
+    for (let idx = 0; idx < n; idx++) {
+      const i = order[idx]
+      const bt = bones[i].bindTranslation
+      const p = bones[i].parentIndex
+      if (p >= 0 && p < n) {
+        bindWorld[i * 3 + 0] = bindWorld[p * 3 + 0] + bt[0]
+        bindWorld[i * 3 + 1] = bindWorld[p * 3 + 1] + bt[1]
+        bindWorld[i * 3 + 2] = bindWorld[p * 3 + 2] + bt[2]
+      } else {
+        bindWorld[i * 3 + 0] = bt[0]
+        bindWorld[i * 3 + 1] = bt[1]
+        bindWorld[i * 3 + 2] = bt[2]
+      }
+    }
+    this.bindWorldPos = bindWorld
   }
 
   private initializeTweenBuffers(): void {
@@ -659,63 +753,49 @@ export class Model {
   }
 
   // VMD translation (world delta from bind pose) → bone local space; optional rotation for animation vs IK
+  // Returns a REUSED scratch Vec3 (_convOut) — callers must copy immediately (they do:
+  // .set() / destructure). Zero allocation; result is bit-identical to the previous
+  // recursive implementation (verified numerically).
   private convertVMDTranslationToLocal(boneIdx: number, vmdRelativeTranslation: Vec3, rotation?: Quat): Vec3 {
-    const skeleton = this.skeleton
-    const bones = skeleton.bones
-    const localRot = this.runtimeSkeleton.localRotations
-
-    // Compute bind pose world positions for all bones
-    const computeBindPoseWorldPosition = (idx: number): Vec3 => {
-      const bone = bones[idx]
-      const bindPos = new Vec3(bone.bindTranslation[0], bone.bindTranslation[1], bone.bindTranslation[2])
-      if (bone.parentIndex >= 0 && bone.parentIndex < bones.length) {
-        const parentWorldPos = computeBindPoseWorldPosition(bone.parentIndex)
-        return parentWorldPos.add(bindPos)
-      } else {
-        return bindPos
-      }
-    }
-
-    const bone = bones[boneIdx]
-
-    // VMD translation is relative to bind pose world position
-    // targetWorldPos = bindPoseWorldPos + vmdRelativeTranslation
-    const bindPoseWorldPos = computeBindPoseWorldPosition(boneIdx)
-    const targetWorldPos = bindPoseWorldPos.add(vmdRelativeTranslation)
-
-    // Convert target world position to local translation
-    // We need parent's bind pose world position to transform to parent space
-    let parentBindPoseWorldPos: Vec3
-    if (bone.parentIndex >= 0) {
-      parentBindPoseWorldPos = computeBindPoseWorldPosition(bone.parentIndex)
+    const bone = this.skeleton.bones[boneIdx]
+    const bindWorld = this.bindWorldPos
+    const bt = bone.bindTranslation
+    const p = bone.parentIndex
+
+    // afterBindTranslation = (bindWorld[bone] + vmd − bindWorld[parent]) − bindTranslation.
+    // (Algebraically this reduces to vmd, since bindWorld[bone] = bindWorld[parent] +
+    // bindTranslation, but the explicit form keeps the result bit-identical to before.)
+    const bi3 = boneIdx * 3
+    const targetX = bindWorld[bi3 + 0] + vmdRelativeTranslation.x
+    const targetY = bindWorld[bi3 + 1] + vmdRelativeTranslation.y
+    const targetZ = bindWorld[bi3 + 2] + vmdRelativeTranslation.z
+    const px = p >= 0 ? bindWorld[p * 3 + 0] : 0
+    const py = p >= 0 ? bindWorld[p * 3 + 1] : 0
+    const pz = p >= 0 ? bindWorld[p * 3 + 2] : 0
+    const abx = targetX - px - bt[0]
+    const aby = targetY - py - bt[1]
+    const abz = targetZ - pz - bt[2]
+
+    // Inverse rotation = conjugate + normalize (matches localRotation.clone().conjugate()
+    // .normalize()), applied via a rotation matrix (matches Mat4.fromQuat). Uses animation
+    // rotation when provided so IK-modified localRot doesn't perturb the conversion.
+    const q = rotation ?? this.runtimeSkeleton.localRotations[boneIdx]
+    const qlen = Math.sqrt(q.x * q.x + q.y * q.y + q.z * q.z + q.w * q.w)
+    let ix: number, iy: number, iz: number, iw: number
+    if (qlen === 0) {
+      ix = 0; iy = 0; iz = 0; iw = 1
     } else {
-      parentBindPoseWorldPos = Vec3.zeros()
+      const inv = 1 / qlen
+      ix = -q.x * inv; iy = -q.y * inv; iz = -q.z * inv; iw = q.w * inv
     }
-
-    // Transform target world position to parent's local space
-    // In bind pose, parent's world matrix is just a translation
-    const parentSpacePos = targetWorldPos.subtract(parentBindPoseWorldPos)
-
-    // Subtract bindTranslation to get position after bind translation
-    const afterBindTranslation = parentSpacePos.subtract(
-      new Vec3(bone.bindTranslation[0], bone.bindTranslation[1], bone.bindTranslation[2])
-    )
-
-    // Apply inverse rotation to get local translation
-    // Use provided rotation (animation rotation) or fall back to current localRotation
-    // Using animation rotation prevents conflicts when IK modifies the rotation
-    const localRotation = rotation ?? localRot[boneIdx]
-    // Clone to avoid mutating, then conjugate and normalize
-    const invRotation = localRotation.clone().conjugate().normalize()
-    const rotationMat = Mat4.fromQuat(invRotation.x, invRotation.y, invRotation.z, invRotation.w)
-    const rm = rotationMat.values
-    const localTranslation = new Vec3(
-      rm[0] * afterBindTranslation.x + rm[4] * afterBindTranslation.y + rm[8] * afterBindTranslation.z,
-      rm[1] * afterBindTranslation.x + rm[5] * afterBindTranslation.y + rm[9] * afterBindTranslation.z,
-      rm[2] * afterBindTranslation.x + rm[6] * afterBindTranslation.y + rm[10] * afterBindTranslation.z
+    Mat4.fromQuatInto(ix, iy, iz, iw, _convMat, 0)
+    const rm = _convMat
+    _convOut.setXYZ(
+      rm[0] * abx + rm[4] * aby + rm[8] * abz,
+      rm[1] * abx + rm[5] * aby + rm[9] * abz,
+      rm[2] * abx + rm[6] * aby + rm[10] * abz
     )
-
-    return localTranslation
+    return _convOut
   }
 
   getWorldMatrices(): Mat4[] {
@@ -826,15 +906,16 @@ export class Model {
   }
 
   private applyMorphs(): void {
-    // Reset vertex data to base positions
-    this.vertexData.set(this.baseVertexData)
-
     const vertexCount = this.vertexCount
     const morphCount = this.morphing.morphs.length
     const weights = this.runtimeMorph.weights
 
-    // First pass: Compute effective weights for all morphs (handling group morphs)
-    const effectiveWeights = new Float32Array(morphCount)
+    // Effective weights (group-morph resolution + clamp). Both paths need these: the GPU
+    // path uploads them for the compute pass; the CPU path applies them below. Reused buffer.
+    if (!this.morphEffectiveWeights || this.morphEffectiveWeights.length !== morphCount) {
+      this.morphEffectiveWeights = new Float32Array(morphCount)
+    }
+    const effectiveWeights = this.morphEffectiveWeights
     effectiveWeights.set(weights) // Start with direct weights
 
     // Apply group morphs: group morph weight * ratio affects referenced morphs
@@ -845,20 +926,33 @@ export class Model {
         if (groupWeight > 0.0001) {
           for (const ref of morph.groupReferences) {
             if (ref.morphIndex >= 0 && ref.morphIndex < morphCount) {
-              // Add group morph's contribution to the referenced morph
               effectiveWeights[ref.morphIndex] += groupWeight * ref.ratio
             }
           }
         }
       }
     }
-
-    // Clamp effective weights to [0, 1]
     for (let i = 0; i < morphCount; i++) {
       effectiveWeights[i] = Math.max(0, Math.min(1, effectiveWeights[i]))
     }
 
-    // Second pass: Apply vertex morphs with their effective weights
+    // GPU path: the compute pass applies the vertex offsets from these weights.
+    if (this.gpuMorphEnabled) {
+      this.morphWeightsDirty = true
+      return
+    }
+
+    // ── CPU path ── Reset only the vertices morphed by the previous pass back to base
+    // (targeted reset; vertexData never diverges from base outside that range).
+    if (this.morphPrevMaxVert >= 0) {
+      const s = this.morphPrevMinVert * VERTEX_STRIDE
+      const e = (this.morphPrevMaxVert + 1) * VERTEX_STRIDE
+      this.vertexData.set(this.baseVertexData.subarray(s, e), s)
+    }
+
+    // Apply vertex morphs, tracking the touched vertex-index range for partial upload.
+    let curMinVert = -1
+    let curMaxVert = -1
     for (let morphIdx = 0; morphIdx < morphCount; morphIdx++) {
       const effectiveWeight = effectiveWeights[morphIdx]
       if (effectiveWeight === 0 || effectiveWeight < 0.0001) continue
@@ -866,28 +960,140 @@ export class Model {
       const morph = this.morphing.morphs[morphIdx]
       if (morph.type !== 1) continue // Only process vertex morphs
 
-      // For vertex morphs, iterate through vertices that have offsets
       for (const vertexOffset of morph.vertexOffsets) {
         const vIdx = vertexOffset.vertexIndex
         if (vIdx < 0 || vIdx >= vertexCount) continue
 
-        // Get morph offset for this vertex
         const offsetX = vertexOffset.positionOffset[0]
         const offsetY = vertexOffset.positionOffset[1]
         const offsetZ = vertexOffset.positionOffset[2]
-
-        // Skip if offset is zero
         if (Math.abs(offsetX) < 0.0001 && Math.abs(offsetY) < 0.0001 && Math.abs(offsetZ) < 0.0001) {
           continue
         }
 
-        // Apply weighted offset to vertex position (positions are at stride 0, 8, 16, ...)
         const vertexIdx = vIdx * VERTEX_STRIDE
         this.vertexData[vertexIdx] += offsetX * effectiveWeight
         this.vertexData[vertexIdx + 1] += offsetY * effectiveWeight
         this.vertexData[vertexIdx + 2] += offsetZ * effectiveWeight
+
+        if (curMinVert < 0 || vIdx < curMinVert) curMinVert = vIdx
+        if (vIdx > curMaxVert) curMaxVert = vIdx
+      }
+    }
+
+    let dirtyMin = curMinVert
+    let dirtyMax = curMaxVert
+    if (this.morphPrevMaxVert >= 0) {
+      if (dirtyMin < 0 || this.morphPrevMinVert < dirtyMin) dirtyMin = this.morphPrevMinVert
+      if (this.morphPrevMaxVert > dirtyMax) dirtyMax = this.morphPrevMaxVert
+    }
+    if (dirtyMin >= 0 && dirtyMax >= 0) {
+      this.morphPendingMinVert =
+        this.morphPendingMinVert < 0 ? dirtyMin : Math.min(this.morphPendingMinVert, dirtyMin)
+      this.morphPendingMaxVert =
+        this.morphPendingMaxVert < 0 ? dirtyMax : Math.max(this.morphPendingMaxVert, dirtyMax)
+    }
+    this.morphPrevMinVert = curMinVert
+    this.morphPrevMaxVert = curMaxVert
+  }
+
+  // ── GPU morph path support ──
+  // Called by the engine once it has created the compute buffers for this model; switches
+  // applyMorphs to the weights-only branch.
+  enableGpuMorphs(): void {
+    this.gpuMorphEnabled = true
+  }
+
+  // True (once) when morph weights changed since the last check — the engine then uploads
+  // getEffectiveMorphWeights() and dispatches the compute pass.
+  consumeMorphWeightsDirty(): boolean {
+    const d = this.morphWeightsDirty
+    this.morphWeightsDirty = false
+    return d
+  }
+
+  // Effective (group-resolved, clamped) morph weights for GPU upload. Ensures they're
+  // computed at least once even before the first weight change.
+  getEffectiveMorphWeights(): Float32Array {
+    if (!this.morphEffectiveWeights) this.applyMorphs()
+    return this.morphEffectiveWeights ?? new Float32Array(0)
+  }
+
+  // Build the CSR inversion of vertex-morph offsets for the GPU compute pass. Returns null
+  // when the model has no vertex-morph offsets (no GPU path needed). Entries for each vertex
+  // are emitted in ascending morph-index order, matching the CPU accumulation order.
+  buildMorphComputeData(): MorphComputeData | null {
+    const V = this.vertexCount
+    const M = this.morphing.morphs.length
+    const morphs = this.morphing.morphs
+    const EPS = 0.0001
+
+    const isLive = (o: VertexMorphOffset): boolean =>
+      o.vertexIndex >= 0 &&
+      o.vertexIndex < V &&
+      (Math.abs(o.positionOffset[0]) >= EPS ||
+        Math.abs(o.positionOffset[1]) >= EPS ||
+        Math.abs(o.positionOffset[2]) >= EPS)
+
+    const counts = new Uint32Array(V)
+    for (let m = 0; m < M; m++) {
+      const morph = morphs[m]
+      if (morph.type !== 1) continue
+      for (const o of morph.vertexOffsets) if (isLive(o)) counts[o.vertexIndex]++
+    }
+
+    const rowStart = new Uint32Array(V + 1)
+    let acc = 0
+    for (let v = 0; v < V; v++) {
+      rowStart[v] = acc
+      acc += counts[v]
+    }
+    rowStart[V] = acc
+    const E = acc
+    if (E === 0) return null
+
+    const colMorph = new Uint32Array(E)
+    const colOffset = new Float32Array(E * 3)
+    const fill = new Uint32Array(V)
+    for (let m = 0; m < M; m++) {
+      const morph = morphs[m]
+      if (morph.type !== 1) continue
+      for (const o of morph.vertexOffsets) {
+        if (!isLive(o)) continue
+        const v = o.vertexIndex
+        const p = rowStart[v] + fill[v]++
+        colMorph[p] = m
+        colOffset[p * 3] = o.positionOffset[0]
+        colOffset[p * 3 + 1] = o.positionOffset[1]
+        colOffset[p * 3 + 2] = o.positionOffset[2]
       }
     }
+
+    const basePositions = new Float32Array(V * 3)
+    for (let v = 0; v < V; v++) {
+      const vi = v * VERTEX_STRIDE
+      basePositions[v * 3] = this.baseVertexData[vi]
+      basePositions[v * 3 + 1] = this.baseVertexData[vi + 1]
+      basePositions[v * 3 + 2] = this.baseVertexData[vi + 2]
+    }
+
+    return { basePositions, rowStart, colMorph, colOffset, morphCount: M, vertexCount: V, entryCount: E }
+  }
+
+  // Consume the pending morph vertex-upload range for the engine. Returns null when a
+  // full upload is needed (first time after load, or nothing tracked), else the inclusive
+  // [minVert, maxVert] slice that changed. Resets pending state.
+  consumeVertexUploadRange(): { minVert: number; maxVert: number } | null {
+    if (this.morphUploadFull || this.morphPendingMaxVert < 0) {
+      this.morphUploadFull = false
+      this.morphPendingMinVert = -1
+      this.morphPendingMaxVert = -1
+      return null
+    }
+    const range = { minVert: this.morphPendingMinVert, maxVert: this.morphPendingMaxVert }
+    this.morphPendingMinVert = -1
+    this.morphPendingMaxVert = -1
+    return range
   }
 
   private buildClipFromVmdKeyFrames(vmdKeyFrames: VMDKeyFrame[]): AnimationClip {
@@ -1143,13 +1349,13 @@ export class Model {
         const interp = frameB.interpolation
 
         const rotT = interpolateControlPoints(interp.rotation, gradient)
-        const rotation = Quat.slerp(frameA.rotation, frameB.rotation, rotT)
+        const rotation = Quat.slerpInto(frameA.rotation, frameB.rotation, rotT, _animSlerp)
 
         const txWeight = interpolateControlPoints(interp.translationX, gradient)
         const tyWeight = interpolateControlPoints(interp.translationY, gradient)
         const tzWeight = interpolateControlPoints(interp.translationZ, gradient)
 
-        const interpolatedVMDTranslation = new Vec3(
+        const interpolatedVMDTranslation = _animInterpT.setXYZ(
           frameA.translation.x + (frameB.translation.x - frameA.translation.x) * txWeight,
           frameA.translation.y + (frameB.translation.y - frameA.translation.y) * tyWeight,
           frameA.translation.z + (frameB.translation.z - frameA.translation.z) * tzWeight
@@ -1235,10 +1441,13 @@ export class Model {
     if (!ikChainInfo) return
 
     // Solve each IK solver sequentially, ensuring consistent state between solvers
+    let firstSolver = true
     for (const solver of ikSolvers) {
-      // Recompute ALL world matrices before each solver starts
-      // This ensures each solver sees the effects of previous solvers on localRotations
-      this.computeWorldMatrices()
+      // Each solver must see the effects of previous solvers on localRotations, so
+      // recompute world matrices between solvers. The first solver is skipped: the
+      // caller (update) already computed them and nothing has changed localRotations yet.
+      if (!firstSolver) this.computeWorldMatrices()
+      firstSolver = false
 
       // Clear computed set for this solver's pass
       this.ikComputedSet.clear()
@@ -1388,21 +1597,13 @@ export class Model {
 
     if (boneCount === 0) return
 
-    // Local computed array (avoids instance field overhead)
-    const computed = new Array<boolean>(boneCount).fill(false)
-
-    const computeWorld = (i: number): void => {
-      if (computed[i]) return
-
+    // Flat traversal in precomputed order: every bone's parent is already done, so no
+    // per-bone visited check, no recursion, and no per-call allocation. Same per-bone
+    // math as before. Scratch slots are safe to reuse since there's no reentrancy now.
+    const order = this.deformOrder
+    for (let k = 0; k < boneCount; k++) {
+      const i = order[k]
       const b = bones[i]
-      if (b.parentIndex >= boneCount) {
-        console.warn(`[RZM] bone ${i} parent out of range: ${b.parentIndex}`)
-      }
-
-      // Ensure parent is computed FIRST, before we touch any scratch buffers.
-      // Recursion may itself use scratchMat4Values[0] / scratchQuat; doing it up
-      // front keeps the current frame's scratch slots untouched when we use them below.
-      if (b.parentIndex >= 0 && !computed[b.parentIndex]) computeWorld(b.parentIndex)
 
       const boneRot = localRot[i]
       let fx = boneRot.x, fy = boneRot.y, fz = boneRot.z, fw = boneRot.w
@@ -1467,10 +1668,6 @@ export class Model {
       } else {
         worldMat.values.set(localMVals)
       }
-      computed[i] = true
     }
-
-    // Process all bones (recursion handles dependencies automatically)
-    for (let i = 0; i < boneCount; i++) computeWorld(i)
   }
 }

package/src/physics/body.ts

@@ -40,6 +40,12 @@ export class RigidBodyStore {
   readonly bodyOffsetInverse: Float32Array // 16*N column-major
   private boneOffsetsReady = false
 
+  // Flat list of (i, j) pairs that survive the static-static + group/mask
+  // filter. None of those inputs change after construction, so building this
+  // once collapses 60k pair tests/step (349 bodies) down to a few thousand.
+  // Built lazily on first access.
+  private collisionPairs: Uint16Array | null = null
+
   constructor(rigidbodies: Rigidbody[]) {
     const N = rigidbodies.length
     this.count = N
@@ -247,6 +253,29 @@ export class RigidBodyStore {
   isBoneOffsetsReady(): boolean {
     return this.boneOffsetsReady
   }
+
+  // Pair-filter inputs (invMass, group, mask) are immutable post-construction,
+  // so build the candidate-pair list once and reuse every step.
+  getCollisionPairs(): Uint16Array {
+    if (this.collisionPairs !== null) return this.collisionPairs
+    const N = this.count
+    const invMass = this.invMass
+    const group = this.collisionGroup
+    const mask = this.willCollideMask
+    const buf: number[] = []
+    for (let i = 0; i < N; i++) {
+      const gi = group[i]
+      const mi = mask[i]
+      const dynA = invMass[i] > 0
+      for (let j = i + 1; j < N; j++) {
+        if (!dynA && invMass[j] === 0) continue
+        if ((mi & group[j]) === 0 || (mask[j] & gi) === 0) continue
+        buf.push(i, j)
+      }
+    }
+    this.collisionPairs = new Uint16Array(buf)
+    return this.collisionPairs
+  }
 }
 
 const _scratchA = new Float32Array(16)

package/src/physics/constraint.ts

@@ -26,6 +26,23 @@ export interface SixDofSpringConstraint {
   springEnabled: Uint8Array     // length 6
   springStiffness: Float32Array // length 6 (k)
   equilibriumPoint: Float32Array// length 6, baked at setup time
+
+  // 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
+  // on pos/ori/inertia which are constant during solve.
+  cacheSkip: boolean              // both bodies static — skip entirely
+  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
+  cacheLinJacInv: Float32Array    // 3: 1/(im+im+cA²·ii+cB²·ii) per axis
+  cacheLinTargetVel: Float32Array // 3: limit ERP + spring drive, signed
+  cacheLinActive: Uint8Array      // 3
+  cacheAngAxes: Float32Array      // 9
+  cacheAngTargetVel: Float32Array // 3
+  cacheAngActive: Uint8Array      // 3
+  cacheAngJacInv: number          // 1 — same for all 3 angular axes
 }
 
 export const STOP_ERP = 0.475
@@ -102,6 +119,19 @@ export function buildConstraints(
       springEnabled,
       springStiffness,
       equilibriumPoint: new Float32Array(6),
+      cacheSkip: false,
+      cacheLeverA: new Float32Array(3),
+      cacheLeverB: new Float32Array(3),
+      cacheLinAxes: new Float32Array(9),
+      cacheLinCrossA: new Float32Array(9),
+      cacheLinCrossB: new Float32Array(9),
+      cacheLinJacInv: new Float32Array(3),
+      cacheLinTargetVel: new Float32Array(3),
+      cacheLinActive: new Uint8Array(3),
+      cacheAngAxes: new Float32Array(9),
+      cacheAngTargetVel: new Float32Array(3),
+      cacheAngActive: new Uint8Array(3),
+      cacheAngJacInv: 0,
     })
   }