@solidrt/3d 0.0.71 → 0.0.72

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
@@ -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)