@solidrt/3d 0.0.58 → 0.0.60

package/src/mixer.ts

@@ -9,9 +9,11 @@
 // (getTransform) and may overwrite them (root-motion strips, skeleton
 // copies), last write wins, palettes and uModel following at the frame's
 // flush. A channel the active clips do not animate keeps the node's
-// current pose. Playing requires the model to be IN A SCENE (players
-// bind live arena nodes); removing it drops the players, and a re-added
-// model plays again from play().
+// current pose. A weights channel (morph targets) plays the same way,
+// into the owning node's weights register (`getMorphWeights` reads it),
+// blended across players like a TRS path. Playing requires the model
+// to be IN A SCENE (players bind live arena nodes); removing it drops
+// the players, and a re-added model plays again from play().
 //
 // Root motion: a locomotion clip translates its root, which is what a game
 // consumes to move the character and what sends a viewer's model through
@@ -44,7 +46,7 @@ import * as spatial from "flux:spatial"
 import type { NodeId } from "flux:spatial"
 import { on } from "srt:events"
 import type { ModelChannel, ModelClip } from "./gltf.ts"
-import { sampleChannel } from "./clip.ts"
+import { channelElements, sampleChannel } from "./clip.ts"
 import type { Vec3 } from "./math.ts"
 import type { Model } from "./model.ts"
 
@@ -111,8 +113,10 @@ export type Mixer = {
 }
 
 // The packed-clip codes of flux:spatial's createClip layout.
-const PATH_CODE = { position: 0, rotation: 1, scale: 2 } as const
+const PATH_CODE = { position: 0, rotation: 1, scale: 2, weights: 3 } as const
 const INTERP_CODE = { step: 0, linear: 1, cubic: 2 } as const
+// Meta words per channel in that layout.
+const CLIP_META_WORDS = 5
 
 // Net root x/z drift, as a fraction of the model's rest height, above
 // which a clip counts as travelling. Measured on a stock rig: run cycles
