@solidrt/3d 0.0.70 → 0.0.72

package/src/mesh.ts

@@ -3,12 +3,12 @@
 // setter write paths that keep a live scene's draw entries in step. The
 // scene side is reached through the node's SceneHooks (node.ts).
 
-import { beginBufferWrite, createBuffer, destroyBuffer, destroyTexture, endBufferWrite, transferRecords, writeBuffer } from "@solidrt/core/gpu"
-import type { BufferId, DrawId, ShaderParams, TextureBindings, TextureId, VertexAttribute, VertexBufferLayout } from "@solidrt/core/gpu"
+import { createBuffer, createRecordStream, destroyBuffer, destroyTexture, encodeRecord, layoutComponents, layoutFields, transferRecords, writeRecord as writeLayoutRecord, VERTEX_FORMATS } from "@solidrt/core/gpu"
+import type { AttributeAccess, BufferId, DrawId, RecordStream, ShaderParams, TextureBindings, TextureId, VertexAttribute, VertexBufferLayout } from "@solidrt/core/gpu"
 import { checkCubeKnobs } from "./environment.ts"
 import type { EnvironmentOptions } from "./environment.ts"
-import { geometryBounds, isFloatLayout, layoutKey, layoutStride, plane, vertexBytes, vertexView, VERTEX_FORMATS } from "./geometry.ts"
-import type { AttributeAccess, Geometry } from "./geometry.ts"
+import { geometryBounds, isFloatLayout, layoutKey, layoutStride, plane, vertexBytes, vertexView } from "./geometry.ts"
+import type { Geometry } from "./geometry.ts"
 import { INSTANCE_MATRIX_ATTRIBUTES } from "./glsl.ts"
 import type { GeometryBuffers } from "./geometry-gpu.ts"
 import type { Material } from "./material.ts"
