@solidrt/3d 0.0.60 → 0.0.61

package/src/shots.ts

@@ -0,0 +1,63 @@
+// Shots and blends over the 3d cameras (okf/design/camera-controls.md):
+// core's blender specialized to the scene's CameraState - an orbit or
+// first-person control drives a shot's recording target instead of the
+// scene, the blender owns the scene's setCamera, and a switch blends
+// position, target, up, fov, near and far linearly; two orthographic
+// extents blend too, a perspective-to-ortho switch cuts at the midpoint
+// (there is no in-between projection).
+
+import { createShotBlend } from "@solidrt/core/camera-control"
+import type { ShotBlend, ShotBlendOptions, ShotTarget as RecordingTarget } from "@solidrt/core/camera-control"
+import type { CameraState, CameraUpdate } from "./camera.ts"
+import type { Vec3 } from "./math.ts"
+
+let lerp = (a: number, b: number, t: number) => a + (b - a) * t
+let lerp3 = (a: Vec3, b: Vec3, t: number): Vec3 => [lerp(a[0], b[0], t), lerp(a[1], b[1], t), lerp(a[2], b[2], t)]
+
+/** Interpolate two scene cameras (see the header). */
+export let mixCamera = (a: CameraState, b: CameraState, t: number): CameraState => ({
+  position: lerp3(a.position, b.position, t),
+  target: lerp3(a.target, b.target, t),
+  up: lerp3(a.up, b.up, t),
+  fov: lerp(a.fov, b.fov, t),
+  near: lerp(a.near, b.near, t),
+  far: lerp(a.far, b.far, t),
+  ortho:
+    a.ortho !== null && b.ortho !== null
+      ? { left: lerp(a.ortho.left, b.ortho.left, t), right: lerp(a.ortho.right, b.ortho.right, t), top: lerp(a.ortho.top, b.ortho.top, t), bottom: lerp(a.ortho.bottom, b.ortho.bottom, t) }
+      : t < 0.5
+        ? a.ortho
+        : b.ortho,
+})
+
+/** What shots drive: a Scene, or one of its Views. */
+export type ShotsOwner = { setCamera(update: CameraUpdate): void; camera(): CameraState; size(): { width: number; height: number } }
+
+/** A shot's target: the recording half plus the owner's size, so an
+ * orbit or first-person control drives it exactly like the scene. */
+export type ShotTarget = RecordingTarget<CameraState> & { size(): { width: number; height: number } }
+
+export type ShotsHandle = Omit<ShotBlend<CameraState>, "shot"> & { shot(name: string, opts?: { priority?: number }): ShotTarget }
+
+/**
+ * Shots over a scene or a view: `shot(name, { priority? })` returns the
+ * target a `createOrbitCamera` or `createFirstPersonCamera` drives (its
+ * `camera()` is the shot's own, its `size()` the owner's); `activate(
+ * name, { blend? })` makes it live when its priority wins, blending
+ * from the current output; `update(dt)` from a frame loop while
+ * `active()`. Every shot starts from the owner's camera at creation.
+ */
+export function createShots(owner: ShotsOwner, options: ShotBlendOptions = {}): ShotsHandle {
+  if (!owner || typeof owner.setCamera !== "function" || typeof owner.camera !== "function" || typeof owner.size !== "function") {
+    throw new Error("createShots: the owner needs setCamera(), camera() and size() (a Scene or a View)")
+  }
+  let initial = owner.camera()
+  let blend = createShotBlend<CameraState>(camera => owner.setCamera(camera), mixCamera, initial, options)
+  return {
+    ...blend,
+    shot(name, opts) {
+      let rec = blend.shot(name, opts)
+      return { setCamera: rec.setCamera, camera: rec.camera, size: () => owner.size() }
+    },
+  }
+}

package/src/skeleton.ts

@@ -24,8 +24,10 @@
 
 import * as spatial from "flux:spatial"
 import type { TextureId } from "@solidrt/core/gpu"
-import { add, remove, setTransform } from "./node.ts"
+import { add, destroy, remove, setTransform } from "./node.ts"
 import type { SceneNode } from "./node.ts"