@@ -141,16 +145,18 @@ on("spatialRootMotion", (event: { player: number; x: number; y: number; z: numbe
 
 /** Pack channels into the core's createClip layout. */
 function registerClip(duration: number, channels: ModelChannel[]): number {
-  let meta = new Uint32Array(channels.length * 4)
+  let meta = new Uint32Array(channels.length * CLIP_META_WORDS)
   let timeCount = 0
   let valueCount = 0
   channels.forEach((c, i) => {
     // Target slot = channel index: the player's target table below is
     // built in the same order.
-    meta[i * 4] = i
-    meta[i * 4 + 1] = PATH_CODE[c.path]
-    meta[i * 4 + 2] = INTERP_CODE[c.interpolation]
-    meta[i * 4 + 3] = c.times.length
+    let at = i * CLIP_META_WORDS
+    meta[at] = i
+    meta[at + 1] = PATH_CODE[c.path]
+    meta[at + 2] = INTERP_CODE[c.interpolation]
+    meta[at + 3] = c.times.length
+    meta[at + 4] = channelElements(c)
     timeCount += c.times.length
     valueCount += c.values.length
   })
@@ -211,7 +217,7 @@ function axisQuat(up: Vec3, angle: number): [number, number, number, number] {
  * linear or step channel is returned as is). */
 function linearized(c: ModelChannel, duration: number): ModelChannel {
   if (c.interpolation !== "cubic") return c
-  let elements = c.path === "rotation" ? 4 : 3
+  let elements = channelElements(c)
   let keys = Math.max(2, Math.ceil(duration * YAW_HOLD_RESAMPLE_HZ) + 1)
   let times = new Float32Array(keys)
   let values = new Float32Array(keys * elements)
@@ -249,7 +255,7 @@ function holdYaw(rotation: ModelChannel, duration: number, up: Vec3): ModelChann
 // Floats per key and the value's offset within a key: a key's value sits
 // at [in, value, out] for cubic keys; rotations are four floats.
 function keyLayout(c: ModelChannel): { stride: number; mid: number } {
-  let elements = c.path === "rotation" ? 4 : 3
+  let elements = channelElements(c)
   let cubic = c.interpolation === "cubic"
   return { stride: cubic ? elements * 3 : elements, mid: cubic ? elements : 0 }
 }
@@ -369,14 +375,21 @@ export function createMixer(model: Model, mixerOpts: MixerOptions = {}): Mixer {
   let rootAcc = { position: [0, 0, 0] as [number, number, number], yaw: 0 }
   // Channel targets resolve at play: clips index the model's node table,
   // and the arena ids are per scene-entry, so a re-added model binds
-  // fresh ones.
+  // fresh ones. A weights channel targets the node's weights register
+  // (the glTF node owning its mesh's morph targets, model.ts); its key
+  // width must be the node's target count.
   let targetsFor = (clip: ModelClip): NodeId[] =>
     clip.channels.map((c) => {
       let entry = model.nodes[c.node]
       if (entry === undefined) throw new Error("createMixer: clip '" + clip.name + "' targets a missing node " + c.node)
       let id = entry.node._node
       if (id === null) throw new Error("play: the model must be in a scene (add() it first) before clips can play")
-      entry.node._native = true
+      if (c.path === "weights") {
+        let targets = entry.node._morph?.names.length ?? 0
+        if (channelElements(c) !== targets) {
+          throw new Error("play: clip '" + clip.name + "' has " + channelElements(c) + " weights per key for node '" + entry.name + "' with " + targets + " morph targets")
+        }
+      } else entry.node._native = true
       return id
     })
 

package/src/model-file.ts

@@ -10,7 +10,8 @@
 // directly. Images travel as their encoded files (PNG/JPEG bytes).
 
 import type { ModelChannel, ModelData, ModelMaterial, ModelNode, ModelSkin } from "./gltf.ts"
-import { layoutStride } from "./geometry.ts"
+import { layoutStride, vertexView, VERTEX_FORMATS } from "./geometry.ts"
+import type { VertexAttribute } from "@solidrt/core/gpu"
 import type { VertexLayout } from "./geometry.ts"
 
 /** "SRTM" read as a little-endian u32. */
@@ -24,11 +25,39 @@ const MAGIC = 0x4d545253
 // Version 4 adds the metalness/roughness fields to the material records
 // (metalness, roughness, metalnessRoughnessMap); a version-3 file lacks
 // them, so it is rejected the same way rather than read as all-metal.
-const VERSION = 5
+// Version 6 spells attribute formats in the WebGPU vocabulary
+// (float32x3, unorm8x4, ...) and counts vertices in bytes, so a part may
+// carry packed channels; a version-5 file's "vec3" words do not parse.
+// Version 7 changes the named "skinned" layout's joints from float32x4 to
+// uint8x4 (an integer shader input), so a version-6 skinned part would
+// decode at the wrong stride; it is rejected. Re-bake with `srt tool
+// 3d/model`.
+// Version 8 carries morph targets: a part's packed targets block (names,
+// the sparse-by-vertex texels, the extent - see packMorphTargets), the
+// mesh weights on the node table, and clip channels on the "weights"
+// path. A version-7 file has none, so it is rejected the same way.
+// Version 9 names the plain layout "base" (position, normal, uv - the
+// prefix "colored" and "skinned" extend) where version 8 wrote
+// "standard"; a version-8 file's layout word does not parse.
+const VERSION = 9
 
-// The named layouts the container writes; a custom attribute-list layout
-// has no name to store, so encodeModel rejects it.
-const NAMED_LAYOUTS = ["standard", "colored", "skinned"]
+// The named layouts the container writes by name; a custom attribute-list
+// layout (a skinned primitive with COLOR_0, a withAttribute channel) is
+// written as its list.
+const NAMED_LAYOUTS = ["base", "colored", "skinned"]
+
+// A part's layout as written: a named preset, or a custom attribute list
+// checked to the shape the stride and the pipeline are built from.
+function decodeLayout(layout: string | VertexAttribute[], name: string): VertexLayout {
+  if (typeof layout === "string") {
+    if (!NAMED_LAYOUTS.includes(layout)) throw new Error("decodeModel: part '" + name + "' has an unsupported layout " + layout)
+    return layout as VertexLayout
+  }
+  if (!Array.isArray(layout) || !layout.every((a) => typeof a.name === "string" && a.format in VERTEX_FORMATS)) {
+    throw new Error("decodeModel: part '" + name + "' has a malformed attribute list")
+  }
+  return layout
+}
 
 type Block = { offset: number; bytes: number }
 
@@ -37,10 +66,12 @@ type PartHeader = Block & {
   node: number
   skin: number | null
   material: number
-  layout: string
+  layout: string | VertexAttribute[]
   vertexCount: number
   indexBits: 16 | 32
   index: Block
+  /** The part's packed morph targets, when it has any. */
+  morphs?: { names: string[]; texels: Block; extent: number[] }
 }
 
 type SkinHeader = { joints: number[]; inverseBind: Block; jointBounds: Block }
@@ -83,23 +114,28 @@ export function encodeModel(data: ModelData): Uint8Array {
 
   let parts: PartHeader[] = data.parts.map((part) => {
     let g = part.geometry
-    let layout = g.layout === undefined ? "standard" : g.layout
-    if (typeof layout !== "string") {
-      throw new Error("encodeModel: part '" + part.name + "' has a custom attribute-list layout; only the named layouts are written")
+    if (g.streams !== undefined && g.streams.length > 0) {
+      throw new Error("encodeModel: part '" + part.name + "' carries extra vertex streams; the container writes one interleaved buffer per part")
     }
+    let layout = g.layout === undefined ? "base" : g.layout
     let vertices = push(new Uint8Array(g.vertices.buffer, g.vertices.byteOffset, g.vertices.byteLength))
     let index = push(new Uint8Array(g.indices.buffer, g.indices.byteOffset, g.indices.byteLength))
-    return {
+    let header: PartHeader = {
       ...vertices,
       name: part.name,
       node: part.node,
       skin: part.skin,
       material: part.material,
       layout,
-      vertexCount: g.vertices.length / layoutStride(layout),
+      vertexCount: g.vertices.byteLength / layoutStride(layout),
       indexBits: g.indices instanceof Uint32Array ? 32 : 16,
       index,
     }
+    if (g.morphs !== undefined) {
+      let texels = push(new Uint8Array(g.morphs.texels.buffer, g.morphs.texels.byteOffset, g.morphs.texels.byteLength))
+      header.morphs = { names: g.morphs.names, texels, extent: Array.from(g.morphs.extent) }
+    }
+    return header
   })
   let images = data.images.map((image) => push(image))
   let floats = (f: Float32Array): Block => push(new Uint8Array(f.buffer, f.byteOffset, f.byteLength))
@@ -152,15 +188,18 @@ export function decodeModel(bytes: Uint8Array): ModelData {
   let payload = base + 12 + jsonLength + ((4 - (jsonLength % 4)) % 4)
 
   let parts = header.parts.map((part) => {
-    if (!NAMED_LAYOUTS.includes(part.layout)) throw new Error("decodeModel: part '" + part.name + "' has an unsupported layout " + part.layout)
-    let layout = part.layout as VertexLayout
+    let layout = decodeLayout(part.layout, part.name)
     let indexCount = part.index.bytes / (part.indexBits / 8)
     let geometry: ModelData["parts"][0]["geometry"] = {
-      vertices: new Float32Array(buffer, payload + part.offset, part.vertexCount * layoutStride(layout)),
+      vertices: vertexView(layout, buffer, payload + part.offset, part.vertexCount * layoutStride(layout)),
       indices: part.indexBits === 32 ? new Uint32Array(buffer, payload + part.index.offset, indexCount) : new Uint16Array(buffer, payload + part.index.offset, indexCount),
       label: part.name,
     }
-    if (part.layout !== "standard") geometry.layout = layout
+    if (part.layout !== "base") geometry.layout = layout
+    if (part.morphs !== undefined) {
+      let m = part.morphs
+      geometry.morphs = { names: m.names, texels: new Float32Array(buffer, payload + m.texels.offset, m.texels.bytes / 4), extent: Float32Array.from(m.extent) }
+    }
     return {
       name: part.name,
       node: part.node,

package/src/model.ts

@@ -11,16 +11,18 @@
 
 import { file } from "flux:fs"
 import * as spatial from "flux:spatial"
-import { decodeImage } from "@solidrt/core"
+import { decodeImage, getOwner, isDisposed, onCleanup, runWithOwner } from "@solidrt/core"
+import type { Owner } from "@solidrt/core"
 import { createMutableTexture, createTexture, destroyTexture } from "@solidrt/core/gpu"
 import type { TextureId } from "@solidrt/core/gpu"
 import { gltfExternalUris, parseGltf } from "./gltf.ts"
 import type { ModelClip, ModelData, ModelMaterial } from "./gltf.ts"
 import { decodeModel } from "./model-file.ts"
 import { disposeGeometry } from "./geometry-gpu.ts"
+import { layoutSlot } from "./geometry.ts"
 import { standard } from "./material.ts"
 import type { Material } from "./material.ts"
-import { add, createGroup, remove, setTransform } from "./node.ts"
+import { add, afterFree, createGroup, createMorphState, remove, setTransform } from "./node.ts"
 import type { SceneNode } from "./node.ts"
 import { createMesh } from "./mesh.ts"
 import type { Mesh } from "./mesh.ts"
@@ -33,7 +35,7 @@ import type { WornPiece } from "./skeleton.ts"
  * the device by the runtime. */
 const MODEL_ANISOTROPY = 4
 
-/** A glTF material's uploaded textures, by lit()/standard() option name;
+/** A glTF material's uploaded textures, by phong()/standard() option name;
  * null where the material has none. */
 export type ModelMaps = {
   map: TextureId | null
@@ -49,18 +51,26 @@ export type ModelOptions = {
   /** The material for each glTF material (default: `standard` with its
    * color, maps, normal scale, metalness/roughness, emissive and
    * transparency - the glTF material model; a scene with no `environment`
-   * renders its metals near black, so set one, or return `lit` here for
+   * renders its metals near black, so set one, or return `phong` here for
    * the Blinn-Phong look). `maps` holds the uploaded textures by
-   * lit()/standard() option name. Called once per material -
-   * or once per (material, skinned) combination when skinned parts share
-   * a material with static ones - and shared by every part using it.
-   * `skinned` is true when the material must skin (pass it through to
-   * `lit`/`unlit`, or read aJoints/aWeights + uBones yourself).
-   * `data.materials` is in file order, so the calls arrive in file order
-   * too. */
-  material?: (material: ModelMaterial, maps: ModelMaps, skinned: boolean) => Material
+   * phong()/standard() option name. Called once per material -
+   * or once per (material, skinned, vertexColors, morphed) combination
+   * when parts that differ in any share a material - and shared by every
+   * part using it. `skinned` is true when the material must skin (pass it
+   * through to `phong`/`unlit`, or read aJoints/aWeights + uBones yourself);
+   * `vertexColors` is true when the part carries COLOR_0 in aColor (pass
+   * it through, or read aColor yourself); `morphed` is true when the part
+   * carries morph targets (pass it through as `morph`, or splice
+   * MORPH_DECLS/MORPH_APPLY yourself). `data.materials` is in file order,
+   * so the calls arrive in file order too. */
+  material?: (material: ModelMaterial, maps: ModelMaps, skinned: boolean, vertexColors: boolean, morphed: boolean) => Material
   /** Debug name for the textures. */
   label?: string
+  /** Free the model with the owning reactive scope (default true, like
+   * createScene: `dispose()` runs at the scope's cleanup); `false` opts
+   * out, then call dispose yourself. For loadGltf/loadModel the scope is
+   * the caller's at the call, before the await. */
+  autoFree?: boolean
 }
 
 /** A model in the scene: a Group carrying the file's node hierarchy as
@@ -134,7 +144,7 @@ export function createModel(data: ModelData, opts: ModelOptions = {}): Model {
       label: label ? label + "-image" + i : undefined,
     })
   })
-  let make = opts.material ?? ((m: ModelMaterial, maps: ModelMaps, skinned: boolean): Material => {
+  let make = opts.material ?? ((m: ModelMaterial, maps: ModelMaps, skinned: boolean, vertexColors: boolean, morphed: boolean): Material => {
     // An emissive factor of zero is emission OFF (the glTF product rule:
     // factor times texture), so the map is skipped too - no sampler for
     // a term that cannot show.
@@ -155,17 +165,20 @@ export function createModel(data: ModelData, opts: ModelOptions = {}): Model {
       cull: m.doubleSided ? "none" : "back",
       alphaTest: m.alphaMode === "MASK" ? m.alphaCutoff : undefined,
       skinned: skinned || undefined,
+      vertexColors: vertexColors || undefined,
+      morph: morphed || undefined,
     })
   })
   let slot = (index: number | null): TextureId | null => (index === null ? null : textures[index]!)
   // One instance per glTF material as today, plus a skinned variant per
-  // material the skinned parts bring (a material shared by a static and
-  // a skinned part needs two programs - different vertex stages).
+  // material the skinned parts bring and a vertex-colored one per material
+  // the COLOR_0 parts bring (a material shared by parts that differ in
+  // either needs two programs - different vertex stages).
   let variants = new Map<string, Material>()
-  let materialFor = (index: number, skinned: boolean): Material => {
+  let materialFor = (index: number, skinned: boolean, vertexColors: boolean, morphed: boolean): Material => {
     let m = data.materials[index]
     if (m === undefined) throw new Error("createModel: a part names a missing material " + index)
-    let key = index + (skinned ? "|skinned" : "")
+    let key = index + (skinned ? "|skinned" : "") + (vertexColors ? "|colored" : "") + (morphed ? "|morphed" : "")
     let made = variants.get(key)
     if (made === undefined) {
       made = make(
@@ -178,12 +191,14 @@ export function createModel(data: ModelData, opts: ModelOptions = {}): Model {
           roughnessMap: slot(m.metalnessRoughnessMap),
         },
         skinned,
+        vertexColors,
+        morphed,
       )
       variants.set(key, made)
     }
     return made
   }
-  let materials = data.materials.map((_, i) => materialFor(i, false))
+  let materials = data.materials.map((_, i) => materialFor(i, false, false, false))
 
   let model = createGroup() as Model
   model._skins = []
@@ -199,6 +214,16 @@ export function createModel(data: ModelData, opts: ModelOptions = {}): Model {
   })
   data.nodes.forEach((n, i) => add(n.parent === null ? model : groups[n.parent]!, groups[i]!))
   model.nodes = data.nodes.map((n, i) => ({ name: n.name, node: groups[i]! }))
+  // A glTF node with morph targets owns its parts' weights (the file's
+  // node.weights / mesh.weights seed them): one register, one weights
+  // texture, every part of the mesh reads it - so setMorphWeights on
+  // the node (and a clip's weights track) moves the whole mesh.
+  data.nodes.forEach((n, i) => {
+    if (n.weights === undefined) return
+    let part = data.parts.find((p) => p.node === i && p.geometry.morphs !== undefined)
+    if (part === undefined) return
+    groups[i]!._morph = createMorphState(part.geometry.morphs!.names, n.weights, label ? label + "-" + n.name + "-weights" : n.name + "-weights")
+  })
   // Each skin's palette lives in an rgba32f texture, 4 texels wide, one
   // row per joint (the four columns of that joint's mat4), sized to the
   // RIG: rig size is bounded by texture height (>= 2048 everywhere), not
@@ -245,8 +270,11 @@ export function createModel(data: ModelData, opts: ModelOptions = {}): Model {
   refreshJointBounds(model)
   model.parts = data.parts.map((part) => {
     let skinned = part.skin !== null
-    let material = materialFor(part.material, skinned)
+    let morphed = part.geometry.morphs !== undefined
+    let material = materialFor(part.material, skinned, layoutSlot(part.geometry.layout, "aColor") !== null, morphed)
     let mesh = createMesh(part.geometry, material)
+    // The part's weights are its glTF node's (above), not its own.
+    if (morphed) mesh._morphOwner = groups[part.node] ?? mesh
     if (skinned) {
       // A skinned part's vertices are model-space bind pose and the skin
       // matrices place them, so its mesh hangs off the model root (the
@@ -268,16 +296,32 @@ export function createModel(data: ModelData, opts: ModelOptions = {}): Model {
   model.materials = materials
   model.clips = data.clips
   model.bounds = data.bounds
+  let disposed = false
   model.dispose = () => {
+    if (disposed) return
     // A worn piece comes off first (its rows sit on the body's joints);
     // a body takes its pieces with it (their skins read joints that are
     // about to go).
     if (model._body !== null) unbindSkeleton(model)
     for (let worn of model._worn.slice()) worn.piece.dispose()
     if (model.parent !== null) remove(model)
+    // A destroyed model still animating out (its root waits for every
+    // part's exit) keeps its textures until it is gone: destroy then
+    // dispose is the unmount shape, and a corpse must not sample a
+    // destroyed texture.
+    if (afterFree(model, () => model.dispose())) return
+    disposed = true
     for (let part of model.parts) disposeGeometry(part.mesh.geometry)
     for (let id of textures) destroyTexture(id)
     textures.length = 0
+    // The nodes' weights textures (the parts' entries are off the scene
+    // with the remove above).
+    for (let n of model.nodes) {
+      if (n.node._morph !== null) {
+        destroyTexture(n.node._morph.texture)
+        n.node._morph = null
+      }
+    }
     // Core clips a mixer registered; their players drop at the next
     // advance (the leave above already killed the target nodes).
     for (let clip of model.clips) {
@@ -291,9 +335,27 @@ export function createModel(data: ModelData, opts: ModelOptions = {}): Model {
       }
     }
   }
+  if (opts.autoFree !== false && getOwner()) onCleanup(() => model.dispose())
   return model
 }
 
+// Build under the reactive scope a loader was called from, captured
+// before its first await (an await leaves the reactive context; whatever
+// scope happens to be current when the bytes arrive is not the caller's).
+// autoFree then frees the model with that scope. A scope gone by the time
+// the load settles - a component unmounted mid-load - can own nothing
+// any more, so the model is freed on arrival and the promise resolves
+// with it disposed: the caller nobody listens to gets a valid, inert
+// object rather than a rejection or a leak.
+function buildOwned(owner: Owner | null, opts: ModelOptions | undefined, build: () => Model): Model {
+  if (opts?.autoFree !== false && owner !== null && isDisposed(owner)) {
+    let model = build()
+    model.dispose()
+    return model
+  }
+  return runWithOwner(owner, build)
+}
+
 /**
  * Read a .glb or .gltf (with its external .bin and image files, resolved
  * next to it) and build the model. The parse runs on the runtime - fine
@@ -301,6 +363,7 @@ export function createModel(data: ModelData, opts: ModelOptions = {}): Model {
  * `srt tool 3d/model` and use loadModel.
  */
 export async function loadGltf(path: string, opts?: ModelOptions): Promise<Model> {
+  let owner = getOwner()
   let bytes = await file(path).bytes()
   // A .glb usually embeds everything, but external uris are legal there
   // too (some exporters keep images as files), so both containers get
@@ -310,11 +373,13 @@ export async function loadGltf(path: string, opts?: ModelOptions): Promise<Model
   for (let uri of gltfExternalUris(bytes)) {
     if (!files.has(uri)) files.set(uri, await file(dir + decodeURIComponent(uri)).bytes())
   }
-  return createModel(parseGltf(bytes, (uri) => files.get(uri)!), opts)
+  return buildOwned(owner, opts, () => createModel(parseGltf(bytes, (uri) => files.get(uri)!), opts))
 }
 
 /** Read a baked .srtm model (`srt tool 3d/model`) and build it: no parsing,
  * the geometry views the file's bytes directly. */
 export async function loadModel(path: string, opts?: ModelOptions): Promise<Model> {
-  return createModel(decodeModel(await file(path).bytes()), opts)
+  let owner = getOwner()
+  let bytes = await file(path).bytes()
+  return buildOwned(owner, opts, () => createModel(decodeModel(bytes), opts))
 }

package/src/motion.ts

@@ -0,0 +1,17 @@
+// The ease every camera control's self-driven motion runs on: a glide to
+// a commanded pose (glideTo, fit) and the damping of an unbracketed input
+// delta (a wheel notch) both close the gap to a goal pose by the same
+// exponential fraction per frame, so the two controls here and the 2d
+// camera read the same. Frame-rate independent: the step is
+// 1 - e^(-rate * dt), never a fixed fraction.
+
+// E-foldings per second toward the goal: high enough that a wheel notch
+// reads as one push, low enough to look smooth (the 2d camera's rate).
+export const GLIDE_EASE = 9
+// A motion lands - snaps to its goal and stops - once this fraction of
+// its initial gap remains: under a pixel on any pose component a glide
+// moves through at ordinary distances.
+export const GLIDE_EPSILON = 0.001
+
+/** The fraction of the remaining gap an ease at `rate` closes over dt. */
+export let easeStep = (rate: number, dt: number): number => 1 - Math.exp(-rate * dt)