@@ -189,15 +189,22 @@ export type InstanceStream = {
   layout: VertexAttribute[]
   /** Bytes per record: the layout's stride. */
   stride: number
+  /** The GPU buffer the entry binds; `stream.buffer` where a stream
+   * exists (growth re-points both), the engine-held buffer otherwise. */
   buffer: BufferId
+  /** The core record stream behind the mirror (createRecordStream: the
+   * buffer, the byte mirror, the dirty range and the publish), or null
+   * where no JS mirror exists: the transfer form hands the records to
+   * the engine, the indexed order's id stream is the engine's to fill. */
+  stream: RecordStream | null
+  /** The mirror as the layout's view (a Float32Array over an all-float
+   * layout, bytes otherwise): `stream.bytes` viewed, re-derived on growth;
+   * zero-length without a stream. */
   data: ArrayBufferView
   /** The record a fresh (or recycled) instance slot starts with: the
    * material's instanceStyle encoded, on the first stream of an
    * instanced mesh; zeros otherwise. */
   blank: Uint8Array
-  /** The byte range [lo, hi) of `data` written since the last publish,
-   * or null. */
-  dirty: [number, number] | null
   /** The DataView the accessors read through; follows `data`. */
   _view: DataView
   /** All-float32 layout: `data` is a Float32Array and a record write is
@@ -337,13 +344,6 @@ const MATRIX_KEY = layoutKey(INSTANCE_MATRIX_ATTRIBUTES)
 // doubles past it.
 const DEFAULT_CAPACITY = 64
 
-// Values per record of a layout: its attributes' components summed - what
-// setInstanceStyle and a material's instanceStyle count in.
-function layoutComponents(layout: VertexAttribute[]): number {
-  let n = 0
-  for (let a of layout) n += VERTEX_FORMATS[a.format].components
-  return n
-}
 
 // Records in a byte view of `layout`: 4-aligned and a whole number of
 // strides, or a throw naming `site`.
@@ -356,22 +356,6 @@ function recordCount(records: ArrayBufferView, layout: VertexAttribute[], site:
   return records.byteLength / stride
 }
 
-// The accessors of a stream's attributes, reading through the stream's
-// current view so they survive growth.
-function streamFields(stream: InstanceStream): AttributeAccess[] {
-  let offset = 0
-  return stream.layout.map(attr => {
-    let codec = VERTEX_FORMATS[attr.format]
-    let at = offset
-    offset += codec.bytes
-    return {
-      format: attr.format,
-      components: codec.components,
-      get: (i, k) => codec.get(stream._view, i * stream.stride + at, k),
-      set: (i, k, v) => codec.set(stream._view, i * stream.stride + at, k, v),
-    }
-  })
-}
 
 // Point a stream's mirror at `bytes` (a fresh ArrayBuffer of whole
 // records): the handed-out view and the accessors' view.
@@ -384,24 +368,26 @@ function streamLabel(label: string | undefined, index: number): string | undefin
   return label === undefined ? undefined : label + "-" + index
 }
 
-// A stream of `capacity` zeroed records over `layout`; its GPU buffer is
-// sized and unwritten (the mirror is the truth, publishes follow dirty).
+// A stream of `capacity` zeroed records over `layout` on a core record
+// stream; its GPU buffer is sized and unwritten (the mirror is the truth,
+// publishes follow the dirty range).
 function makeStream(layout: VertexAttribute[], capacity: number, blank: Uint8Array | null, label: string | undefined): InstanceStream {
   let stride = layoutStride(layout)
+  let records = createRecordStream(stride, capacity, { autoFree: false, label })
   let stream: InstanceStream = {
     layout,
     stride,
-    buffer: createBuffer(capacity * stride, { autoFree: false, label }),
+    buffer: records.buffer,
+    stream: records,
     data: new Uint8Array(0),
     blank: blank ?? new Uint8Array(stride),
-    dirty: null,
     _view: new DataView(new ArrayBuffer(0)),
     _floats: isFloatLayout(layout),
     _components: layoutComponents(layout),
     _fields: [],
   }
-  viewStream(stream, new ArrayBuffer(capacity * stride))
-  stream._fields = streamFields(stream)
+  viewStream(stream, records.bytes.buffer)
+  stream._fields = layoutFields(stream.layout, () => stream._view)
   return stream
 }
 
@@ -416,9 +402,9 @@ function makeIndexStream(layout: VertexAttribute[], capacity: number, group: num
     layout,
     stride,
     buffer: createBuffer(Math.ceil(capacity / group) * stride, { autoFree: false, label }),
+    stream: null,
     data: new Uint8Array(0),
     blank: new Uint8Array(stride),
-    dirty: null,
     _view: new DataView(new ArrayBuffer(0)),
     _floats: false,
     _components: layoutComponents(layout),
@@ -442,9 +428,9 @@ function makeTransferredStream(layout: VertexAttribute[], records: Uint8Array, o
     buffer: ordered
       ? createBuffer(records.byteLength, { autoFree: false, label })
       : createBuffer(records, { autoFree: false, label }),
+    stream: null,
     data: new Uint8Array(0),
     blank: new Uint8Array(stride),
-    dirty: null,
     _view: new DataView(new ArrayBuffer(0)),
     _floats: isFloatLayout(layout),
     _components: layoutComponents(layout),
@@ -455,41 +441,18 @@ function makeTransferredStream(layout: VertexAttribute[], records: Uint8Array, o
 }
 
 // Encode `values` (one per component, in layout order, as the shader
-// sees them) into record `i` of a stream: one typed-array set over an
-// all-float layout (the values ARE the bytes), the codecs otherwise.
+// sees them) into record `i` of a stream: core's writeRecord over the
+// stream's layout, accessors and float view.
 function writeRecord(stream: InstanceStream, i: number, values: ArrayLike<number>, site: string): void {
-  let n = stream._components
-  if (values.length !== n) throw new Error(site + ": a " + layoutKey(stream.layout) + " record is " + n + " values, got " + values.length)
-  if (stream._floats) {
-    // Indexed stores beat TypedArray.set over a plain array under QuickJS,
-    // which walks the array-like generically.
-    let data = stream.data as Float32Array
-    let at = i * n
-    for (let k = 0; k < n; k++) data[at + k] = values[k]!
-    return
-  }
-  let j = 0
-  for (let f of stream._fields) for (let k = 0; k < f.components; k++) f.set(i, k, values[j++]!)
+  writeLayoutRecord(stream.layout, stream._fields, stream._floats ? (stream.data as Float32Array) : null, i, values, site)
 }
 
-// One record of `layout` encoded from `values`, the bytes a blank slot copies.
-function encodeRecord(layout: VertexAttribute[], values: ArrayLike<number>, site: string): Uint8Array {
-  let stride = layoutStride(layout)
-  let one: InstanceStream = { layout, stride, buffer: 0 as BufferId, data: new Uint8Array(0), blank: new Uint8Array(0), dirty: null, _view: new DataView(new ArrayBuffer(0)), _floats: isFloatLayout(layout), _components: layoutComponents(layout), _fields: [] }
-  viewStream(one, new ArrayBuffer(stride))
-  one._fields = streamFields(one)
-  writeRecord(one, 0, values, site)
-  return vertexBytes(one.data)
-}
 
-// Extend a stream's dirty range over [lo, hi) bytes of the mirror and ask
-// the scene to publish it at the next sync.
+// Mark records [lo, hi) of a stream's mirror and ask the scene to publish
+// them at the next sync.
 function markRecords(mesh: Mesh, stream: InstanceStream, lo: number, hi: number): void {
-  if (stream.dirty === null) stream.dirty = [lo, hi]
-  else {
-    if (lo < stream.dirty[0]) stream.dirty[0] = lo
-    if (hi > stream.dirty[1]) stream.dirty[1] = hi
-  }
+  if (stream.stream === null) throw new Error("markRecords: the stream has no mirror (its records were transferred to the engine)")
+  stream.stream.mark(lo, hi)
   mesh._scene?._setRecords(mesh)
 }
 
@@ -869,7 +832,7 @@ export function setInstanceStyle(instance: InstanceNode, values: ArrayLike<numbe
     let stream = l._instances.streams[0]
     if (stream === undefined) continue
     writeRecord(stream, instance._slot, values, "setInstanceStyle")
-    markRecords(l, stream, instance._slot * stream.stride, (instance._slot + 1) * stream.stride)
+    markRecords(l, stream, instance._slot, instance._slot + 1)
   }
 }
 
@@ -944,34 +907,23 @@ export function updateRecords(mesh: InstancedMesh | RecordMesh, options: UpdateR
   if (!Number.isInteger(first) || !Number.isInteger(count) || first < 0 || count < 0 || first + count > inst.capacity) {
     throw new Error("updateRecords: range [" + first + ", " + (first + count) + ") is outside the mesh's " + inst.capacity + " records")
   }
-  if (count > 0) markRecords(mesh, stream, first * stream.stride, (first + count) * stream.stride)
+  if (count > 0) markRecords(mesh, stream, first, first + count)
 }
 
 /** Publish a mesh's pending record writes, one buffer write per dirty
- * stream (the scene calls it from its sync). An ordered mesh publishes
- * the LIVE record set whole through the write lease - the engine gathers
- * it into key order during the copy, and a byte range has no stable
- * position under a permutation (writeBuffer throws on an ordered buffer). */
+ * stream (the scene calls it from its sync): the dirty record range, up
+ * to the capacity (a record mesh writes ahead of its count). An ordered
+ * mesh publishes the LIVE record set whole through the write lease - the
+ * engine gathers it into key order during the copy, and a byte range has
+ * no stable position under a permutation (writeBuffer throws on an
+ * ordered buffer). */
 export function publishRecords(mesh: Mesh): void {
   let inst = mesh._instances
   if (inst === null) return
-  if (inst.order !== null) {
-    for (let s of inst.streams) {
-      if (s.dirty === null) continue
-      s.dirty = null
-      let bytes = inst.count * s.stride
-      if (bytes === 0) continue
-      let block = beginBufferWrite(s.buffer)
-      new Uint8Array(block.buffer, 0, bytes).set(vertexBytes(s.data).subarray(0, bytes))
-      endBufferWrite(s.buffer, bytes)
-    }
-    return
-  }
+  let ordered = inst.order !== null
   for (let s of inst.streams) {
-    if (s.dirty === null) continue
-    let [lo, hi] = s.dirty
-    s.dirty = null
-    writeBuffer(s.buffer, vertexBytes(s.data).subarray(lo, hi), lo)
+    if (s.stream === null || !s.stream.dirty) continue
+    s.stream.publish(ordered, ordered ? inst.count : inst.capacity)
   }
 }
 
@@ -984,7 +936,7 @@ export function markLiveRecords(mesh: Mesh): void {
   // A transferred mesh has no mirror; the engine's own (buffer-lifetime)
   // mirror seeds a re-attached entry instead.
   if (inst === null || inst.count === 0 || inst.transfer) return
-  for (let s of inst.streams) markRecords(mesh, s, 0, inst.count * s.stride)
+  for (let s of inst.streams) markRecords(mesh, s, 0, inst.count)
 }
 
 /**
@@ -1033,7 +985,7 @@ export function addInstance(mesh: InstancedMesh, update?: TransformUpdate, paren
     // A recycled slot must not wear its last occupant's records.
     for (let s of li.streams) {
       vertexBytes(s.data).set(s.blank, slot * s.stride)
-      markRecords(l, s, slot * s.stride, (slot + 1) * s.stride)
+      markRecords(l, s, slot, slot + 1)
     }
   }
   if (parent._scene) enterScene(instance, parent._scene)
@@ -1069,14 +1021,13 @@ export function reparentInstance(instance: InstanceNode, parent: SceneNode): voi
 
 // Grow the population's buffers to `next` records: replacements (never a
 // resize). An instanced mesh's live matrix records move to the new buffer
-// in one core call and republish at the next flush; every stream's mirror
-// is copied over and marked whole, so the scene republishes it; the entry
-// re-points, then the old buffers, which the entry held alive until now,
-// are freed.
+// in one core call and republish at the next flush; every stream grows
+// into a replacement with its mirror copied over and marked whole, so the
+// scene republishes it; the entry re-points, then the old buffers, which
+// the entry held alive until now, are freed.
 function growInstances(mesh: InstancedMesh | RecordMesh, next: number): void {
   let inst: MeshInstances = mesh._instances
   if (inst.transfer) throw new Error("growInstances: a transferred population is fixed at its creation records")
-  let previous = inst.capacity
   inst.capacity = next
   let freed: BufferId[] = []
   if (inst.matrix !== null) {
@@ -1085,15 +1036,13 @@ function growInstances(mesh: InstancedMesh | RecordMesh, next: number): void {
     // Out of a scene nothing is bound, and retargeting an empty source throws.
     if (inst.nodes !== null && inst.nodes.slots.some(n => n !== null && n._node !== null)) spatial.retargetRecords(freed[0]!, inst.matrix)
   }
-  inst.streams.forEach((s, i) => {
-    freed.push(s.buffer)
-    s.buffer = createBuffer(next * s.stride, { autoFree: false, label: streamLabel(inst.label, i) })
-    let held = vertexBytes(s.data)
-    viewStream(s, new ArrayBuffer(next * s.stride))
-    vertexBytes(s.data).set(held)
-    s.dirty = null
-    markRecords(mesh, s, 0, previous * s.stride)
-  })
+  for (let s of inst.streams) {
+    if (s.stream === null) throw new Error("growInstances: a stream without a mirror cannot grow")
+    freed.push(s.stream.grow(next))
+    s.buffer = s.stream.buffer
+    viewStream(s, s.stream.bytes.buffer)
+    mesh._scene?._setRecords(mesh)
+  }
   mesh._scene?._setBuffer(mesh)
   for (let b of freed) destroyBuffer(b)
   if (inst.morph !== null) replacePopulationMorph(mesh, populationMorph(mesh.geometry, next, inst.label), true)
@@ -1180,7 +1129,7 @@ export function createRecordMesh(
 function copyRecords(mesh: RecordMesh, records: ArrayBufferView, written: number): void {
   let stream = mesh._instances.streams[0]!
   vertexBytes(stream.data).set(vertexBytes(records))
-  if (written > 0) markRecords(mesh, stream, 0, written * stream.stride)
+  if (written > 0) markRecords(mesh, stream, 0, written)
 }
 
 /**
@@ -1220,7 +1169,7 @@ export function setRecordCount(mesh: RecordMesh, count: number): void {
   // old population's nearest records, a growth its stale tail. A
   // transferred mesh has no mirror to publish from; the engine follows
   // the entry's instance count into its own mirror's prefix instead.
-  if (inst.order !== null && !inst.transfer && n > 0) for (let s of inst.streams) markRecords(mesh, s, 0, n * s.stride)
+  if (inst.order !== null && !inst.transfer && n > 0) for (let s of inst.streams) markRecords(mesh, s, 0, n)
   mesh._scene?._setCount(mesh)
 }
 
@@ -1259,7 +1208,10 @@ export function disposeInstances(mesh: InstancedMesh | RecordMesh): void {
     spatial.flush()
   }
   if (inst.matrix !== null) destroyBuffer(inst.matrix)
-  for (let s of inst.streams) destroyBuffer(s.buffer)
+  for (let s of inst.streams) {
+    if (s.stream !== null) s.stream.destroy()
+    else destroyBuffer(s.buffer)
+  }
   if (inst.morph !== null) destroyTexture(inst.morph.texture)
   for (let t of inst.textures) destroyTexture(t)
   ;(mesh as Mesh)._instances = null

package/src/mixer.ts

@@ -401,7 +401,12 @@ export function createMixer(model: Model, mixerOpts: MixerOptions = {}): Mixer {
     if (i >= 0) actions.splice(i, 1)
   }
   let start = (clip: ModelClip, opts: MixerPlayOptions, weight: number, fade: number): void => {
-    let player = spatial.createPlayer(clipFor(clip, opts), targetsFor(clip), opts.speed ?? 1, opts.loop ?? true, weight, fade)
+    let targets = targetsFor(clip)
+    // The player's time runs at the model node's rate (setTimeScale on
+    // it or an ancestor): targetsFor threw if the model is not in a scene.
+    let clock = model._node
+    if (clock === null) throw new Error("play: the model must be in a scene (add() it first) before clips can play")
+    let player = spatial.createPlayer(clipFor(clip, opts), targets, clock, { speed: opts.speed, loop: opts.loop, weight, fade })
     let action: Action = { name: clip.name, player, fadingOut: false, finished: false }
     PLAYER_ENDS.set(player, (reason) => {
       if (reason === "finished") {

package/src/node.ts

@@ -217,8 +217,9 @@ export type SceneNode = {
   /** The wheel over the node (NodeWheelEvent: `deltaX`/`deltaY`), bubbling
    * like down/move/up. */
   onWheel?: (event: NodeWheelEvent) => void
-  /** A press released on this node within the slop, alone for its whole
-   * press (NodeTapEvent: `tapCount`); bubbles like down/move/up. */
+  /** A primary-button press (a right click never taps) released on this
+   * node within the slop, alone for its whole press (NodeTapEvent:
+   * `tapCount`); bubbles like down/move/up. */
   onTap?: (event: NodeTapEvent) => void
   /** A declared transition (setTransition) settled naturally on one
    * component; a cancel, snap, scene leave or exit never fires. */
@@ -239,6 +240,9 @@ export type SceneNode = {
   _scene: SceneHooks | null
   /** The declared transition, re-applied on every scene enter. */
   _transition: NodeTransition | string | null
+  /** The declared time scale (setTimeScale), re-applied on every scene
+   * enter; null inherits. */
+  _timeScale: number | null
   /** Skin palette rows this node feeds (a model joint carries one per
    * skin): bound to the core at every scene enter, so the flush writes
    * `inverse(anchorWorld) * world * post` - the model-local bone matrix -
@@ -289,6 +293,9 @@ export type SceneEventBase = {
   predicted: boolean
   pointerId: number
   pointerType: string
+  /** The pressed button on a down, up or tap (0 = primary, 2 = secondary;
+   * touch is always 0), as the element event carries it; absent on a
+   * move, cancel or wheel. */
   button?: number
   shiftKey: boolean
   ctrlKey: boolean
@@ -407,6 +414,7 @@ export function makeNode(kind: SceneNode["kind"]): SceneNode {
     _moved: false,
     _scene: null,
     _transition: null,
+    _timeScale: null,
     _palettes: null,
     _morph: null,
     _cullBounds: null,
@@ -548,6 +556,7 @@ export function enterScene(node: SceneNode, scene: SceneHooks): void {
     spatial.setTransition(node._node, node._transition)
     declareTransition(node._node, node)
   }
+  if (node._timeScale !== null) spatial.setTimeScale(node._node, node._timeScale)
   // The parent is in the scene already (add() enters the child only then),
   // and the scene root is the one node without a parent.
   if (node.parent !== null && node.parent._node !== null) spatial.setParent(node._node, node.parent._node)
@@ -799,6 +808,37 @@ export function setTransition(node: SceneNode, transition: NodeTransition | stri
   }
 }
 
+/**
+ * Declare (null clears) the rate the native motion in the node's subtree
+ * runs at: transitions with their delays, enters, exits and stagger,
+ * morph weight tracks, and the clip players of the models under it
+ * (a mixer's players are clocked on their model's node, so this is also
+ * Three's `mixer.timeScale`). 0 freezes, 1 is app time, other values
+ * are slow or fast motion. The nearest declaring ancestor wins, never a
+ * product: a world at 0 with a group inside it declaring 1 keeps that
+ * group running (a preview on a pause screen). A frozen subtree asks for
+ * no frames; this write brings the one that resumes it. The declaration
+ * lives on the SceneNode and re-applies on every scene enter. What it
+ * does not cover: `onFrame` logic, timers, video and audio stay on app
+ * time - multiply your own step by `timeRate(node)`. For the whole scene,
+ * `scene.setTimeScale` / `<Scene timeScale>` declare it on `scene.root`.
+ */
+export function setTimeScale(node: SceneNode, scale: number | null): void {
+  if (node._destroyed) return
+  node._timeScale = scale
+  if (node._node !== null) spatial.setTimeScale(node._node, scale)
+}
+
+/**
+ * The rate the node's motion runs at (setTimeScale): its own scale, else
+ * the nearest declaring ancestor's, else 1. Null outside a scene, where
+ * nothing runs and no ancestry resolves.
+ */
+export function timeRate(node: SceneNode): number | null {
+  if (node._node === null) return null
+  return spatial.timeRate(node._node)
+}
+
 /**
  * The one write path for node transforms (so the scene knows to sync).
  * Values are copied in; absent keys keep their current value. This is also
@@ -941,7 +981,11 @@ export function getTransform(node: SceneNode): { position: Vec3; quaternion: Qua
 /**
  * A node's position in world space, copied into `out` (or a fresh Vec3) -
  * Three's `getWorldPosition`. Brings the ancestor chain up to date first,
- * so it is exact before the pending sync has run.
+ * so it is exact before the pending sync has run, and exact against
+ * native motion: a transition or a clip player has stepped to this
+ * frame's pose before any of the frame's JS runs, so a read in onFrame
+ * or the late pass of onBeforeRender is where the node is drawn this
+ * frame.
  */
 export function worldPosition(node: SceneNode, out: Vec3 = [0, 0, 0]): Vec3 {
   let world = worldInto(worldScratch, node)

package/src/scene-pointer.ts

@@ -12,11 +12,12 @@
 // turns. Capture is per pointer to the press target, the root included: a
 // drag from empty space keeps delivering to the root as it crosses meshes,
 // exactly as a drag from a mesh keeps naming that mesh. Enter/leave pair
-// on the struck node alone. Taps are synthesized here (DOM's click,
-// Unity's IPointerClickHandler): a press that releases on the same target
-// within the slop, the only pointer down for its whole press, counted up
-// for repeats (DOM's detail, Unity's clickCount). @solidrt/2d's
-// dispatch.ts is the same model one dimension down.
+// on the struck node alone. Taps are synthesized here (DOM's click, which
+// is primary-button only; Unity's IPointerClickHandler fires for every
+// button and reports it, we do not): a primary-button press that releases
+// on the same target within the slop, the only pointer down for its whole
+// press, counted up for repeats (DOM's detail, Unity's clickCount).
+// @solidrt/2d's dispatch.ts is the same model one dimension down.
 //
 // Pure BY DESIGN (types only, nothing with GPU imports) so
 // tests/dispatch.test.ts drives it headless with a fake pick.
@@ -240,9 +241,11 @@ export function makePointerInput(deps: PointerInputDeps): PointerInput {
         presses.delete(e.pointerId)
         let under = hitOn(press.target, x, y)
         walk("onPointerUp", makeEvent(e, press.target, x, y, under), !press.claimed)
-        // The tap rule: no travel past the slop, alone for the whole
-        // press, released over the target it pressed (empty space for the
-        // root itself).
+        // The tap rule: the primary button (DOM click; core's press and
+        // long-press gate the same way), no travel past the slop, alone
+        // for the whole press, released over the target it pressed (empty
+        // space for the root itself).
+        if (e.button != null && e.button !== 0) return
         if (press.moved || !press.alone) return
         let release = nearest(x, y)
         if (press.target === null ? release !== null : release === null || !sameHit(release, press.target)) return

package/src/scene.ts

@@ -63,7 +63,7 @@ import type { EnvironmentOptions, Prefilter } from "./environment.ts"
 
 export type { EnvironmentOptions } from "./environment.ts"
 import type { Material } from "./material.ts"
-import { activateMorph, fillTransform, freeLeaving, leaveScene, makeNode, setTransition, worldInto } from "./node.ts"
+import { activateMorph, fillTransform, freeLeaving, leaveScene, makeNode, setTimeScale, setTransition, timeRate, worldInto } from "./node.ts"
 import type { SceneHooks, SceneNode, ScenePointerListener } from "./node.ts"
 import { checkInstancePairing, checkMask, checkOrderPairing, drawCount, instanceBinding, localBounds, markLiveRecords, publishRecords, spriteScreenPx } from "./mesh.ts"
 import type { InstancedMesh, InstanceNode, Mesh, MeshInstances, ResolvedInstanceOrder } from "./mesh.ts"
@@ -474,6 +474,10 @@ export type SceneOptions = {
    * the whole-scene form of a Group's stagger (nested groups declaring
    * their own win for what is under them). See setStagger. */
   stagger?: number
+  /** The rate the scene's native motion runs at - `setTimeScale(scene.root,
+   * scale)` at creation: 0 freezes the world, 1 is app time (nodes
+   * declaring their own win for what is under them). See setTimeScale. */
+  timeScale?: number
   /** `autoFree: false` opts out of owner-scoped auto-dispose (then call dispose yourself). */
   autoFree?: boolean
   filter?: FilterMode
@@ -833,6 +837,16 @@ export type Scene = {
   /** Stagger (ms) on the scene's root node, live (SceneOptions.stagger
    * is its creation form): null removes it. The 2d layer's setStagger. */
   setStagger(ms: number | null): void
+  /** The time scale on the scene's root node, live (SceneOptions.timeScale
+   * is its creation form): the rate every transition, enter, exit and
+   * clip player in the scene runs at, 0 a pause that leaves the app's own
+   * UI moving; null removes it (app time). A node declaring its own keeps
+   * its subtree at that rate (see node setTimeScale). The 2d layer's
+   * setTimeScale. */
+  setTimeScale(scale: number | null): void
+  /** The rate the scene's root runs at (setTimeScale): what the app's own
+   * per-frame logic in this scene multiplies its step by. */
+  timeRate(): number
   /** The level a LOD group draws in the scene's own render (the thing to
    * read while tuning thresholds): the index into its levels, nearest
    * first, `levels.length` when culled past the last one, null before
@@ -2071,7 +2085,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       for (let v of views) attachView(v, mesh)
       // Record writes made while the mesh was out of a scene kept their
       // dirty ranges: publish them now.
-      if (inst !== null && inst.streams.some(s => s.dirty !== null)) recordsDirty.add(mesh)
+      if (inst !== null && inst.streams.some(s => s.stream !== null && s.stream.dirty)) recordsDirty.add(mesh)
       // Picking: an ordinary mesh's node carries its geometry's shape,
       // which is its box in the core index (following every
       // updateVertices) and its triangle narrowphase. An instanced mesh's
@@ -2272,22 +2286,45 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
   root._scene = hooks
   root._node = spatial.createNode(fillTransform(root), true)
   if (opts?.stagger !== undefined) setTransition(root, { stagger: opts.stagger })
+  if (opts?.timeScale !== undefined) setTimeScale(root, opts.timeScale)
   // The first light rewrite seeds the (empty) light set and the shadow
   // slots - placeholders, no casts - so receivers draw plain from the
   // first frame.
   lightsDirty = true
   hooks._schedule()
+  // What the sync derives from poses the core moves on its own, placed
+  // every frame: a casting light's shadow cameras follow a light under a
+  // transition or a clip player in the frame the lighting moves, which
+  // the core writes itself. The compare in placeShadowCamera makes this
+  // one world read per caster and no write when nothing moved; the
+  // records, the lights and the budgets wait for a write to schedule the
+  // sync, which places the cameras itself.
+  let follow = () => {
+    if (disposed) return
+    shadowSys.placeCameras(false)
+    for (let v of views) {
+      ensureCamera(v.camera, v.width, v.height)
+      if (!v.camera.pending) continue
+      v.camera.pending = false
+      setTargetParams(v.texture, cameraParams(v.camera, v.width, v.height))
+      setView(v.texture, v.camera)
+      if (v.shadowFilter !== null) shadowSys.markMatricesDirty()
+    }
+    shadowSys.flushMatrices(params => receivingTargets(t => setTargetParams(t, params)))
+  }
   // The publish pass of every frame runs the pending sync ahead of the
   // paint, so a write made anywhere in the frame's JS is in that frame's
   // picture: the count, the buffers and the bytes of a record write land
-  // together, and nothing shows a frame late. The microtask stays for
-  // writes made outside a frame. Registered outside any owner: the scene's
-  // own dispose unhooks it (an autoFree: false scene outlives the owner it
+  // together, and nothing shows a frame late. With nothing scheduled it
+  // follows native motion instead. The microtask stays for writes made
+  // outside a frame. Registered outside any owner: the scene's own
+  // dispose unhooks it (an autoFree: false scene outlives the owner it
   // was created in).
   let unhook = runWithOwner(null, () =>
     onBeforeRender(
       () => {
         if (scheduled) sync()
+        else follow()
       },
       { publish: true },
     ),
@@ -2444,6 +2481,13 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       if (disposed) return
       setTransition(root, ms === null ? null : { stagger: ms })
     },
+    setTimeScale(scale) {
+      if (disposed) return
+      setTimeScale(root, scale)
+    },
+    timeRate() {
+      return timeRate(root) ?? 1
+    },
     setParams(params) {
       if (disposed) return
       Object.assign(sceneParams, params)