+import { reparentInstance } from "./mesh.ts"
+import type { InstancedMesh, InstanceNode } from "./mesh.ts"
 import type { Model } from "./model.ts"
 
 /** Inverse-bind entries of a piece and its body differ by exporter
@@ -41,9 +43,19 @@ export type WornPiece = {
   boxes: { joint: SceneNode; box: Float32Array }[]
 }
 
+export type BindSkeletonOptions = {
+  /** Map a piece node's name to the body name to look up (still
+   * case-insensitive), for a pipeline whose joint names differ by a
+   * prefix or suffix: Mixamo's `mixamorig:`, a one-sided `_JNT`. Unity
+   * matches exact names and leaves the rest to the app; this is that
+   * hook. Default the identity. */
+  match?: (pieceName: string) => string
+}
+
 /**
  * Drive `piece`'s skins from `body`'s skeleton: a wardrobe piece exported
- * over the body's joints (matched by name, case-insensitive) with no
+ * over the body's joints (matched by name, case-insensitive, through
+ * `match` when the names differ by a fixed prefix or suffix) with no
  * clips of its own. After this the piece hangs under the body at the
  * body's placement, its skinned parts follow every pose the body takes -
  * mixer-driven or hand-posed - and its joints with no body counterpart
@@ -54,8 +66,9 @@ export type WornPiece = {
  * rest pose). A piece is taken off by disposing it; disposing the body
  * disposes what it wears.
  */
