reze-engine 0.41.2 → 0.41.4

package/src/model.ts

@@ -92,6 +92,12 @@ export interface Bone {
   appendRatio?: number // 0..1
   appendRotate?: boolean
   appendMove?: boolean
+  /** 軸制限: this bone rotates ONLY about this axis (the twist bones use it). */
+  fixedAxis?: [number, number, number]
+  /** 変形階層: MMD poses whole layers in order, not bones in array order.
+   *  Parsed but not yet honoured — distinct from Model's `deformOrder`, which is
+   *  this engine's parent-before-child traversal. */
+  deformLayer?: number
   ikTargetIndex?: number // IK target bone index (if this bone is an IK effector)
   ikIteration?: number // IK iteration count
   ikLimitAngle?: number // IK rotation constraint (radians)
@@ -477,6 +483,9 @@ export class Model {
     this.applyMorphs()
   }
 
+  /** 軸制限 bones and their normalised axes — see applyFixedAxes. */
+  private fixedAxisBones: { index: number; x: number; y: number; z: number }[] = []
+
   private initializeRuntimeSkeleton(): void {
     const boneCount = this.skeleton.bones.length
 
@@ -490,6 +499,18 @@ export class Model {
       worldMatrices[i] = Mat4.identity()
     }
 
+    // 軸制限 bones, gathered once and normalised. A standard rig has four —
+    // the two arm twists and the two wrist twists — so this is a four-element
+    // walk per pose rather than a branch on every bone.
+    this.fixedAxisBones = []
+    for (let i = 0; i < boneCount; i++) {
+      const a = this.skeleton.bones[i].fixedAxis
+      if (!a) continue
+      const len = Math.hypot(a[0], a[1], a[2])
+      if (len < 1e-8) continue
+      this.fixedAxisBones.push({ index: i, x: a[0] / len, y: a[1] / len, z: a[2] / len })
+    }
+
     this.runtimeSkeleton = {
       localRotations,
       localTranslations,
@@ -673,19 +694,42 @@ export class Model {
    * 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.
    */
+  /**
+   * Take the last frame's bone-morph offsets back off, before any pose source
+   * runs.
+   *
+   * This cannot live at the top of applyBoneMorphs, which is where it used to
+   * be. A pose source writes only the bones its clip keys, and it writes them
+   * from the clip — so restoring afterwards overwrote the freshly animated pose
+   * with a snapshot taken a frame earlier, and the re-snapshot immediately
+   * below then saved that same stale value again. The result was not a drift or
+   * a lag: every bone any bone morph touched stayed pinned to the first frame
+   * the model was posed at, permanently, and at ANY weight — the restore ran
+   * over the touched set before the weight test, so a morph sitting at 0 froze
+   * its bones just as hard as one at 1.
+   *
+   * It reads as "the arms don't animate" because arms are what these morphs
+   * touch: character models routinely ship T-Pose / A-Pose / ShouderBlend /
+   * ElbowBlend adjusters on 腕 and ひじ, and nothing else in the rig is a
+   * comparably popular bone-morph target.
+   */
+  private undoBoneMorphs(): void {
+    if (!this.boneMorphApplied) return
+    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])
+    }
+    this.boneMorphApplied = false
+  }
+
   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])
