reze-engine 0.55.1 → 0.55.3

package/src/engine.ts

@@ -380,6 +380,24 @@ export type ModelTransform = {
   visible: boolean
 }
 
+/** How a model rides another — MMD's 外部親 (outside parent). See setModelParent. */
+export type ModelAttachment = {
+  /** Model key of the parent. */
+  model: string
+  /** Bone on the parent. A name the parent's rig lacks rides the parent's root. */
+  bone: string
+}
+
+/** The attachment as the engine keeps it: the record plus the two matrices the
+ *  per-frame placement needs, allocated once per attach rather than per frame. */
+type Attachment = ModelAttachment & {
+  /** Where the child's origin sits in the bone's space (position · rotation). */
+  offsetMatrix: Float32Array
+  /** The root the child is posed under this frame. Handed to Model.setRootParent
+   *  BY REFERENCE and refilled every frame; see placeAttached. */
+  rootMatrix: Float32Array
+}
+
 type SunOptions = {
   /** Linear color of the sun lamp (Blender: Light > Color). */
   color?: Vec3
@@ -778,6 +796,18 @@ interface ModelInstance {
    * plane into isStage would have made adding a title graphic delete the ground.
    */
   isPlane: boolean
+  /**
+   * A PROP: a PMX object a character holds or wears — a microphone, a fan, a
+   * sword. The third answer beside stage and plane. It keeps what a cast member
+   * has that scenery does not (physics, outlines, its own clip) and drops what
+   * makes one a performer: no effect subject id, no seeding of the scene clock,
+   * no bone picking. Like a card it leaves the floor alone. See addProp.
+   */
+  isProp: boolean
+  /** Who this model hangs from, or null. Any model can: a prop by design, a
+   *  card for a sign in her hand, a second character for a mascot on her
+   *  shoulder. See setModelParent. */
+  parent: Attachment | null
   /** This card's texture is rewritten every frame, so it is allocated with no
    *  mip chain — rebuilding one per frame is a pass per level per card, and is
    *  what a moving card was mostly costing. See setPlaneFrame. */
@@ -1510,6 +1540,13 @@ export class Engine {
   // tone (bottom). Stand-in for MMD's toon01–10.bmp, which we can't ship.
   private defaultToonRampTexture!: GPUTexture
   private groundShadowPipeline!: GPURenderPipeline
+  /** The soft-edge variant, built the first time a scene asks for one. Null while
+   *  no scene has, which is most of them — a pipeline nobody draws with is still
+   *  a shader compile at load. */
+  private groundShadowSoftPipeline: GPURenderPipeline | null = null
+  /** How the ground's own pipeline is chosen, kept beside the uniform that sets
+   *  it so the draw does not have to read the buffer back. */
+  private groundSoft = false
   private groundShadowBindGroupLayout!: GPUBindGroupLayout
   private outlinePipeline!: GPURenderPipeline
   private selectedMaterial: { modelName: string; materialName: string } | null = null
@@ -4963,7 +5000,7 @@ export class Engine {
     for (const inst of this.modelInstances.values()) {
       // Neither a stage nor a plane is a performer, so neither is a subject an
       // effect can follow.
-      if (!inst.model.visible || inst.isStage || inst.isPlane) continue
+      if (!inst.model.visible || inst.isStage || inst.isPlane || inst.isProp) continue
       const model = inst.model
       const matrices = model.getWorldMatrices()
       if (matrices.length === 0) continue
@@ -6068,14 +6105,9 @@ export class Engine {
         { binding: 12, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float" } },
       ],
     })
-    const groundShadowShader = this.device.createShaderModule({
-      label: "ground shadow",
-      code: groundShaderWgsl(),
-    })
-    this.groundShadowPipeline = this.createRenderPipeline({
+    this.groundShadowPipelineDesc = {
       label: "ground shadow pipeline",
       layout: this.device.createPipelineLayout({ bindGroupLayouts: [this.groundShadowBindGroupLayout] }),
-      shaderModule: groundShadowShader,
       // Slot 0 only — the ground has no skinning, and declaring the full
       // 3-slot layout while renderGround binds one buffer is a WebGPU
       // validation error that invalidates the whole command buffer.
@@ -6083,7 +6115,8 @@ export class Engine {
       fragmentTargets: sceneTargetsFor("ground", this.sceneFormats),
       cullMode: "back",
       depthStencil: { format: this.depthFormat, depthWriteEnabled: true, depthCompare: this.depthAhead },
-    })
+    }
+    this.groundShadowPipeline = this.buildGroundPipeline(false)
 
     // Outline: group 0 = per-frame (camera), group 1 = per-instance (skinMats), group 2 = per-material (edge uniforms)
     this.outlinePerFrameBindGroupLayout = this.device.createBindGroupLayout({
@@ -8005,7 +8038,7 @@ export class Engine {
       // is first in insertion order and was seeding this clock with its own
       // permanent zero. In a scene with a stage, a camera VMD therefore sampled
       // frame 0 forever and the shot never moved.
-      if (inst.isStage || inst.isPlane) continue
+      if (inst.isStage || inst.isPlane || inst.isProp) continue
       const p = inst.model.getAnimationProgress()
       if (p.playing || p.paused) return p.current
       // Otherwise the first cast member that actually HAS a clip: one still at
@@ -8457,6 +8490,16 @@ export class Engine {
     return model
   }
 
+  /** loadModel's folder/zip path for a prop. See addProp. */
+  async loadProp(
+    name: string,
+    options: LoadModelFromFilesOptions & { transform?: Partial<ModelTransform> },
+  ): Promise<Model> {
+    const { model, pmxKey, reader } = await this.openPmxFromFiles(name, options)
+    await this.addProp(model, pmxKey, { name, transform: options.transform, assetReader: reader })
+    return model
+  }
+
   /** Read a PMX out of a picked folder / expanded zip. Shared by loadModel and
    *  loadStage so the file-map and path handling exist in exactly one place. */
   private async openPmxFromFiles(
@@ -8482,7 +8525,7 @@ export class Engine {
     pmxPath: string,
     name?: string,
     assetReader?: AssetReader,
-    options?: { stage?: boolean; plane?: boolean; dynamic?: boolean },
+    options?: { stage?: boolean; plane?: boolean; dynamic?: boolean; prop?: boolean },
   ): Promise<string> {
     const requested = name ?? model.name
     let key = requested
@@ -8501,6 +8544,7 @@ export class Engine {
       options?.stage ?? false,
       options?.plane ?? false,
       options?.dynamic ?? false,
+      options?.prop ?? false,
     )
     return key
   }
@@ -8534,6 +8578,28 @@ export class Engine {
     return key
   }
 
+  /**
+   * Add a PMX as a PROP: an object a character holds or wears rather than a
+   * performer or the environment. A microphone, a fan, a sword, an umbrella.
+   *
+   * It keeps what makes a held thing look right — physics (the charm on a phone
+   * strap swings), toon outlines, its own clip if it has one — and drops what
+   * makes a model a cast member: no effect subject id, so a silhouette effect
+   * still outlines HER and not the mic; no seeding of the scene clock; no bone
+   * picking in the pose editor. Like a card it leaves the built-in ground
+   * alone, which is the one thing a stage does that a prop must not. Usually
+   * hung from a bone with setModelParent, though it can stand on its own.
+   */
+  async addProp(
+    model: Model,
+    pmxPath: string,
+    options?: { name?: string; transform?: Partial<ModelTransform>; assetReader?: AssetReader },
+  ): Promise<string> {
+    const key = await this.addModel(model, pmxPath, options?.name, options?.assetReader, { prop: true })
+    if (options?.transform) this.setModelTransform(key, options.transform)
+    return key
+  }
+
   /**
    * Put a picture in the scene as a flat card.
    *
@@ -8789,8 +8855,14 @@ export class Engine {
     // Per-group StyleUniforms buffers aren't in gpuBuffers (allocated post-load).
     for (const install of inst.styleGroups.values()) this.destroyInstall(install)
     this.modelInstances.delete(name)
+    // Whatever hung from it stands on its own now, at identity — the same
+    // place a detach leaves a model.
+    for (const other of this.modelInstances.values()) {
+      if (other.parent?.model === name) this.setModelParent(other.name, null)
+    }
     this.cullListDirty = true
     this.bundlesDirty = true
+    this.updateOrderDirty = true
   }
 
   getModelNames(): string[] {
@@ -8801,6 +8873,136 @@ export class Engine {
     return this.modelInstances.get(name)?.model ?? null
   }
 
+  /**
+   * Hang a model from a bone of another — MMD's 外部親 (outside parent).
+   *
+   * Every frame, after the parent has been posed and simulated, the child's
+   * root bones are placed at that bone with `offset` composed on top, and only
+   * then is the child posed itself. The placement enters through the child's
+   * BONES rather than its model transform (Model.setRootParent): physics runs
+   * in model space, so a root moved by the transform would have a charm on a
+   * phone strap feel gravity swing with the hand, while a root moved by the
+   * skeleton keeps down down. It also puts the child's own clip on top of the
+   * ride, as MMD does — an umbrella that spins keeps spinning in the hand.
+   *
+   * While attached the child's position and rotation are held at identity and
+   * setModelTransform ignores them; scale still applies, and is folded into
+   * the placement so the offset stays in the parent's units. Detaching leaves
+   * the model at identity until the host places it again.
+   *
+   * A bone the parent lacks rides the parent's root, which is what camera
+   * follow does with an unknown name. Returns false for an unknown model, a
+   * missing parent, or a model asked to ride itself.
+   */
+  setModelParent(
+    name: string,
+    parent: string | null,
+    bone = "全ての親",
+    offset?: { position?: Vec3; rotation?: Quat },
+  ): boolean {
+    const inst = this.modelInstances.get(name)
+    if (!inst) return false
+    if (parent === null) {
+      if (inst.parent) {
+        inst.parent = null
+        inst.model.setRootParent(null)
+        inst.skinMatricesDirty = true
+        this.updateOrderDirty = true
+      }
+      return true
+    }
+    if (parent === name || !this.modelInstances.has(parent)) return false
+    const p = offset?.position ?? new Vec3(0, 0, 0)
+    const r = offset?.rotation ?? Quat.identity()
+    const offsetMatrix = inst.parent?.offsetMatrix ?? new Float32Array(16)
+    Mat4.fromPositionRotationScaleInto(p.x, p.y, p.z, r.x, r.y, r.z, r.w, 1, offsetMatrix)
+    // Identity until the first frame fills it: a physics reset between now and
+    // then re-poses the model, and a zero matrix would fold it to a point.
+    const rootMatrix = inst.parent?.rootMatrix ?? new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1])
+    inst.parent = { model: parent, bone, offsetMatrix, rootMatrix }
+    inst.model.setPosition(new Vec3(0, 0, 0))
+    inst.model.setRotation(Quat.identity())
+    inst.model.setRootParent(rootMatrix)
+    inst.skinMatricesDirty = true
+    this.updateOrderDirty = true
+    return true
+  }
+
+  /** What a model hangs from, or null. */
+  getModelParent(name: string): ModelAttachment | null {
+    const att = this.modelInstances.get(name)?.parent
+    return att ? { model: att.model, bone: att.bone } : null
+  }
+
+  /**
+   * The root an attached model is posed under this frame: the parent's
+   * placement, its bone as posed and simulated, then the offset.
+   *
+   * The translation is divided by the child's own scale. The skin bake
+   * multiplies the child's scale back on outside the skeleton, and a uniform
+   * scale commutes with the rotation, so this is exactly what lands the child
+   * at the bone in world units while its mesh still comes out scaled.
+   */
+  private placeAttached(inst: ModelInstance): void {
+    const att = inst.parent!
+    const parent = this.modelInstances.get(att.model)
+    if (!parent) {
+      this.setModelParent(inst.name, null)
+      return
+    }
+    const out = att.rootMatrix
+    const tmp = this.attachScratch
+    const root = parent.model.getRootMatrix()
+    const bone = parent.model.getBoneWorldMatrix(att.bone)
+    if (bone) {
+      Mat4.multiplyArrays(root, 0, bone, 0, tmp, 0)
+      Mat4.multiplyArrays(tmp, 0, att.offsetMatrix, 0, out, 0)
+    } else {
+      Mat4.multiplyArrays(root, 0, att.offsetMatrix, 0, out, 0)
+    }
+    const s = inst.model.scale
+    if (s > 0 && s !== 1) {
+      const k = 1 / s
+      out[12] *= k
+      out[13] *= k
+      out[14] *= k
+    }
+  }
+  private readonly attachScratch = new Float32Array(16)
+
+  /** Instances in pose order: a parent before every model hanging from it, so
+   *  a child reads the bone as posed and simulated THIS frame. Insertion order
+   *  otherwise. Rebuilt when a model is added, removed or re-parented. */
+  private updateOrder: ModelInstance[] = []
+  private updateOrderDirty = true
+  private instancesInUpdateOrder(): ModelInstance[] {
+    if (!this.updateOrderDirty) return this.updateOrder
+    const placed = new Set<string>()
+    const order: ModelInstance[] = []
+    let pending = Array.from(this.modelInstances.values())
+    while (pending.length > 0) {
+      const rest: ModelInstance[] = []
+      for (const inst of pending) {
+        const p = inst.parent?.model
+        if (p === undefined || placed.has(p) || !this.modelInstances.has(p)) {
+          order.push(inst)
+          placed.add(inst.name)
+        } else rest.push(inst)
+      }
+      if (rest.length === pending.length) {
+        // A cycle: nothing left can go first. They pose in insertion order and
+        // each reads the other's previous frame, which is the best a cycle gets.
+        console.warn(`[reze] attachment cycle: ${rest.map((r) => r.name).join(" → ")}`)
+        order.push(...rest)
+        break
+      }
+      pending = rest
+    }
+    this.updateOrder = order
+    this.updateOrderDirty = false
+    return order
+  }
+
   /**
    * Place a model in the scene — position, rotation, uniform scale, visibility. The
    * transform is a root offset baked into skinning (moves the whole rig), so it composes
@@ -8812,8 +9014,11 @@ export class Engine {
     const inst = this.modelInstances.get(name)
     const model = inst?.model
     if (!inst || !model) return
-    if (transform.position) model.setPosition(transform.position)
-    if (transform.rotation) model.setRotation(transform.rotation)
+    // An attached model is placed by its parent's bone; its own position and
+    // rotation are held at identity so the ride is the whole placement (see
+    // setModelParent). Scale and visibility are still its own.
+    if (transform.position && !inst.parent) model.setPosition(transform.position)
+    if (transform.rotation && !inst.parent) model.setRotation(transform.rotation)
     if (transform.scale !== undefined) model.setScale(transform.scale)
     if (transform.visible !== undefined) model.setVisible(transform.visible)
     // The root transform is baked into the skin matrices, so moving a model is a
@@ -8934,7 +9139,7 @@ export class Engine {
 
     for (const inst of this.modelInstances.values()) {
       if (options.modelName !== undefined && inst.name !== options.modelName) continue
-      if (inst.isStage || inst.isPlane) continue
+      if (inst.isStage || inst.isPlane || inst.isProp) continue
       const bones = inst.model.getSkeleton().bones
       this.bonePickScratch = boneMarkerPositions(inst.model, this.bonePickScratch)
       const pos = this.bonePickScratch
@@ -9001,7 +9206,7 @@ export class Engine {
 
     for (const inst of this.modelInstances.values()) {
       if (options.modelName !== undefined && inst.name !== options.modelName) continue
-      if (inst.isStage || inst.isPlane) continue
+      if (inst.isStage || inst.isPlane || inst.isProp) continue
       const model = inst.model
       const { positions } = model.getGeometry()
       const count = positions.length / 3
@@ -9192,6 +9397,59 @@ export class Engine {
     else inst.hiddenMaterials.add(materialName)
   }
 
+  /**
+   * Push a colour/shading edit straight into a material's own uniform buffer —
+   * the same block createMaterialUniformBuffer wrote at load, offset for
+   * offset. A single write per call, on the fields that actually moved, so
+   * dragging one slider does not touch the other eleven.
+   *
+   * UNGROUPED materials only. A grouped material renders through its style
+   * group's own compiled graph (setupPipelines' neutral/DEFAULT_GRAPH path is
+   * what reads this buffer, and a grouped material never runs it) — the call
+   * still writes the bytes, they are simply never sampled, which would look
+   * like the edit silently failing. Callers check groupsByModel first and this
+   * quietly no-ops rather than assume that check was made, since a document
+   * edit landing to the WRONG channel (the group's own colour input) would be
+   * a worse failure than one that does nothing.
+   *
+   * Structural fields — anything that changes which draw bucket a material is
+   * in, or which texture it binds — are NOT here: alpha crossing the 1.0
+   * opaque/transparent line, edge on/off, a texture swap, all need the draw
+   * list or the bind group rebuilt, not a uniform write. Those get their own
+   * call when something needs them.
+   */
+  setMaterialUniforms(
+    modelName: string,
+    materialName: string,
+    patch: {
+      diffuse?: readonly [number, number, number, number]
+      specular?: readonly [number, number, number]
+      specularPower?: number
+      ambient?: readonly [number, number, number]
+    },
+  ): boolean {
+    const inst = this.modelInstances.get(modelName)
+    if (!inst) return false
+    const materials = inst.model.getMaterials()
+    const index = materials.findIndex((m) => m.name === materialName)
+    if (index < 0) return false
+    const buffer = inst.materialUniformBuffers[index]
+    if (!buffer) return false
+    if (patch.diffuse) {
+      this.device.queue.writeBuffer(buffer, 0, new Float32Array(patch.diffuse))
+    }
+    if (patch.ambient) {
+      this.device.queue.writeBuffer(buffer, 16, new Float32Array(patch.ambient))
+    }
+    if (patch.specularPower !== undefined) {
+      this.device.queue.writeBuffer(buffer, 28, new Float32Array([patch.specularPower]))
+    }
+    if (patch.specular) {
+      this.device.queue.writeBuffer(buffer, 32, new Float32Array(patch.specular))
+    }
+    return true
+  }
+
   isMaterialVisible(modelName: string, materialName: string): boolean {
     const inst = this.modelInstances.get(modelName)
     return inst ? !inst.hiddenMaterials.has(materialName) : false
@@ -9318,12 +9576,18 @@ export class Engine {
   private updateInstances(deltaTime: number): void {
     let animMs = 0
     let physicsMs = 0
-    this.forEachInstance((inst) => {
+    for (const inst of this.instancesInUpdateOrder()) {
       const tAnim = performance.now()
+      // An attached model is placed from its parent's bone as posed and
+      // simulated THIS frame — the order guarantees the parent came first —
+      // and only then posed itself, so its clip and physics ride the placement.
+      const attached = inst.parent !== null
+      if (attached) this.placeAttached(inst)
       // A stage never solves IK — nothing drives its chains — and skips the pose
       // pass entirely while it is idle. Morph changes still come through, since
-      // that is the one thing a stage's controls do move.
-      const stageIdle = (inst.isStage || inst.isPlane) && inst.model.isIdle()
+      // that is the one thing a stage's controls do move. A prop idles the same
+      // way while it stands on its own; hung from a hand it moves every frame.
+      const stageIdle = (inst.isStage || inst.isPlane || inst.isProp) && !attached && inst.model.isIdle()
       let verticesChanged = false
       if (!stageIdle) {
         verticesChanged = inst.model.update(deltaTime, inst.isStage || inst.isPlane ? false : this.ikEnabled)
@@ -9367,7 +9631,7 @@ export class Engine {
         physicsMs += performance.now() - tPhys
       }
       if (inst.vertexBufferNeedsUpdate) this.updateVertexBuffer(inst)
-    })
+    }
     this.frameAnimMsRaw = animMs
     this.framePhysicsMsRaw = physicsMs
     const EMA = 0.1
@@ -10324,6 +10588,7 @@ export class Engine {
     isStage = false,
     isPlane = false,
     dynamicTexture = false,
+    isProp = false,
   ): Promise<void> {
     const vertices = model.getVertices()
     const skinning = model.getSkinning()
@@ -10469,6 +10734,8 @@ export class Engine {
       pickDrawCalls: [],
       isStage,
       isPlane,
+      isProp,
+      parent: null,
       dynamicTexture,
       // Seeded true: the bind pose has to reach the GPU once before any frame.
       skinMatricesDirty: true,
@@ -10497,6 +10764,7 @@ export class Engine {
     this.modelInstances.set(name, inst)
     this.cullListDirty = true
     this.bundlesDirty = true
+    this.updateOrderDirty = true
   }
 
   // Build the per-model GPU vertex-morph state. Returns null (and leaves the model on the
@@ -10642,6 +10910,28 @@ export class Engine {
     this.device.queue.writeBuffer(this.groundIndexBuffer, 0, indices)
   }
 
+  /** Everything about the ground's pipeline except which shadow variant it
+   *  compiles, so the two are built from one description and cannot drift. */
+  private groundShadowPipelineDesc!: Omit<Parameters<Engine["createRenderPipeline"]>[0], "shaderModule">
+
+  private buildGroundPipeline(soft: boolean): GPURenderPipeline {
+    return this.createRenderPipeline({
+      ...this.groundShadowPipelineDesc,
+      label: soft ? "ground shadow pipeline (soft)" : "ground shadow pipeline",
+      shaderModule: this.device.createShaderModule({
+        label: soft ? "ground shadow (soft)" : "ground shadow",
+        code: groundShaderWgsl(soft),
+      }),
+    })
+  }
+
+  /** Built on the first frame that actually needs it. A shader compile costs
+   *  load time, and the overwhelming majority of scenes never soften a shadow. */
+  private ensureGroundSoftPipeline(): GPURenderPipeline {
+    if (!this.groundShadowSoftPipeline) this.groundShadowSoftPipeline = this.buildGroundPipeline(true)
+    return this.groundShadowSoftPipeline
+  }
+
   private createShadowGroundResources(opts: {
     diffuseColor: Vec3
     fadeStart: number
@@ -10699,6 +10989,9 @@ export class Engine {
     // gb[18] — shadow edge softness. Was padding; the shader reads it as the
     // Vogel disk's radius, and 0 takes the sharp nine-tap path unchanged.
     gb[18] = Math.min(Math.max(shadowSoftness, 0), 1)
+    // Which variant the draw picks. Zero is the sharp shader, which is the one
+    // that existed before softness did.
+    this.groundSoft = gb[18] > 0
     // gb[17] — does the FAR cascade hold anything?
     //
     // It holds something only when a stage is loaded; that is what it exists for
@@ -11398,7 +11691,7 @@ export class Engine {
     // hasGround is left alone: remove the stage and the ground comes back.
     if (this.groundIsSuppressed()) return
     if (!this.hasGround || !this.groundVertexBuffer || !this.groundIndexBuffer || !this.groundDrawCall) return
-    pass.setPipeline(this.groundShadowPipeline)
+    pass.setPipeline(this.groundSoft ? this.ensureGroundSoftPipeline() : this.groundShadowPipeline)
     pass.setVertexBuffer(0, this.groundVertexBuffer)
     pass.setIndexBuffer(this.groundIndexBuffer, "uint16")
     pass.setBindGroup(0, this.groundDrawCall.bindGroup)
@@ -13854,7 +14147,7 @@ export class Engine {
       // serves.
       let n = 0
       this.forEachInstance((inst) => {
-        if (n >= MAX_EFFECT_SUBJECTS || inst.isStage || inst.isPlane) return
+        if (n >= MAX_EFFECT_SUBJECTS || inst.isStage || inst.isPlane || inst.isProp) return
         const m = inst.model
         // The model transform is only where the model was PLACED. A motion moves
         // the character by animating bones, so an effect anchored to the

package/src/index.ts

@@ -14,6 +14,7 @@ export {
   type MaterialPreset,
   type MaterialPresetMap,
   type ModelTransform,
+  type ModelAttachment,
   type GizmoDragEvent,
   type GizmoDragCallback,
   type GizmoDragKind,

package/src/model.ts

@@ -315,6 +315,38 @@ export class Model {
     this._visible = visible
   }
 
+  /** Hang the rig's root bones from `matrix` (model space, column-major 16
+   *  floats), or from nothing. The engine drives this every frame for an
+   *  attached model; the matrix is read at the next world pass, not copied. */
+  setRootParent(matrix: Float32Array | null): void {
+    this.rootParent = matrix
+    if (matrix) {
+      const root = this.skeleton.bones.find((b) => b.parentIndex < 0)
+      this.primaryRootBind = root ? [root.bindTranslation[0], root.bindTranslation[1], root.bindTranslation[2]] : [0, 0, 0]
+    }
+  }
+
+  getRootParent(): Float32Array | null {
+    return this.rootParent
+  }
+
+  /** The placement matrix (position · rotation · scale) the skin bake composes
+   *  onto every bone. Rebuilt lazily, the way getSkinMatrices does it. */
+  getRootMatrix(): Float32Array {
+    this.refreshRootMatrix()
+    return this.rootMatrixValues
+  }
+
+  private refreshRootMatrix(): void {
+    if (!this.rootMatrixDirty) return
+    const p = this._position, r = this._rotation, s = this._scale
+    Mat4.fromPositionRotationScaleInto(p.x, p.y, p.z, r.x, r.y, r.z, r.w, s, this.rootMatrixValues)
+    this.rootIsIdentity =
+      p.x === 0 && p.y === 0 && p.z === 0 &&
+      r.x === 0 && r.y === 0 && r.z === 0 && r.w === 1 && s === 1
+    this.rootMatrixDirty = false
+  }
+
   private vertexData: Float32Array<ArrayBuffer>
   private baseVertexData: Float32Array<ArrayBuffer> // Original vertex data before morphing
   private vertexCount: number
@@ -383,6 +415,21 @@ export class Model {
   private rootMatrixValues: Float32Array = new Float32Array([1,0,0,0, 0,1,0,0, 0,0,1,0, 0,0,0,1])
   private rootMatrixDirty: boolean = false
   private rootIsIdentity: boolean = true
+  /** What every parentless bone hangs from — MMD's 外部親 (outside parent).
+   *  Model space, so the pose pipeline, IK and physics all see it: a prop bound
+   *  to a hand is moved by its BONES, and gravity keeps pointing down while the
+   *  hand tilts. Null is the ordinary rig, rooted at the model's own origin.
+   *  Written per frame by the engine from the parent's posed bone; see
+   *  Engine.setModelParent. */
+  private rootParent: Float32Array | null = null
+  /** The bind position of the PRIMARY root — the first parentless bone, 全ての親
+   *  by convention. Under a root parent that bone sits exactly ON the parent
+   *  bone, as MMD's 外部親 does, so its bind position is taken off every root's
+   *  local matrix: the primary lands at the parent, the other roots keep their
+   *  layout relative to it. Without this the MODEL ORIGIN went to the parent
+   *  bone, and a prop rigged with its one bone at the mesh's centre hung that
+   *  far away from the hand. */
+  private primaryRootBind: [number, number, number] = [0, 0, 0]
 
   // Cached skin matrices array to avoid allocations in getSkinMatrices
   private skinMatricesArray?: Float32Array
@@ -984,6 +1031,14 @@ export class Model {
     return this.clipApplySuspended
   }
 
+  /** A bone's posed matrix — model space, column-major, the live array rather
+   *  than a copy. Null for a name this rig does not have. */
+  getBoneWorldMatrix(boneName: string): Float32Array | null {
+    const idx = this.runtimeSkeleton.nameIndex[boneName]
+    if (idx === undefined || idx < 0) return null
+    return this.runtimeSkeleton.worldMatrices[idx].values
+  }
+
   // World bone origin (world matrix col3); unknown name → null
   getBoneWorldPosition(boneName: string): Vec3 | null {
     const idx = this.runtimeSkeleton.nameIndex[boneName]
@@ -1238,14 +1293,7 @@ export class Model {
     const skinMatrices = this.skinMatricesArray
 
     // Rebuild root matrix + cache identity-shortcut flag only when pos/rot changed.
-    if (this.rootMatrixDirty) {
-      const p = this._position, r = this._rotation, s = this._scale
-      Mat4.fromPositionRotationScaleInto(p.x, p.y, p.z, r.x, r.y, r.z, r.w, s, this.rootMatrixValues)
-      this.rootIsIdentity =
-        p.x === 0 && p.y === 0 && p.z === 0 &&
-        r.x === 0 && r.y === 0 && r.z === 0 && r.w === 1 && s === 1
-      this.rootMatrixDirty = false
-    }
+    this.refreshRootMatrix()
 
     if (this.rootIsIdentity) {
       // skinMatrix = worldMatrix × inverseBindMatrix
@@ -2644,6 +2692,12 @@ export class Model {
     if (b.parentIndex >= 0) {
       const parentMat = worldMats[b.parentIndex]
       Mat4.multiplyArrays(parentMat.values, 0, localMVals, 0, worldMat.values, 0)
+    } else if (this.rootParent) {
+      const pr = this.primaryRootBind
+      localMVals[12] -= pr[0]
+      localMVals[13] -= pr[1]
+      localMVals[14] -= pr[2]
+      Mat4.multiplyArrays(this.rootParent, 0, localMVals, 0, worldMat.values, 0)
     } else {
       worldMat.values.set(localMVals)
     }
@@ -2801,6 +2855,8 @@ export class Model {
     // leaving every other bone — the simulated ones above all — untouched.
     const order = subset ?? this.deformOrder
     const count = subset ? subset.length : boneCount
+    const rootParent = this.rootParent
+    const primaryRootBind = this.primaryRootBind
     const override = this.appendRotOverride
     const overrideSet = this.appendRotOverrideSet
     for (let k = 0; k < count; k++) {
@@ -2875,6 +2931,13 @@ export class Model {
       if (b.parentIndex >= 0) {
         const parentMat = worldMats[b.parentIndex]
         Mat4.multiplyArrays(parentMat.values, 0, localMVals, 0, worldMat.values, 0)
+      } else if (rootParent) {
+        // The primary root's bind position comes off every root, so the primary
+        // sits ON the parent bone. See primaryRootBind.
+        localMVals[12] -= primaryRootBind[0]
+        localMVals[13] -= primaryRootBind[1]
+        localMVals[14] -= primaryRootBind[2]
+        Mat4.multiplyArrays(rootParent, 0, localMVals, 0, worldMat.values, 0)
       } else {
         worldMat.values.set(localMVals)
       }