reze-engine 0.50.4 → 0.50.6

package/src/camera-animation.ts

@@ -4,7 +4,7 @@
 
 import { Vec3 } from "./math"
 import { bezierInterpolate } from "./animation"
-import type { CameraKeyframe } from "./vmd-loader"
+import { DEFAULT_CAMERA_INTERPOLATION, type CameraKeyframe } from "./vmd-loader"
 
 const FPS = 30
 const DEG2RAD = Math.PI / 180
@@ -53,6 +53,19 @@ export class CameraAnimation {
     return this.frames.map((f) => f.frame)
   }
 
+  /**
+   * Every keyframe, in full — the track as an editable document.
+   *
+   * The counterpart to keyframeIndices(), which deliberately withholds the
+   * poses because a timeline only wants the rhythm. An EDITOR wants the poses:
+   * it has to show what the shot does at a cut, let it be changed, and write
+   * the result back out. Shallow copies, so a host mutating what it gets back
+   * cannot reach into the track this is sampling from mid-playback.
+   */
+  keyframes(): CameraKeyframe[] {
+    return this.frames.map((f) => ({ ...f }))
+  }
+
   /** Sample the camera pose at time `t` (seconds). Clamps to the track ends; null if empty. */
   sample(t: number): CameraPose | null {
     const frames = this.frames
@@ -76,7 +89,7 @@ export class CameraAnimation {
     const span = b.frame - a.frame
     const localT = span > 0 ? (frame - a.frame) / span : 0
     // The incoming interpolation curve is stored on the segment's end keyframe (b).
-    const ip = b.interpolation
+    const ip = b.interpolation ?? DEFAULT_CAMERA_INTERPOLATION
 
     return {
       target: new Vec3(

package/src/engine.ts

@@ -8,7 +8,8 @@ import { CULL_COMPUTE_WGSL } from "./shaders/passes/cull"
 import { buildAnchorTable, anchorAliasWgsl, EMPTY_ANCHOR_TABLE, type AnchorTable } from "./shaders/anchor-table"
 import { MIDI_HEADER, MIDI_KEYS, MIDI_NOTES, MIDI_STRIDE } from "./shaders/midi-api"
 import { decodeTga } from "./tga-loader"
-import { VMDLoader } from "./vmd-loader"
+import { VMDLoader, type CameraKeyframe } from "./vmd-loader"
+import { VMDWriter } from "./vmd-writer"
 import { CameraAnimation } from "./camera-animation"
 import { PmxLoader } from "./pmx-loader"
 import { RezePhysics } from "./physics"
@@ -1525,6 +1526,16 @@ export class Engine {
    * this line, and the accessors then answer 0 rather than failing to compile.
    */
   private static readonly MRT_IDS = true
+  /**
+   * What fraction of its authored damping a chest rig's body keeps.
+   *
+   * The whole tuning surface for how long those rigs swing: lower rings
+   * longer, 1 restores the authored value exactly. It does NOT change where
+   * they hang at rest — that is the property that made damping the right knob
+   * (see RezePhysics.setJiggleDamping). Judge it against the models that
+   * motivated it; it is a starting point, not a measurement.
+   */
+  private static readonly JIGGLE_DAMPING_SCALE = 0.5
   /** The id attachment. Multisampled with the pass and NEVER resolved: an
    *  averaged id belongs to nothing, so consumers textureLoad sample 0. */
   private idTexture: GPUTexture | null = null
@@ -6500,6 +6511,39 @@ export class Engine {
     this.camera.setVmdDriven(this.cameraAnimation !== null)
   }
 
+  /**
+   * Drive the shot from camera keyframes built in JS — the camera's answer to
+   * `Model.loadClip`.
+   *
+   * The two loadCameraVmd* methods take FILE BYTES, which is all a viewer ever
+   * needs. An editor needs the other direction: hold the track as data, change
+   * a keyframe, and see the result immediately. Going through the writer and
+   * back through the parser for every edit would work and would be absurd.
+   *
+   * Empty (or an empty array) clears the track and returns the camera to orbit,
+   * same as clearCameraVmd — a track with no keyframes cannot drive anything,
+   * and silently keeping the previous one would be worse than saying so.
+   */
+  loadCameraClip(frames: CameraKeyframe[]): void {
+    this.cameraAnimation = frames.length ? new CameraAnimation([...frames]) : null
+    this.camera.setVmdDriven(this.cameraAnimation !== null)
+  }
+
+  /** The loaded camera track as editable keyframes, or [] with none loaded.
+   *  Copies — mutating them does not reach the track being sampled. */
+  getCameraClip(): CameraKeyframe[] {
+    return this.cameraAnimation?.keyframes() ?? []
+  }
+
+  /** The loaded camera track as camera-VMD bytes. Throws with none loaded:
+   *  writing an empty camera file is a mistake worth hearing about, not a
+   *  30-byte header to hand someone as a download. */
+  exportCameraVmd(): ArrayBuffer {
+    const frames = this.cameraAnimation?.keyframes()
+    if (!frames?.length) throw new Error("No camera track loaded")
+    return new VMDWriter().writeCamera(frames)
+  }
+
   /** Turn the loaded camera VMD on/off (falls back to orbit when off). No-op if none loaded. */
   setCameraVmdEnabled(enabled: boolean): void {
     this.camera.setVmdDriven(enabled && this.cameraAnimation !== null)
@@ -7505,6 +7549,10 @@ export class Engine {
       if (inst.physics && this.physicsEnabled && inst.model.visible) {
         const tPhys = performance.now()
         inst.physics.step(deltaTime, inst.model.getWorldMatrices(), inst.model.getBoneInverseBindMatrices())
+        // The step published new world matrices for the simulated bones; the
+        // bones that INHERIT from them are still wearing the animated pose.
+        // Returns immediately unless this rig actually has such a bone.
+        inst.model.applyPhysicsAppend()
         physicsMs += performance.now() - tPhys
       }
       if (inst.vertexBufferNeedsUpdate) this.updateVertexBuffer(inst)
@@ -8522,6 +8570,20 @@ export class Engine {
     // solver for the heaviest mesh in the scene and dropping it afterwards was
     // both wasted work and an invariant maintained in the wrong place.
     const physics = !isStage && rbs.length > 0 ? new RezePhysics(rbs, model.getJoints()) : null
+    // Which bones the simulation will overwrite, handed to the pose pipeline so
+    // the append (付与) pass can consume the simulated result instead of the
+    // animated one. Precomputed here, once, because the answer is topology —
+    // see Model.setPhysicsDrivenBones for what it costs when a rig needs it and
+    // why it costs nothing when none does.
+    if (physics) {
+      model.setPhysicsDrivenBones(physics.getPhysicsDrivenBones())
+      // The bodies an inherited-from bone rides on are damped less than the
+      // rest, so they swing longer WITHOUT hanging lower — see
+      // RezePhysics.setJiggleDamping for why damping is the separable knob and
+      // solver iterations are not.
+      const appendSources = model.getAppendSourceBones()
+      if (appendSources.length > 0) physics.setJiggleDamping(appendSources, Engine.JIGGLE_DAMPING_SCALE)
+    }
     // Adopt the scene's air, or a model added mid-session would fall under
     // different gravity from the ones already on stage.
     if (physics) {

package/src/index.ts

@@ -109,8 +109,8 @@ export {
   interpolateControlPoints,
   rawInterpolationToBoneInterpolation,
 } from "./animation"
-export { VMDLoader, type CameraKeyframe, type IkFrame } from "./vmd-loader"
-export { VMDWriter } from "./vmd-writer"
+export { VMDLoader, DEFAULT_CAMERA_INTERPOLATION, type CameraKeyframe, type IkFrame } from "./vmd-loader"
+export { VMDWriter, type VmdTrackSelection } from "./vmd-writer"
 export { PmxLoader } from "./pmx-loader"
 export { CameraAnimation, type CameraPose } from "./camera-animation"
 export { RezePhysics } from "./physics"

package/src/model.ts

@@ -4,7 +4,7 @@ import { joinAssetPath, type AssetReader } from "./asset-reader"
 import { Rigidbody, Joint } from "./physics"
 import { IKSolverSystem } from "./ik-solver"
 import { VMDLoader, type VMDKeyFrame } from "./vmd-loader"
-import { VMDWriter } from "./vmd-writer"
+import { VMDWriter, type VmdTrackSelection } from "./vmd-writer"
 import {
   AnimationClip,
   AnimationPlayOptions,
@@ -30,6 +30,10 @@ 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)
+// Scratch for the post-physics append recovery — see applyPhysicsAppend.
+const _appendBasisX = new Vec3(0, 0, 0)
+const _appendBasisY = new Vec3(0, 0, 0)
+const _appendBasisZ = new Vec3(0, 0, 0)
 // 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)
@@ -388,6 +392,15 @@ export class Model {
   // visited-array + closure. Order depends only on parentIndex (static), so this
   // reproduces the old recursion's finishing order exactly. See buildDeformOrder.
   private deformOrder!: Int32Array
+  /** 1 where the simulation overwrites the bone's world matrix. See setPhysicsDrivenBones. */
+  private physicsDriven: Uint8Array | null = null
+  /** Bones to recompute after a step, in deform order — null when no rig needs it. */
+  private physicsAppendOrder: Int32Array | null = null
+  /** Simulated bones something inherits from; their local rotation is recovered. */
+  private physicsAppendSources: Int32Array | null = null
+  /** Recovered post-step local rotations, kept OUT of localRotations on purpose. */
+  private appendRotOverride: Quat[] | null = null
+  private appendRotOverrideSet: Uint8Array | null = null
 
   // Bind-pose absolute (world) position per bone, xyz packed. Static (bindTranslation
   // accumulated down the hierarchy). Precomputed once so convertVMDTranslationToLocal
@@ -1707,10 +1720,20 @@ export class Model {
     return values[i - 1] + (values[i] - values[i - 1]) * t
   }
 
-  exportVmd(name: string): ArrayBuffer {
+  /**
+   * The clip called `name` as VMD bytes.
+   *
+   * `tracks` splits the file the same way `loadVmd`'s option splits what it
+   * reads: "motion" is the dance (bones + IK), "morphs" is the expression file
+   * to lay over one, "all" (the default) is both in one file as MMD exports it.
+   * A clip missing the half you asked for still writes — an empty motion or an
+   * empty expression file is a valid VMD, and is the honest answer to "export
+   * the morphs" for a clip that has none.
+   */
+  exportVmd(name: string, options?: { tracks?: VmdTrackSelection }): ArrayBuffer {
     const clip = this.animationState.getAnimationClip(name)
     if (!clip) throw new Error(`Animation clip "${name}" not found`)
-    return new VMDWriter().write(clip)
+    return new VMDWriter().write(clip, options)
   }
 
   play(): void
@@ -2612,7 +2635,141 @@ export class Model {
     }
   }
 
-  computeWorldMatrices(): void {
+  /**
+   * Which bones the physics simulation overwrites, and what that costs the
+   * append (付与) pass — the 胸 problem.
+   *
+   * PMX lets a bone inherit a fraction of another bone's rotation (付与親 /
+   * append parent). The pipeline computes that inheritance inside
+   * computeWorldMatrices, which runs BEFORE physics — and it reads the
+   * parent's LOCAL rotation, which physics never writes: the simulation
+   * publishes world matrices only. So when a rig hangs a bone off a simulated
+   * one, the inheritance saw the animated pose and nothing else, and the
+   * dependent bone sat still no matter how much the parent swung. Rigs that
+   * drive a chest this way — a simulated bone with the visible bones
+   * appending from it — produced no motion at all.
+   *
+   * The engine calls this once, after building the simulation, and it
+   * precomputes the whole answer: WHICH bones need revisiting after a step,
+   * in deform order. Everything downstream is a walk over that list.
+   */
+  setPhysicsDrivenBones(boneIndices: number[]): void {
+    const bones = this.skeleton.bones
+    const n = bones.length
+    this.physicsDriven = new Uint8Array(n)
+    for (const b of boneIndices) if (b >= 0 && b < n) this.physicsDriven[b] = 1
+
+    // Bones to recompute after a step: anything that INHERITS from a simulated
+    // bone, everything under it, and anything inheriting from those in turn.
+    // Simulated bones themselves are deliberately excluded — their world matrix
+    // IS the simulation's output, and recomputing it from a local pose the
+    // simulation never wrote would throw the step away.
+    const affected = new Uint8Array(n)
+    let changed = true
+    while (changed) {
+      changed = false
+      for (let k = 0; k < n; k++) {
+        const i = this.deformOrder[k]
+        if (affected[i] || this.physicsDriven[i]) continue
+        const b = bones[i]
+        const ap = b.appendParentIndex
+        const inheritsAffected =
+          (b.appendRotate || b.appendMove) && ap !== undefined && ap >= 0 && ap < n && (this.physicsDriven[ap] || affected[ap])
+        const parentAffected = b.parentIndex >= 0 && affected[b.parentIndex]
+        if (inheritsAffected || parentAffected) {
+          affected[i] = 1
+          changed = true
+        }
+      }
+    }
+
+    const order: number[] = []
+    for (let k = 0; k < n; k++) {
+      const i = this.deformOrder[k]
+      if (affected[i]) order.push(i)
+    }
+    this.physicsAppendOrder = order.length > 0 ? Int32Array.from(order) : null
+    // The simulated bones something actually inherits from — the only ones
+    // whose post-step local rotation has to be recovered below.
+    const sources = new Set<number>()
+    for (const i of order) {
+      const ap = bones[i].appendParentIndex
+      if (ap !== undefined && ap >= 0 && ap < n && this.physicsDriven[ap]) sources.add(ap)
+    }
+    this.physicsAppendSources = sources.size > 0 ? Int32Array.from(sources) : null
+    if (this.appendRotOverride === null && this.physicsAppendOrder) {
+      this.appendRotOverride = Array.from({ length: n }, () => Quat.identity())
+      this.appendRotOverrideSet = new Uint8Array(n)
+    }
+  }
+
+  /** The simulated bones that visible bones INHERIT from — the chest rig, in
+   *  one list. Empty unless setPhysicsDrivenBones found such a relationship. */
+  getAppendSourceBones(): number[] {
+    return this.physicsAppendSources ? Array.from(this.physicsAppendSources) : []
+  }
+
+  /**
+   * Re-run the append pass against the simulation's result. Call after a step.
+   *
+   * Two halves. First the simulated bones an append parent list names get their
+   * post-step LOCAL rotation recovered — physics published only world matrices,
+   * and the append math speaks local. The recovery is the ordinary change of
+   * basis: local = parentWorld⁻¹ · world, read back as a quaternion off the
+   * relative basis, which is exact for the rigid transforms these are.
+   *
+   * Then the dependent bones recompute, in deform order, reading that recovered
+   * rotation instead of the animated one. The recovered value lives in its OWN
+   * array rather than in localRotations, deliberately: localRotations is what
+   * next frame's pose blends against and what the simulation reads to build
+   * kinematic targets, and writing a simulation result back into it would make
+   * the animation chase its own tail.
+   */
+  applyPhysicsAppend(): void {
+    const order = this.physicsAppendOrder
+    const sources = this.physicsAppendSources
+    if (!order || !sources || !this.appendRotOverride || !this.appendRotOverrideSet) return
+    const bones = this.skeleton.bones
+    const worldMats = this.runtimeSkeleton.worldMatrices
+
+    this.appendRotOverrideSet.fill(0)
+    for (let s = 0; s < sources.length; s++) {
+      const i = sources[s]
+      const w = worldMats[i].values
+      const p = bones[i].parentIndex
+      // Columns of the bone's own basis, expressed in its parent's frame. With
+      // no parent the world basis already IS the local one.
+      let bx0 = w[0], bx1 = w[1], bx2 = w[2]
+      let by0 = w[4], by1 = w[5], by2 = w[6]
+      let bz0 = w[8], bz1 = w[9], bz2 = w[10]
+      if (p >= 0) {
+        const pm = worldMats[p].values
+        // parentᵀ · child, the rotation half of parentWorld⁻¹ · world: the
+        // parent basis is orthonormal, so its inverse is its transpose.
+        const r0 = bx0, r1 = bx1, r2 = bx2
+        bx0 = pm[0] * r0 + pm[1] * r1 + pm[2] * r2
+        bx1 = pm[4] * r0 + pm[5] * r1 + pm[6] * r2
+        bx2 = pm[8] * r0 + pm[9] * r1 + pm[10] * r2
+        const g0 = by0, g1 = by1, g2 = by2
+        by0 = pm[0] * g0 + pm[1] * g1 + pm[2] * g2
+        by1 = pm[4] * g0 + pm[5] * g1 + pm[6] * g2
+        by2 = pm[8] * g0 + pm[9] * g1 + pm[10] * g2
+        const b0 = bz0, b1 = bz1, b2 = bz2
+        bz0 = pm[0] * b0 + pm[1] * b1 + pm[2] * b2
+        bz1 = pm[4] * b0 + pm[5] * b1 + pm[6] * b2
+        bz2 = pm[8] * b0 + pm[9] * b1 + pm[10] * b2
+      }
+      _appendBasisX.setXYZ(bx0, bx1, bx2)
+      _appendBasisY.setXYZ(by0, by1, by2)
+      _appendBasisZ.setXYZ(bz0, bz1, bz2)
+      Quat.fromBasisInto(_appendBasisX, _appendBasisY, _appendBasisZ, this.appendRotOverride[i])
+      this.appendRotOverrideSet[i] = 1
+    }
+
+    this.computeWorldMatrices(order)
+  }
+
+  computeWorldMatrices(subset?: Int32Array): void {
     const bones = this.skeleton.bones
     const localRot = this.runtimeSkeleton.localRotations
     const localTrans = this.runtimeSkeleton.localTranslations
@@ -2624,8 +2781,15 @@ export class Model {
     // 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++) {
+    //
+    // A SUBSET is the post-physics pass (applyPhysicsAppend): the same walk over
+    // the bones that inherit from a simulated one, in the same relative order,
+    // leaving every other bone — the simulated ones above all — untouched.
+    const order = subset ?? this.deformOrder
+    const count = subset ? subset.length : boneCount
+    const override = this.appendRotOverride
+    const overrideSet = this.appendRotOverrideSet
+    for (let k = 0; k < count; k++) {
       const i = order[k]
       const b = bones[i]
 
@@ -2643,7 +2807,12 @@ export class Model {
 
         if (hasRatio) {
           if (b.appendRotate) {
-            const appendRot = localRot[appendParentIdx]
+            // The simulated parent's RECOVERED rotation when there is one — the
+            // whole point of the post-physics pass. localRotations still holds
+            // the animated pose for that bone, which is exactly what must not
+            // be inherited here.
+            const appendRot =
+              override && overrideSet && overrideSet[appendParentIdx] ? override[appendParentIdx] : localRot[appendParentIdx]
             let ax = appendRot.x, ay = appendRot.y, az = appendRot.z
             const aw = appendRot.w
             const absRatio = ratio < 0 ? -ratio : ratio

package/src/physics/physics.ts

@@ -706,6 +706,69 @@ export class RezePhysics {
   //   boneWorld = bodyWorld × bodyOffsetInverse.
   // The body pose is the render-interpolated pose between the previous and current
   // substep states (alpha = fraction into the next step), which removes fixed-step judder.
+  /**
+   * Let the bodies carrying these bones swing longer, by damping them less.
+   *
+   * DAMPING, and not solver iterations, and the difference is the whole point.
+   * Under-converging a joint does make it swing further — it also stops it ever
+   * reaching equilibrium, so the body hangs visibly low at rest. Sag and swing
+   * come as a pair there and no amount of tuning separates them. Damping does
+   * separate them: for m·x″ + c·x′ + k·x = mg the rest position is mg/k, which
+   * c does not appear in. Less damping is a longer, larger oscillation about
+   * exactly the same resting height.
+   *
+   * Scoped to the bones asked for, because it is a look and not a correction —
+   * rigs whose visible bones inherit from a simulated one (付与親) are authored
+   * against an MMD that lets them move more than a faithfully damped
+   * simulation does. Hair and skirt keep their authored damping.
+   *
+   * `scale` multiplies the AUTHORED damping: 1 restores it, 0.5 halves it,
+   * 0 leaves the body undamped and ringing. Idempotent — the authored values
+   * are snapshotted on first use, so repeated calls set rather than compound.
+   */
+  setJiggleDamping(boneIndices: number[], scale: number): void {
+    const wanted = new Set(boneIndices.filter((b) => b >= 0))
+    if (wanted.size === 0) return
+    if (!this.authoredLinDamp || !this.authoredAngDamp) {
+      this.authoredLinDamp = Float32Array.from(this.store.linearDamping)
+      this.authoredAngDamp = Float32Array.from(this.store.angularDamping)
+    }
+    const s = Math.max(0, Math.min(1, scale))
+    const boneOf = this.store.boneIndex
+    for (let i = 0; i < this.store.count; i++) {
+      const b = boneOf[i]
+      if (b < 0 || !wanted.has(b)) continue
+      this.store.linearDamping[i] = this.authoredLinDamp[i] * s
+      this.store.angularDamping[i] = this.authoredAngDamp[i] * s
+    }
+    // The factors are cached against dt, which has not changed.
+    this.world.invalidateDampingCache()
+  }
+
+  /** Authored damping, kept so setJiggleDamping sets rather than compounds. */
+  private authoredLinDamp: Float32Array | null = null
+  private authoredAngDamp: Float32Array | null = null
+
+  /**
+   * Bones whose world matrix this simulation OVERWRITES each step.
+   *
+   * The same test applyDynamicsToBones runs — a Dynamic body bound to a real
+   * bone — exposed because the pose pipeline has to know. PMX lets a bone
+   * inherit rotation from an 付与親 (append parent), and when that parent is
+   * simulated the inheritance has to consume the SIMULATED result, not the
+   * animated pose the frame started with. Nothing else can answer which bones
+   * those are: the mapping lives in this store.
+   */
+  getPhysicsDrivenBones(): number[] {
+    const out: number[] = []
+    for (let i = 0; i < this.store.count; i++) {
+      if (this.store.type[i] !== RigidbodyType.Dynamic) continue
+      const b = this.store.boneIndex[i]
+      if (b >= 0) out.push(b)
+    }
+    return out
+  }
+
   private applyDynamicsToBones(boneWorldMatrices: Mat4[], alpha: number): void {
     const N = this.store.count
     const inv = this.store.bodyOffsetInverse

package/src/physics/world.ts

@@ -45,6 +45,13 @@ export class World {
   // Per-body damping factors pow(1−damping, dt), cached because damping and
   // the fixed dt never change — two Math.pow per body per substep otherwise.
   private dampCacheDt = -1
+
+  /** Drop the cached damping factors. The cache is keyed on dt alone, because
+   *  authored damping never changed — until a rig asked for softer jiggle (see
+   *  RezePhysics.setJiggleDamping), which rewrites the store's values. */
+  invalidateDampingCache(): void {
+    this.dampCacheDt = -1
+  }
   private linDampFactor: Float32Array | null = null
   private angDampFactor: Float32Array | null = null
 

package/src/vmd-loader.ts

@@ -29,9 +29,28 @@ export interface CameraKeyframe {
   target: Vec3
   rotation: Vec3 // euler radians
   fov: number // degrees
-  interpolation: Uint8Array // 24 bytes
+  /** 24 bytes, contiguous per channel — see camera-animation.ts's `bez`.
+   *  Optional so a hand-authored keyframe does not have to know the layout;
+   *  both the sampler and the writer fall back to DEFAULT_CAMERA_INTERPOLATION.
+   *  A parsed file always carries its own. */
+  interpolation?: Uint8Array
 }
 
+/** Linear in, linear out on all six channels. 20/107 is MMD's own linear pair
+ *  (its bezier bytes run 0-127), so a keyframe written with this reads back as
+ *  a straight line in MMD rather than an ease nobody asked for. */
+export const DEFAULT_CAMERA_INTERPOLATION: Uint8Array = (() => {
+  const ip = new Uint8Array(24)
+  for (let c = 0; c < 6; c++) {
+    const b = c * 4
+    ip[b] = 20 // x1
+    ip[b + 1] = 107 // x2
+    ip[b + 2] = 20 // y1
+    ip[b + 3] = 107 // y2
+  }
+  return ip
+})()
+
 /** A VMD "IK/display" record: one moment at which chains are switched. */
 export interface IkFrame {
   frame: number

package/src/vmd-writer.ts

@@ -1,4 +1,5 @@
 import { AnimationClip, BoneInterpolation, ControlPoint } from "./animation"
+import { DEFAULT_CAMERA_INTERPOLATION, type CameraKeyframe } from "./vmd-loader"
 
 const VMD_HEADER = "Vocaloid Motion Data 0002"
 const HEADER_SIZE = 30
@@ -9,6 +10,11 @@ const BONE_FRAME_SIZE = BONE_NAME_SIZE + 4 + 12 + 16 + 64 // 111 bytes
 const MORPH_FRAME_SIZE = MORPH_NAME_SIZE + 4 + 4 // 23 bytes
 /** IK bone names get 20 bytes in the IK block, not the 15 bones get elsewhere. */
 const IK_NAME_SIZE = 20
+/** frame + distance + target(3) + rotation(3) + interpolation(24) + fov + perspective. */
+const CAMERA_FRAME_SIZE = 4 + 4 + 12 + 12 + 24 + 4 + 1 // 61 bytes
+/** What MMD stamps in the model-name field of a camera VMD. Tools sniff it to
+ *  tell a camera file from a motion at a glance, so write what they expect. */
+const CAMERA_MODEL_NAME = "\u30ab\u30e1\u30e9\u30fb\u7167\u660e"
 
 // Build a Unicode-to-Shift-JIS lookup by inverting the TextDecoder mapping.
 let shiftJISTable: Map<string, number[]> | null = null
@@ -47,22 +53,41 @@ function encodeShiftJIS(str: string): Uint8Array {
   return new Uint8Array(bytes)
 }
 
+/** Which half of a clip to write. Mirrors `Model.loadVmd`'s `tracks` option, so
+ *  a file this writer splits out is one the loader can read straight back:
+ *
+ *    "all"    bone + morph (+ IK) — one file, what MMD itself exports
+ *    "motion" bone (+ IK) only — the dance, no expressions
+ *    "morphs" morph only — an expression file (\u8868\u60c5\u30e2\u30fc\u30b7\u30e7\u30f3) to lay over a motion
+ *
+ *  IK rides with "motion" rather than "morphs" because it is bone state: which
+ *  chains solve says nothing about a face. */
+export type VmdTrackSelection = "all" | "motion" | "morphs"
+
 export class VMDWriter {
-  write(clip: AnimationClip): ArrayBuffer {
+  write(clip: AnimationClip, options?: { tracks?: VmdTrackSelection }): ArrayBuffer {
+    const tracks = options?.tracks ?? "all"
+    const wantBones = tracks !== "morphs"
+    const wantMorphs = tracks !== "motion"
+
     let totalBoneFrames = 0
-    for (const frames of clip.boneTracks.values()) {
-      totalBoneFrames += frames.length
+    if (wantBones) {
+      for (const frames of clip.boneTracks.values()) {
+        totalBoneFrames += frames.length
+      }
     }
     let totalMorphFrames = 0
-    for (const frames of clip.morphTracks.values()) {
-      totalMorphFrames += frames.length
+    if (wantMorphs) {
+      for (const frames of clip.morphTracks.values()) {
+        totalMorphFrames += frames.length
+      }
     }
 
     // IK state is stored per MOMENT, not per bone: one record lists every chain
     // and its state at that frame. So the tracks are transposed back into the
     // frames they were flattened from.
     const ikByFrame = new Map<number, { boneName: string; enabled: boolean }[]>()
-    for (const [boneName, keys] of clip.ikTracks ?? []) {
+    for (const [boneName, keys] of (wantBones ? clip.ikTracks : undefined) ?? []) {
       for (const key of keys) {
         const at = ikByFrame.get(key.frame)
         if (at) at.push({ boneName, enabled: key.enabled })
@@ -98,7 +123,7 @@ export class VMDWriter {
     offset += 4
 
     // Bone frames
-    for (const frames of clip.boneTracks.values()) {
+    for (const frames of wantBones ? clip.boneTracks.values() : []) {
       for (const kf of frames) {
         // Bone name (15 bytes, Shift-JIS)
         offset = writeFixedShiftJIS(buffer, offset, kf.boneName, BONE_NAME_SIZE)
@@ -130,7 +155,7 @@ export class VMDWriter {
     offset += 4
 
     // Morph frames
-    for (const frames of clip.morphTracks.values()) {
+    for (const frames of wantMorphs ? clip.morphTracks.values() : []) {
       for (const kf of frames) {
         // Morph name (15 bytes, Shift-JIS)
         offset = writeFixedShiftJIS(buffer, offset, kf.morphName, MORPH_NAME_SIZE)
@@ -168,8 +193,67 @@ export class VMDWriter {
 
     return buffer
   }
+
+  /**
+   * A camera VMD: the shot's own file, with no model motion in it.
+   *
+   * Bone and morph counts are written as zero rather than omitted — the camera
+   * block sits after them in the format, so a reader walking the file in order
+   * (including this package's own parseCamera) has to pass through both to
+   * reach it. Light, self-shadow and IK blocks are left off entirely; every
+   * reader bounds-checks past the camera block, and MMD is happy with a file
+   * that simply ends there.
+   *
+   * `frames` is sorted by frame on the way out: CameraAnimation binary-searches
+   * the track it loads, and an out-of-order file would sample wrong rather than
+   * fail loudly.
+   */
+  writeCamera(frames: CameraKeyframe[]): ArrayBuffer {
+    const sorted = [...frames].sort((a, b) => a.frame - b.frame)
+    const size = HEADER_SIZE + MODEL_NAME_SIZE + 4 + 4 + 4 + sorted.length * CAMERA_FRAME_SIZE
+    const buffer = new ArrayBuffer(size)
+    const view = new DataView(buffer)
+    let offset = 0
+
+    offset = writeFixedString(buffer, offset, VMD_HEADER, HEADER_SIZE)
+    offset = writeFixedShiftJIS(buffer, offset, CAMERA_MODEL_NAME, MODEL_NAME_SIZE)
+
+    view.setUint32(offset, 0, true) // bone frame count
+    offset += 4
+    view.setUint32(offset, 0, true) // morph frame count
+    offset += 4
+    view.setUint32(offset, sorted.length, true)
+    offset += 4
+
+    for (const kf of sorted) {
+      view.setUint32(offset, kf.frame, true); offset += 4
+      view.setFloat32(offset, kf.distance, true); offset += 4
+      view.setFloat32(offset, kf.target.x, true); offset += 4
+      view.setFloat32(offset, kf.target.y, true); offset += 4
+      view.setFloat32(offset, kf.target.z, true); offset += 4
+      // Euler radians, as the loader reads them.
+      view.setFloat32(offset, kf.rotation.x, true); offset += 4
+      view.setFloat32(offset, kf.rotation.y, true); offset += 4
+      view.setFloat32(offset, kf.rotation.z, true); offset += 4
+      // 24 bytes, contiguous per channel — see camera-animation.ts's `bez`.
+      // Short or missing tables are padded with a linear default rather than
+      // writing junk: a hand-built keyframe should not have to know the layout.
+      const ip = new Uint8Array(24)
+      ip.set(DEFAULT_CAMERA_INTERPOLATION)
+      if (kf.interpolation) ip.set(kf.interpolation.subarray(0, 24))
+      new Uint8Array(buffer, offset, 24).set(ip)
+      offset += 24
+      // fov is degrees, and an integer in the file — MMD's own field is u32.
+      view.setUint32(offset, Math.max(0, Math.round(kf.fov)), true); offset += 4
+      view.setUint8(offset, 0) // 0 = perspective
+      offset += 1
+    }
+
+    return buffer
+  }
 }
 
+
 function writeFixedString(buffer: ArrayBuffer, offset: number, str: string, maxBytes: number): number {
   const bytes = new Uint8Array(buffer, offset, maxBytes)
   bytes.fill(0)