-export function bindSkeleton(body: Model, piece: Model): void {
+export function bindSkeleton(body: Model, piece: Model, opts: BindSkeletonOptions = {}): void {
   if (piece === body) throw new Error("bindSkeleton: a model cannot wear itself")
+  if (opts.match !== undefined && typeof opts.match !== "function") throw new Error("bindSkeleton: match must be a function from a piece name to a body name")
   if (piece._body !== null) throw new Error("bindSkeleton: the piece is already bound to a body")
   if (body._body !== null) throw new Error("bindSkeleton: the body is itself a worn piece")
   if (piece._skins.length === 0) throw new Error("bindSkeleton: the piece has no skin")
@@ -64,6 +77,13 @@ export function bindSkeleton(body: Model, piece: Model): void {
   // re-bind under a different anchor (one anchor per palette texture),
   // and the add() under the body re-enters everything below.
   remove(piece)
+  // The piece's shared parts re-anchor on the BODY root: the piece sits at
+  // identity under it (below), so the mesh's world still equals the
+  // anchor's, and a copy grafted under a body joint stays inside the
+  // anchor's subtree. The records rebind at the re-enter.
+  for (let part of piece.parts) {
+    if (part.instances !== undefined) (part.mesh as InstancedMesh)._instances.anchor = body
+  }
 
   let bodyByName = new Map<string, SceneNode>()
   for (let n of body.nodes) {
@@ -74,12 +94,13 @@ export function bindSkeleton(body: Model, piece: Model): void {
   for (let s of body._skins) s.joints.forEach((j, k) => bodyBind.set(j, s.inverseBind.subarray(k * 16, k * 16 + 16)))
   let match = new Map<SceneNode, SceneNode>()
   let names = new Map<SceneNode, string>()
+  let bodyName = opts.match ?? ((name: string) => name)
   for (let n of piece.nodes) {
     names.set(n.node, n.name)
-    let b = bodyByName.get(n.name.toLowerCase())
+    let b = bodyByName.get(bodyName(n.name).toLowerCase())
     if (b !== undefined) match.set(n.node, b)
   }
-  if (match.size === 0) throw new Error("bindSkeleton: no node of the piece is named like a node of the body")
+  if (match.size === 0) throw new Error("bindSkeleton: no node of the piece is named like a node of the body" + (opts.match ? " (through match)" : ""))
 
   // Matched rows move onto the body's joints. Identical skins share one
   // texture, so its rows move with the first skin naming it; the check
@@ -126,7 +147,12 @@ export function bindSkeleton(body: Model, piece: Model): void {
   for (let [node, bodyNode] of match) {
     for (let child of node.children.slice()) {
       if (match.has(child)) continue
-      add(bodyNode, child)
+      // A shared part's copy under a matched node (its placement node IS
+      // a joint) rides the body's joint like any rigid part: slot-bound,
+      // so it moves by reparentInstance rather than add, against the
+      // body-root anchor set above.
+      if (child.kind === "instance") reparentInstance(child as InstanceNode, bodyNode)
+      else add(bodyNode, child)
       piece._grafts.push(child)
     }
   }
@@ -158,7 +184,13 @@ export function unbindSkeleton(piece: Model): void {
     }
     n.node._palettes = keep.length > 0 ? keep : null
   }
-  for (let g of piece._grafts) remove(g)
+  // A grafted group detaches; a grafted instance is slot-bound and goes
+  // by destroy (the piece's populations are disposed right after, by the
+  // one caller, dispose).
+  for (let g of piece._grafts) {
+    if (g.kind === "instance") destroy(g)
+    else remove(g)
+  }
   piece._grafts = []
   body._worn.splice(body._worn.findIndex((w) => w.piece === piece), 1)
   piece._body = null

package/tools/environment.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env bun
+/// <reference path="./node-env.d.ts" />
 
 // srt tool 3d/environment: bake a Radiance .hdr panorama into a .srte
 // environment file - the six cube faces and their GGX-prefiltered mip

package/tools/model.ts

@@ -1,18 +1,19 @@
 #!/usr/bin/env bun
+/// <reference path="./node-env.d.ts" />
 
 // srt tool 3d/model: bake a glTF into a .srtm model file - the parse
 // (src/gltf.ts) run once here under bun, the result written in the exact
 // layout loadModel views without any per-vertex work at runtime. Same
 // parser, same subset, same result as loadGltf; this only moves the cost
 // to build time. Put the output under assets/ so it ships with the app.
+// Everything here comes from the runtime-free `@solidrt/3d/model` entry
+// (src/model-data.ts), the same surface an app's own bake script uses.
 //
 //   srt tool 3d/model <in.gltf|in.glb> [-o <out.srtm>]
 
 import { readFileSync, writeFileSync } from "node:fs"
 import { basename, dirname, extname, join } from "node:path"
-import { parseGltf } from "../src/gltf.ts"
-import { encodeModel } from "../src/model-file.ts"
-import { layoutStride } from "../src/geometry.ts"
+import { encodeModel, layoutStride, parseGltf } from "../src/model-data.ts"
 
 function usage(error?: string): never {
   if (error) console.error(error)

package/tools/node-env.d.ts

@@ -0,0 +1,25 @@
+// The node surface the tools use, declared here so `srt check
+// packages/3d/tools/<name>.ts` typechecks them on the package's flux-typed
+// program (the nearest tsconfig is the repo root's). The tools run under
+// bun, but bun's own types cannot join this program: their globals
+// (Response, fetch, process) collide with the flux standards the rest of
+// the chain is typed against - the same split packages/cli keeps. Each
+// tool references this file with a triple-slash directive; nothing else
+// includes it, and a scaffolded app never roots a program at a tool.
+
+declare module "node:fs" {
+  export function readFileSync(path: string): Uint8Array
+  export function writeFileSync(path: string, data: Uint8Array | string): void
+}
+
+declare module "node:path" {
+  export function basename(path: string, ext?: string): string
+  export function dirname(path: string): string
+  export function extname(path: string): string
+  export function join(...parts: string[]): string
+}
+
+declare const process: {
+  argv: string[]
+  exit(code?: number): never
+}

package/src/motion.ts

@@ -1,17 +0,0 @@
-// 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)

package/src/order.ts

@@ -1,58 +0,0 @@
-// Draw-list ordering for a scene: a pure function of the live meshes and the
-// camera's view matrix, with no GUI import, so the check rig
-// (checks/order-check.ts) runs it headless on flux against a linear oracle.
-// The scene calls it whenever the order is dirty and hands the result to
-// setDrawOrder.
-
-import type { Mat4, Vec3 } from "./math.ts"
-
-/** The slice of a Mesh the sort reads (field names match Mesh so the
- * scene passes its meshes straight through). */
-export type Orderable<T> = {
-  _entry: T | null
-  _transparent: boolean
-  renderOrder: number
-  _center: Vec3
-}
-
-/**
- * Draw order: `first` (the background entry, if any), then opaque meshes by
- * renderOrder with add order within a key, then transparent meshes by
- * renderOrder then back-to-front by the view-space depth of the world-bounds
- * center. The center, not the origin (Three's key), so geometry built
- * off-origin sorts by where it is; and not the nearest bounds point, which
- * would draw a large translucent ground plane over the small translucents
- * resting on it. Per-mesh only: no per-triangle sort, no OIT. `entry`
- * picks the id ordered for each mesh (default its own `_entry`; a view
- * passes its per-mesh entries in its target).
- */
-export function orderEntries<T>(
-  meshes: readonly Orderable<T>[],
-  view: Mat4,
-  first?: T,
-  entry: (m: Orderable<T>) => T | null = m => m._entry,
-): T[] {
-  let opaque: Orderable<T>[] = []
-  let transparent: Orderable<T>[] = []
-  for (let m of meshes) {
-    if (entry(m) === null) continue
-    ;(m._transparent ? transparent : opaque).push(m)
-  }
-  // Array sort is stable, so equal keys keep add order.
-  opaque.sort((a, b) => a.renderOrder - b.renderOrder)
-  if (transparent.length > 1) {
-    // The camera looks down -z in view space, so farther is more negative
-    // and ascending depth is back-to-front.
-    let depth = new Map<Orderable<T>, number>()
-    for (let m of transparent) {
-      let c = m._center
-      depth.set(m, view[2] * c[0] + view[6] * c[1] + view[10] * c[2] + view[14])
-    }
-    transparent.sort((a, b) => a.renderOrder - b.renderOrder || depth.get(a)! - depth.get(b)!)
-  }
-  let order: T[] = []
-  if (first !== undefined) order.push(first)
-  for (let m of opaque) order.push(entry(m)!)
-  for (let m of transparent) order.push(entry(m)!)
-  return order
-}