-      }
-    }
+    // Snapshot the pose as the sources left it, so undoBoneMorphs can hand these
+    // bones back unmorphed at the top of the next frame. The two halves are a
+    // pair: without the undo a stage — which has no clip to rewrite its bones —
+    // would compound the same offset every frame.
     for (let i = 0; i < this.boneMorphBones.length; i++) {
       const b = this.boneMorphBones[i]
       this.boneMorphRestoreR[i].set(this.runtimeSkeleton.localRotations[b])
@@ -1922,6 +1966,39 @@ export class Model {
       : frameA.weight
   }
 
+  /**
+   * Hold 軸制限 bones to their own axis.
+   *
+   * A twist bone (腕捩 / 手捩) exists to rotate about the length of the limb and
+   * nothing else, and PMX says so by giving it a fixed axis. A VMD still keys it
+   * with a full quaternion, so without the constraint the bone bends as well as
+   * twists — and because the elbow is parented to 腕捩 and 腕捩1..3 inherit a
+   * fraction of it, that error is carried into the whole forearm and multiplied
+   * three ways down the arm. It is the most visible thing on the model.
+   *
+   * Projecting the quaternion's vector part onto the axis and renormalising is
+   * what keeps the twist and drops everything else; the same operation MMD and
+   * every faithful runtime performs.
+   *
+   * Applied to the STORED local rotation rather than inside a matrix path,
+   * because the append children read that array directly: constrain it once and
+   * the bone, its inheritors and a hand-posed gizmo all agree.
+   */
+  private applyFixedAxes(): void {
+    for (const a of this.fixedAxisBones) {
+      const q = this.runtimeSkeleton.localRotations[a.index]
+      const dot = q.x * a.x + q.y * a.y + q.z * a.z
+      const x = a.x * dot
+      const y = a.y * dot
+      const z = a.z * dot
+      const len = Math.sqrt(x * x + y * y + z * z + q.w * q.w)
+      if (len > 1e-8) {
+        const inv = 1 / len
+        q.setXYZW(x * inv, y * inv, z * inv, q.w * inv)
+      }
+    }
+  }
+
   private applyPoseFromClip(clip: AnimationClip | null, frame: number): void {
     if (!clip) return
     this.applyIkFromClip(clip, frame)
@@ -1941,6 +2018,7 @@ export class Model {
       this.runtimeSkeleton.localRotations[boneIdx].set(_animSlerp)
       this.runtimeSkeleton.localTranslations[boneIdx].set(localTranslation)
     }
+    this.applyFixedAxes()
 
     for (const [morphName, keyFrames] of clip.morphTracks.entries()) {
       const weight = this.sampleMorphTrack(morphName, keyFrames, frame, this.morphTrackIndices)
@@ -2084,6 +2162,7 @@ export class Model {
       this.runtimeSkeleton.localRotations[i].set(_blendQ)
       this.runtimeSkeleton.localTranslations[i].set(localTranslation)
     }
+    this.applyFixedAxes()
 
     const morphCount = morphAcc.length
     for (let i = 0; i < morphCount; i++) {
@@ -2237,6 +2316,13 @@ export class Model {
     const evWatch = this.clipEvents.size > 0 ? this.animationState.getCurrentAnimation() : null
     const evPrevFrame = evWatch !== null ? this.animationState.getCurrentFrame() : 0
     this.animationState.update(deltaTime)
+
+    // Hand the pose sources their bones unmorphed. A bone morph is an offset on
+    // top of the pose, so last frame's offset has to come off before this
+    // frame's pose goes on — taking it off afterwards is what froze every
+    // morph-touched bone at its first posed frame.
+    this.undoBoneMorphs()
+
     if (!this.clipApplySuspended) {
       if (this.oneShot !== null) {
         this.applyOneShot(deltaTime)
@@ -2378,7 +2464,9 @@ export class Model {
 
     // Handle append transformations (same logic as computeWorldMatrices)
     const appendParentIdx = b.appendParentIndex
-    const hasAppend = b.appendRotate &&
+    // `|| appendMove`: a move-only append (no rotation) was skipped altogether,
+    // because the guard demanded appendRotate before either branch could run.
+    const hasAppend = (b.appendRotate || b.appendMove) &&
       appendParentIdx !== undefined &&
       appendParentIdx >= 0 &&
       appendParentIdx < bones.length
@@ -2405,12 +2493,15 @@ export class Model {
           scratchQuat[2].setIdentity()
           Quat.slerpInto(scratchQuat[2], scratchQuat[0], absRatio, scratchQuat[1])
 
-          // finalRot = slerpResult * finalRot (rotation composition as quat mul)
+          // MMD composes the append on the RIGHT: own animated rotation first, then
+          // the inherited one (saba's `r = r * appendRotate`). We had it on the
+          // left, which is a different rotation whenever a bone carries BOTH its
+          // own key and an append — the twist bones, if a motion keys them.
           const sx = scratchQuat[1].x, sy = scratchQuat[1].y, sz = scratchQuat[1].z, sw = scratchQuat[1].w
-          const nx = sw * fx + sx * fw + sy * fz - sz * fy
-          const ny = sw * fy - sx * fz + sy * fw + sz * fx
-          const nz = sw * fz + sx * fy - sy * fx + sz * fw
-          const nw = sw * fw - sx * fx - sy * fy - sz * fz
+          const nx = fw * sx + fx * sw + fy * sz - fz * sy
+          const ny = fw * sy - fx * sz + fy * sw + fz * sx
+          const nz = fw * sz + fx * sy - fy * sx + fz * sw
+          const nw = fw * sw - fx * sx - fy * sy - fz * sz
           fx = nx; fy = ny; fz = nz; fw = nw
         }
 
@@ -2469,7 +2560,7 @@ export class Model {
 
       const appendParentIdx = b.appendParentIndex
       const hasAppend =
-        b.appendRotate && appendParentIdx !== undefined && appendParentIdx >= 0 && appendParentIdx < boneCount
+        (b.appendRotate || b.appendMove) && appendParentIdx !== undefined && appendParentIdx >= 0 && appendParentIdx < boneCount
 
       if (hasAppend) {
         const ratio = b.appendRatio === undefined ? 1 : Math.max(-1, Math.min(1, b.appendRatio))
@@ -2487,12 +2578,15 @@ export class Model {
             scratchQuat[2].setIdentity()
             Quat.slerpInto(scratchQuat[2], scratchQuat[0], absRatio, scratchQuat[1])
 
-            // finalRot = slerpResult * finalRot (quat mul)
+            // MMD composes the append on the RIGHT: own animated rotation first, then
+            // the inherited one (saba's `r = r * appendRotate`). We had it on the
+            // left, which is a different rotation whenever a bone carries BOTH its
+            // own key and an append — the twist bones, if a motion keys them.
             const sx = scratchQuat[1].x, sy = scratchQuat[1].y, sz = scratchQuat[1].z, sw = scratchQuat[1].w
-            const nx = sw * fx + sx * fw + sy * fz - sz * fy
-            const ny = sw * fy - sx * fz + sy * fw + sz * fx
-            const nz = sw * fz + sx * fy - sy * fx + sz * fw
-            const nw = sw * fw - sx * fx - sy * fy - sz * fz
+            const nx = fw * sx + fx * sw + fy * sz - fz * sy
+            const ny = fw * sy - fx * sz + fy * sw + fz * sx
+            const nz = fw * sz + fx * sy - fy * sx + fz * sw
+            const nw = fw * sw - fx * sx - fy * sy - fz * sz
             fx = nx; fy = ny; fz = nz; fw = nw
           }
 

package/src/pmx-loader.ts

@@ -354,6 +354,8 @@ export class PmxLoader {
         ikIteration?: number
         ikLimitAngle?: number
         ikLinks?: IKLink[]
+        fixedAxis?: [number, number, number]
+        deformLayer?: number
       }
       const abs: AbsBone[] = new Array(count)
       // PMX 2.x bone flags (best-effort common masks)
@@ -372,7 +374,7 @@ export class PmxLoader {
         const y = this.getFloat32()
         const z = this.getFloat32()
         const parentIndex = this.getNonVertexIndex(this.boneIndexSize)
-        this.getInt32() // transform order (skip)
+        const deformLayer = this.getInt32() // 変形階層
         const flags = this.getUint16()
 
         // Tail: bone index or offset vector3
@@ -397,11 +399,10 @@ export class PmxLoader {
           appendMove = (flags & FLAG_APPEND_MOVE) !== 0
         }
 
-        // Axis limit
+        // Axis limit (軸制限)
+        let fixedAxis: [number, number, number] | undefined = undefined
         if ((flags & FLAG_AXIS_LIMIT) !== 0) {
-          this.getFloat32()
-          this.getFloat32()
-          this.getFloat32()
+          fixedAxis = [this.getFloat32(), this.getFloat32(), this.getFloat32()]
         }
 
         // Local axis (two vectors x and z)
@@ -467,6 +468,8 @@ export class PmxLoader {
           appendRatio,
           appendRotate,
           appendMove,
+          fixedAxis,
+          deformLayer,
           ikTargetIndex,
           ikIteration,
           ikLimitAngle,
@@ -487,6 +490,8 @@ export class PmxLoader {
           appendRatio: a.appendRatio,
           appendRotate: a.appendRotate,
           appendMove: a.appendMove,
+          fixedAxis: a.fixedAxis,
+          deformLayer: a.deformLayer,
           ikTargetIndex: a.ikTargetIndex,
           ikIteration: a.ikIteration,
           ikLimitAngle: a.ikLimitAngle,

package/src/psd-loader.ts

@@ -0,0 +1,193 @@
+// PSD → RGBA8, from the merged composite.
+//
+// MMD texture packs are often shipped as the artist's working files, so a
+// material's texture path points at a .psd that no browser will decode. The
+// layers are none of our business — Photoshop writes a flattened composite of
+// the whole document at the end of the file, which is exactly the image the
+// artist saw, so that is what this reads.
+//
+// (A file saved with "Maximize Compatibility" off has no useful composite. There
+// is nothing to be done about that here beyond failing clearly: reconstructing it
+// would mean compositing every layer, blend mode and clipping group — a Photoshop,
+// not a texture loader.)
+
+import type { DecodedImage } from "./tga-loader"
+
+const MAGIC = 0x38425053 // "8BPS", big-endian — PSD is big-endian throughout
+
+const enum ColorMode {
+  Bitmap = 0,
+  Grayscale = 1,
+  Indexed = 2,
+  RGB = 3,
+  CMYK = 4,
+  Multichannel = 7,
+  Duotone = 8,
+  Lab = 9,
+}
+
+const MODE_NAMES: Record<number, string> = {
+  [ColorMode.Bitmap]: "bitmap",
+  [ColorMode.CMYK]: "CMYK",
+  [ColorMode.Multichannel]: "multichannel",
+  [ColorMode.Lab]: "Lab",
+}
+
+/** True when these bytes are a PSD/PSB, by magic rather than by file extension. */
+export function isPsd(buffer: ArrayBuffer): boolean {
+  return buffer.byteLength >= 26 && new DataView(buffer).getUint32(0, false) === MAGIC
+}
+
+/**
+ * PackBits, one row at a time.
+ *
+ * `end` bounds the row rather than the buffer: the row-length table says how many
+ * compressed bytes this row occupies, and trusting the control bytes past that
+ * would let one malformed row eat the next one's data.
+ */
+function unpackBits(src: Uint8Array, start: number, end: number, dst: Uint8Array, at: number, limit: number): number {
+  let i = start
+  let o = at
+  while (i < end && o < limit) {
+    const n = (src[i++] << 24) >> 24 // to signed
+    if (n >= 0) {
+      const count = Math.min(n + 1, limit - o, end - i)
+      for (let k = 0; k < count; k++) dst[o++] = src[i++]
+    } else if (n !== -128) {
+      // -128 is a no-op by the spec, not a run of 129.
+      const count = Math.min(1 - n, limit - o)
+      const b = src[i++]
+      for (let k = 0; k < count; k++) dst[o++] = b
+    }
+  }
+  return o
+}
+
+/**
+ * Decode a PSD's composite to RGBA8.
+ *
+ * RGB, grayscale, indexed and duotone at 8 or 16 bits per channel, raw or RLE —
+ * which is every texture that has actually turned up. CMYK and Lab throw: they
+ * need a colour conversion that would be guesswork without a profile, and a
+ * silently wrong-coloured texture is worse than a missing one.
+ */
+export function decodePsd(buffer: ArrayBuffer): DecodedImage {
+  const v = new DataView(buffer)
+  if (buffer.byteLength < 26 || v.getUint32(0, false) !== MAGIC) throw new Error("not a PSD")
+
+  const version = v.getUint16(4, false) // 1 = PSD, 2 = PSB
+  if (version !== 1 && version !== 2) throw new Error(`PSD unsupported version ${version}`)
+  const channels = v.getUint16(12, false)
+  const height = v.getUint32(14, false)
+  const width = v.getUint32(18, false)
+  const depth = v.getUint16(22, false)
+  const mode = v.getUint16(24, false)
+
+  if (width <= 0 || height <= 0) throw new Error(`PSD bad dimensions ${width}x${height}`)
+  if (depth !== 8 && depth !== 16) throw new Error(`PSD unsupported bit depth ${depth}`)
+  if (mode in MODE_NAMES) throw new Error(`PSD unsupported colour mode: ${MODE_NAMES[mode]}`)
+
+  // Three variable-length sections stand between the header and the pixels. Only
+  // the indexed palette is worth reading; the rest is skipped by its length.
+  let p = 26
+  const colorDataLen = v.getUint32(p, false)
+  const colorData = p + 4
+  p = colorData + colorDataLen
+  p += 4 + v.getUint32(p, false) // image resources
+  // PSB states this length in 8 bytes. Only the low word can matter — the high
+  // one would mean a layer section larger than 4GB.
+  if (version === 2) {
+    p += 8 + v.getUint32(p + 4, false)
+  } else {
+    p += 4 + v.getUint32(p, false)
+  }
+  if (p + 2 > buffer.byteLength) throw new Error("PSD truncated before the composite")
+
+  const compression = v.getUint16(p, false)
+  p += 2
+
+  // Only the channels that carry colour, plus one alpha. A PSD can hold spot and
+  // mask channels past those; they are stored after, so ignoring them is a matter
+  // of not reading that far.
+  const colourChannels = mode === ColorMode.RGB ? 3 : 1
+  const hasAlpha = channels > colourChannels
+  const used = colourChannels + (hasAlpha ? 1 : 0)
+  if (channels < colourChannels) throw new Error(`PSD has ${channels} channel(s), expected ${colourChannels}`)
+
+  const bytesPerSample = depth === 16 ? 2 : 1
+  const planeSamples = width * height
+  const planeBytes = planeSamples * bytesPerSample
+  const planes = new Uint8Array(used * planeBytes)
+
+  if (compression === 0) {
+    const need = used * planeBytes
+    if (p + need > buffer.byteLength) throw new Error("PSD truncated composite")
+    planes.set(new Uint8Array(buffer, p, need))
+  } else if (compression === 1) {
+    // A table of per-row compressed lengths for EVERY channel comes first,
+    // including the channels being skipped — so the table is read in full even
+    // though only the first `used` channels' rows are decoded.
+    const countBytes = version === 2 ? 4 : 2
+    const tableBytes = channels * height * countBytes
+    if (p + tableBytes > buffer.byteLength) throw new Error("PSD truncated row table")
+    const rowLengths = new Uint32Array(channels * height)
+    for (let i = 0; i < rowLengths.length; i++) {
+      rowLengths[i] = countBytes === 2 ? v.getUint16(p + i * 2, false) : v.getUint32(p + i * 4, false)
+    }
+    const src = new Uint8Array(buffer)
+    let at = p + tableBytes
+    for (let c = 0; c < channels; c++) {
+      for (let y = 0; y < height; y++) {
+        const len = rowLengths[c * height + y]
+        if (at + len > buffer.byteLength) throw new Error("PSD truncated composite")
+        if (c < used) {
+          const rowStart = c * planeBytes + y * width * bytesPerSample
+          unpackBits(src, at, at + len, planes, rowStart, rowStart + width * bytesPerSample)
+        }
+        at += len
+      }
+    }
+  } else {
+    // 2 and 3 are the Zip codes. They appear on layer data, effectively never on
+    // the composite, and inflating would mean shipping a decompressor.
+    throw new Error(`PSD unsupported compression ${compression}`)
+  }
+
+  // 16-bit samples are big-endian; the high byte is the 8-bit value.
+  const sample = (plane: number, i: number): number =>
+    depth === 16 ? planes[plane * planeBytes + i * 2] : planes[plane * planeBytes + i]
+
+  const rgba = new Uint8Array(planeSamples * 4)
+
+  if (mode === ColorMode.Indexed) {
+    // The palette is the colour mode data: 256 reds, then 256 greens, then blues.
+    if (colorDataLen < 768) throw new Error("PSD indexed image has no palette")
+    const pal = new Uint8Array(buffer, colorData, 768)
+    for (let i = 0; i < planeSamples; i++) {
+      const idx = sample(0, i)
+      rgba[i * 4] = pal[idx]
+      rgba[i * 4 + 1] = pal[256 + idx]
+      rgba[i * 4 + 2] = pal[512 + idx]
+      rgba[i * 4 + 3] = hasAlpha ? sample(1, i) : 255
+    }
+    return { rgba, width, height }
+  }
+
+  for (let i = 0; i < planeSamples; i++) {
+    if (mode === ColorMode.RGB) {
+      rgba[i * 4] = sample(0, i)
+      rgba[i * 4 + 1] = sample(1, i)
+      rgba[i * 4 + 2] = sample(2, i)
+    } else {
+      // Grayscale and duotone: one plane across all three. Duotone's ink colours
+      // live in the colour mode data, and the spec's own advice is to treat the
+      // data as grayscale — which is what every other reader does.
+      const g = sample(0, i)
+      rgba[i * 4] = g
+      rgba[i * 4 + 1] = g
+      rgba[i * 4 + 2] = g
+    }
+    rgba[i * 4 + 3] = hasAlpha ? sample(colourChannels, i) : 255
+  }
+  return { rgba, width, height }
+}