@solidrt/2d 0.0.60 → 0.0.61

package/src/components/camera2d.tsx

@@ -33,8 +33,9 @@ const MAX_CAMERA_DT = 0.1
  * change the pose at runtime through `ref`'s set/glideTo/fit/follow and
  * the verbs. Every other prop is live, forwarded to the control as a
  * getter and read where it applies, so a world, a zoom range, a pivot,
- * a dead zone or a rate follows its prop, and a bounds or pivot change
- * re-clamps and pushes the pose at once - the `<OrbitCamera>` rule.
+ * the follow's zones, the offset lane or a rate follows its prop, and a
+ * bounds, pivot or offset change re-clamps and pushes the pose at once -
+ * the `<OrbitCamera>` rule.
  * `viewport` defaults to the view's own size. Frames run only while the
  * camera moves (`active()`), so a resting camera leaves the app
  * demand-driven idle.
@@ -67,13 +68,14 @@ export let Camera2d: VoidComponent<Camera2dProps> = props => {
       })
     },
   )
-  // A bounds or pivot prop change re-clamps and pushes the pose at once
-  // (set({}) applies the clamps). Deferred: the creation already clamped
-  // and pushed the initial pose. Untracked: the control reads the options
-  // through the getters while it applies them, and the apply wants the
-  // values of that moment (the compute above is what tracks them).
+  // A bounds, pivot or offset prop change re-clamps and pushes the pose
+  // at once (set({}) applies the clamps and the lanes). Deferred: the
+  // creation already clamped and pushed the initial pose. Untracked: the
+  // control reads the options through the getters while it applies
+  // them, and the apply wants the values of that moment (the compute
+  // above is what tracks them).
   createEffect(
-    () => [options.world, options.minZoom, options.maxZoom, options.pivot],
+    () => [options.world, options.minZoom, options.maxZoom, options.pivot, options.offset],
     () => untrack(() => cam.set({})),
     { defer: true },
   )

package/src/components/index.ts

@@ -22,6 +22,8 @@ export { Sprite } from "./sprite.tsx"
 export type { SpritePointerProps, SpriteProps } from "./sprite.tsx"
 export { Camera2d } from "./camera2d.tsx"
 export type { Camera2dProps } from "./camera2d.tsx"
+export { Shot, Shots } from "./shots.tsx"
+export type { ShotProps, ShotsProps } from "./shots.tsx"
 export { View2d } from "./view2d.tsx"
 export type { View2dProps } from "./view2d.tsx"
 export { TileLayer } from "./tile-layer.tsx"

package/src/components/shots.tsx

@@ -0,0 +1,90 @@
+import { createContext, createEffect, onCleanup, onFrame, untrack, useContext } from "@solidrt/core"
+import type { Element, ParentComponent } from "@solidrt/core"
+import { ViewportContext, useSpriteLayer } from "./context.ts"
+import { createShots } from "../shots.ts"
+import type { ShotsHandle } from "../shots.ts"
+import type { ViewHandle } from "../views.ts"
+
+// Cap on the blend loop's per-frame dt in seconds, so the first tick
+// after a suspended stretch cannot leap a blend to its end.
+const MAX_BLEND_DT = 0.1
+
+let ShotsContext = createContext<ShotsHandle>()
+
+export type ShotsProps = {
+  /** The default blend time in seconds when the live shot changes
+   * (0.5); 0 cuts. */
+  blend?: number
+  /** The blender's handle (activate/deactivate/live/camera). */
+  ref?: (shots: ShotsHandle) => void
+  children?: Element
+}
+
+export type ShotProps = {
+  name: string
+  /** The enabled shot with the highest priority is live (default 0;
+   * the most recently enabled wins a tie). Read at mount. */
+  priority?: number
+  /** Whether the shot takes part (default true); live: false withdraws
+   * it and the next by priority goes live, blended. */
+  active?: boolean
+  /** This shot's own blend time when it goes live or withdraws
+   * (default: the container's). */
+  blend?: number
+  children?: Element
+}
+
+/**
+ * createShots as a SpriteLayer (or View2d) child: owns the nearest
+ * view's camera and blends between its `<Shot>` children (Cinemachine's
+ * virtual cameras), each of which provides the view with its camera
+ * redirected to the shot's recording target - so a `<Camera2d>` inside
+ * a `<Shot>` drives that shot, not the view, while its size, handlers
+ * and everything else stay the view's. The blend runs on frames only
+ * while one is in flight.
+ */
+export let Shots: ParentComponent<ShotsProps> = props => {
+  let view = useSpriteLayer().viewport
+  let shots = untrack(() => createShots(view, { blend: props.blend }))
+  createEffect(
+    () => shots.active(),
+    on => {
+      if (!on) return
+      let last: number | null = null
+      return onFrame(tick => {
+        let now = tick / 1000
+        let dt = last === null ? 0 : Math.min(now - last, MAX_BLEND_DT)
+        last = now
+        shots.update(dt)
+      })
+    },
+  )
+  untrack(() => props.ref)?.(shots)
+  return <ShotsContext value={shots}>{props.children}</ShotsContext>
+}
+
+export let Shot: ParentComponent<ShotProps> = props => {
+  let shots = useContext(ShotsContext)
+  let view = useSpriteLayer().viewport
+  let name = untrack(() => props.name)
+  let target = untrack(() => shots.shot(name, { priority: props.priority }))
+  // The view with its camera redirected: a Proxy keeps the view's live
+  // fields (width, height, handlers) live.
+  let redirected = new Proxy(view, {
+    get(t, key, receiver) {
+      if (key === "setCamera") return target.setCamera
+      if (key === "camera") return target.camera
+      return Reflect.get(t, key, receiver)
+    },
+  }) as ViewHandle
+  createEffect(
+    () => props.active ?? true,
+    on => {
+      let blend = untrack(() => props.blend)
+      if (on) shots.activate(name, { blend })
+      else shots.deactivate(name, { blend })
+    },
+  )
+  onCleanup(() => shots.remove(name, { blend: untrack(() => props.blend) }))
+  return <ViewportContext value={redirected}>{props.children}</ViewportContext>
+}

package/src/components/sprite-layer.tsx

@@ -79,6 +79,13 @@ export type SpriteLayerProps = LayerPointerProps & {
    * SpriteLayerOptions.orderBy).
    */
   orderBy?: "y" | "renderOrder"
+  /**
+   * Stagger (ms) on the layer's root: the enters and exits of the sprites
+   * and groups straight under the layer that begin in one frame are spaced
+   * by `index * stagger` (a `<Group>` declaring its own wins for what is
+   * under it). Live: a change applies to the next frame's cascade.
+   */
+  stagger?: number
   label?: string
   /** The layer: sprites, tint, pick, createView. */
   ref?: (layer: LayerHandle) => void
@@ -156,6 +163,7 @@ export let SpriteLayer: ParentComponent<SpriteLayerProps> = props => {
       capacity: props.capacity,
       tint: props.tint,
       orderBy: props.orderBy,
+      stagger: props.stagger,
       label: props.label,
     }),
   )
@@ -165,6 +173,11 @@ export let SpriteLayer: ParentComponent<SpriteLayerProps> = props => {
       if (tint !== undefined) layer.setTint(tint)
     },
   )
+  createEffect(
+    () => props.stagger,
+    ms => layer.setStagger(ms ?? null),
+    { defer: true },
+  )
   untrack(() => props.ref)?.(layer)
   let output = untrack(() => props.output)
   if (output === false) {

package/src/index.ts

@@ -23,6 +23,8 @@ export { projectCamera, unprojectCamera } from "./camera.ts"
 export type { CameraState, CameraUpdate } from "./camera.ts"
 export { createCamera2d } from "./camera2d.ts"
 export type { Camera2d as Camera2dHandle, Camera2dAxes, Camera2dOptions, Camera2dPose, Camera2dTarget, Rect2d } from "./camera2d.ts"
+export { createShots, mixCamera2d } from "./shots.ts"
+export type { ShotTarget, ShotsHandle } from "./shots.ts"
 export { camera2dActions, camera2dBindings } from "./input.ts"
 export type { CameraDevices } from "./input.ts"
 export type {
@@ -69,5 +71,5 @@ export type { AnimationOptions, SpriteAnimation } from "./animation.ts"
 export { fitOversample } from "./oversample.ts"
 export { createAtlas } from "./atlas.ts"
 export type { Atlas, AtlasOptions } from "./atlas.ts"
-export { Camera2d, Group, Sprite, SpriteLayer, TileLayer, View2d, useSpriteLayer } from "./components/index.ts"
-export type { Camera2dProps, GroupProps, LayerPointerProps, SpriteLayerProps, SpritePointerProps, SpriteProps, TileCamera, TileLayerProps, View2dProps } from "./components/index.ts"
+export { Camera2d, Group, Sprite, SpriteLayer, TileLayer, View2d, useSpriteLayer, Shot, Shots } from "./components/index.ts"
+export type { Camera2dProps, GroupProps, LayerPointerProps, SpriteLayerProps, SpritePointerProps, SpriteProps, TileCamera, TileLayerProps, View2dProps, ShotProps, ShotsProps } from "./components/index.ts"

package/src/input.ts

@@ -26,9 +26,10 @@ export let camera2dActions = { pan: "vec2", zoom: "axis", roll: "axis" } as cons
 
 /**
  * The 2d camera's standard bindings: one finger or a mouse drag pans and
- * so do two fingers, a pinch and the wheel zoom about the pointer, a twist
- * rolls; the left stick scrolls, the triggers zoom, the right stick's x
- * rolls; the arrow keys scroll and minus/equals zoom.
+ * so do two fingers, a pinch and the wheel zoom about the pointer, a
+ * double tap zooms one octave in at its point (the map convention), a
+ * twist rolls; the left stick scrolls, the triggers zoom, the right
+ * stick's x rolls; the arrow keys scroll and minus/equals zoom.
  */
 export function camera2dBindings(devices: CameraDevices): Binding[] {
   let out: Binding[] = []
@@ -39,6 +40,7 @@ export function camera2dBindings(devices: CameraDevices): Binding[] {
       { action: "pan", source: pointer.pan },
       { action: "zoom", source: pointer.pinch },
       { action: "zoom", source: pointer.wheel },
+      { action: "zoom", source: pointer.doubleTap },
       { action: "roll", source: pointer.twist },
     )
   }

package/src/layer.ts

@@ -35,6 +35,7 @@ import type {
   MoveOptions as CoreMoveOptions,
   NodeEndpoint,
   NodeId,
+  NodeMotionSpec,
   NodeTransition,
   NodeTransitionSpec,
   QueryFilter,
@@ -1265,7 +1266,9 @@ export type SpriteTransition = {
   position?: SpriteTransitionSpec<[number, number]>
   rotation?: SpriteTransitionSpec<number>
   scale?: SpriteTransitionSpec<[number, number] | number>
-  all?: NodeTransitionSpec
+  /** The catch-all: a motion alone, no `from`/`exit` (those name a
+   * component's units, so they live on the per-component specs). */
+  all?: NodeMotionSpec
   stagger?: number
 }
 

package/src/shots.ts

@@ -0,0 +1,50 @@
+// Shots and blends over the 2d camera (okf/design/camera-controls.md):
+// core's blender specialized to the layers' CameraState - a control
+// drives a shot's recording target instead of the view, the blender
+// owns the view's setCamera, and a switch blends x/y/rotation/pivot
+// linearly and the zoom in log space (a zoom blend in linear space
+// races in and crawls out).
+
+import { createShotBlend } from "@solidrt/core/camera-control"
+import type { ShotBlend, ShotBlendOptions, ShotTarget as RecordingTarget } from "@solidrt/core/camera-control"
+import type { CameraState } from "./camera.ts"
+import type { Camera2dTarget } from "./camera2d.ts"
+
+// The camera every shot starts from: the layers' own defaults (world 0,0
+// at the top-left, pixel for pixel).
+const INITIAL: CameraState = { x: 0, y: 0, zoom: 1, rotation: 0, pivotX: 0, pivotY: 0 }
+
+let lerp = (a: number, b: number, t: number) => a + (b - a) * t
+
+/** Interpolate two 2d cameras: everything linear, the zoom in log space. */
+export let mixCamera2d = (a: CameraState, b: CameraState, t: number): CameraState => ({
+  x: lerp(a.x, b.x, t),
+  y: lerp(a.y, b.y, t),
+  zoom: a.zoom * Math.pow(b.zoom / a.zoom, t),
+  rotation: lerp(a.rotation, b.rotation, t),
+  pivotX: lerp(a.pivotX, b.pivotX, t),
+  pivotY: lerp(a.pivotY, b.pivotY, t),
+})
+
+export type ShotsHandle = ShotBlend<CameraState>
+export type ShotTarget = RecordingTarget<CameraState> & Camera2dTarget
+
+/**
+ * Shots over a view (or several: one output over a scene's layers):
+ * `shot(name, { priority? })` returns the target a `createCamera2d` (or
+ * a `<Camera2d>` through a custom viewport) drives; `activate(name, {
+ * blend? })` makes it live when its priority wins, blending from the
+ * current output; `update(dt)` from a frame loop while `active()`.
+ */
+export function createShots(target: Camera2dTarget | Camera2dTarget[], options: ShotBlendOptions = {}): ShotsHandle {
+  let targets = Array.isArray(target) ? target : [target]
+  for (let t of targets) if (!t || typeof t.setCamera !== "function") throw new Error("createShots: every target needs setCamera() (a view)")
+  return createShotBlend<CameraState>(
+    camera => {
+      for (let t of targets) t.setCamera(camera)
+    },
+    mixCamera2d,
+    INITIAL,
+    options,
+  )
+}

package/src/tiles-math.ts

@@ -0,0 +1,62 @@
+// The pure tile-grid math: cell and rect validation, a cell's chunk and
+// record slot, and the walk of a rect chunk by chunk - plain arithmetic
+// with no GPU imports, so the headless check (checks/tiles-check.ts)
+// drives it directly; tiles.ts wraps it with the chunk textures.
+
+/** Throw unless (col, row) is a cell of the cols x rows grid. */
+export function checkCell(verb: string, col: number, row: number, cols: number, rows: number): void {
+  if (!(Number.isInteger(col) && Number.isInteger(row) && col >= 0 && col < cols && row >= 0 && row < rows)) {
+    throw new Error(`${verb}: cell ${col}, ${row} outside the ${cols} x ${rows} grid`)
+  }
+}
+
+/** Throw unless the w x h rect at (col, row) is non-empty and lies inside
+ * the cols x rows grid. */
+export function checkRect(verb: string, col: number, row: number, w: number, h: number, cols: number, rows: number): void {
+  if (!(Number.isInteger(col) && Number.isInteger(row) && Number.isInteger(w) && Number.isInteger(h) && w > 0 && h > 0 && col >= 0 && row >= 0 && col + w <= cols && row + h <= rows)) {
+    throw new Error(`${verb}: rect ${col}, ${row} of ${w} x ${h} outside the ${cols} x ${rows} grid`)
+  }
+}
+
+/** A cell's chunk index in a grid chunked chunkTiles x chunkTiles, with
+ * chunkCols chunks across: chunks are numbered row-major. */
+export function chunkOf(col: number, row: number, chunkTiles: number, chunkCols: number): number {
+  return Math.floor(row / chunkTiles) * chunkCols + Math.floor(col / chunkTiles)
+}
+
+/** A cell's record offset inside its chunk's records: cells are row-major
+ * within the chunk, `floatsPerCell` floats each. */
+export function slotOf(col: number, row: number, chunkTiles: number, floatsPerCell: number): number {
+  return ((row % chunkTiles) * chunkTiles + (col % chunkTiles)) * floatsPerCell
+}
+
+/**
+ * Walk the w x h rect at (col, row) chunk by chunk: `visit` is called once
+ * per chunk the rect touches with the chunk's index and the rect's slice
+ * of it, the cells [colA, colB) x [rowA, rowB) - chunk rows outer, chunk
+ * columns inner, so a caller writing records advances through each
+ * chunk's slice row by row.
+ */
+export function eachChunkSlice(
+  col: number,
+  row: number,
+  w: number,
+  h: number,
+  chunkTiles: number,
+  chunkCols: number,
+  visit: (index: number, colA: number, colB: number, rowA: number, rowB: number) => void,
+): void {
+  let cr0 = Math.floor(row / chunkTiles)
+  let cr1 = Math.floor((row + h - 1) / chunkTiles)
+  let cc0 = Math.floor(col / chunkTiles)
+  let cc1 = Math.floor((col + w - 1) / chunkTiles)
+  for (let cr = cr0; cr <= cr1; cr++) {
+    let rowA = Math.max(row, cr * chunkTiles)
+    let rowB = Math.min(row + h, (cr + 1) * chunkTiles)
+    for (let cc = cc0; cc <= cc1; cc++) {
+      let colA = Math.max(col, cc * chunkTiles)
+      let colB = Math.min(col + w, (cc + 1) * chunkTiles)
+      visit(cr * chunkCols + cc, colA, colB, rowA, rowB)
+    }
+  }
+}

package/src/tiles.ts

@@ -39,6 +39,7 @@ import { checkTint } from "./layer.ts"
 import { checkOversample, thrashSentinel } from "./oversample.ts"
 import { FLOATS_PER_SPRITE } from "./records.ts"
 import { FRAGMENT, INSTANCE_ATTRIBUTES, VERTEX } from "./shaders.ts"
+import { checkCell, checkRect, chunkOf, eachChunkSlice, slotOf } from "./tiles-math.ts"
 
 const RESOLVED = Promise.resolve()
 
@@ -324,14 +325,10 @@ export function createTileLayer(
     return chunk
   }
 
-  let checkCell = (col: number, row: number, verb: string): void => {
-    if (!(Number.isInteger(col) && Number.isInteger(row) && col >= 0 && col < cols && row >= 0 && row < rows)) {
-      throw new Error(`${verb}: cell ${col}, ${row} outside the ${cols} x ${rows} grid`)
-    }
-  }
-  // A cell's chunk index, and its record offset inside that chunk.
-  let chunkOf = (col: number, row: number): number => Math.floor(row / chunkTiles) * chunkCols + Math.floor(col / chunkTiles)
-  let slot = (col: number, row: number): number => ((row % chunkTiles) * chunkTiles + (col % chunkTiles)) * FLOATS_PER_SPRITE
+  // A cell's chunk index, and its record offset inside that chunk
+  // (tiles-math.ts, bound to this layer's grid).
+  let chunkAt = (col: number, row: number): number => chunkOf(col, row, chunkTiles, chunkCols)
+  let slot = (col: number, row: number): number => slotOf(col, row, chunkTiles, FLOATS_PER_SPRITE)
   // Write one cell's record: the quad at the cell, the frame's UVs, and
   // the tint - the one given, else the default when the cell comes up from
   // empty (a re-set keeps its tint: absent keys keep their values, like
@@ -393,8 +390,8 @@ export function createTileLayer(
     },
     setTile(col, row, frame, opts) {
       if (disposed) return
-      checkCell(col, row, "setTile")
-      let index = chunkOf(col, row)
+      checkCell("setTile", col, row, cols, rows)
+      let index = chunkAt(col, row)
       let at = slot(col, row)
       let chunk = resident.get(index)
       if (frame === null) {
@@ -411,9 +408,7 @@ export function createTileLayer(
     },
     setTiles(col, row, w, h, cells, opts) {
       if (disposed) return
-      if (!(Number.isInteger(col) && Number.isInteger(row) && Number.isInteger(w) && Number.isInteger(h) && w > 0 && h > 0 && col >= 0 && row >= 0 && col + w <= cols && row + h <= rows)) {
-        throw new Error(`setTiles: rect ${col}, ${row} of ${w} x ${h} outside the ${cols} x ${rows} grid`)
-      }
+      checkRect("setTiles", col, row, w, h, cols, rows)
       if (cells.length !== w * h) throw new Error(`setTiles: a ${w} x ${h} rect takes ${w * h} cells, got ${cells.length}`)
       if (opts?.tint !== undefined) checkTint("setTiles", opts.tint)
       let cellTint = opts?.tint
@@ -440,63 +435,52 @@ export function createTileLayer(
       // sub-rect walked row by row with the record offset advancing, one
       // dirty mark at the end. A chunk the slice only clears is never
       // allocated.
-      let cr0 = Math.floor(row / chunkTiles)
-      let cr1 = Math.floor((row + h - 1) / chunkTiles)
-      let cc0 = Math.floor(col / chunkTiles)
-      let cc1 = Math.floor((col + w - 1) / chunkTiles)
-      for (let cr = cr0; cr <= cr1; cr++) {
-        let rowA = Math.max(row, cr * chunkTiles)
-        let rowB = Math.min(row + h, (cr + 1) * chunkTiles)
-        for (let cc = cc0; cc <= cc1; cc++) {
-          let colA = Math.max(col, cc * chunkTiles)
-          let colB = Math.min(col + w, (cc + 1) * chunkTiles)
-          let index = cr * chunkCols + cc
-          let chunk = resident.get(index)
-          let r = chunk ? chunk.records : null
-          for (let y = rowA; y < rowB; y++) {
-            let at = slot(colA, y)
-            let i = (y - row) * w + (colA - col)
-            for (let x = colA; x < colB; x++, at += FLOATS_PER_SPRITE, i++) {
-              let u0: number
-              let v0: number
-              let u1: number
-              let v1: number
-              if (idx !== null) {
-                let k = idx[i]!
-                if (k === -1 || k === CLEAR_INDEX) {
-                  if (r !== null) clearCell(r, at)
-                  continue
-                }
-                let b = k * 4
-                u0 = uv![b]!
-                v0 = uv![b + 1]!
-                u1 = uv![b + 2]!
-                v1 = uv![b + 3]!
-              } else {
-                let f = objs![i]
-                if (f === null || f === undefined) {
-                  if (r !== null) clearCell(r, at)
-                  continue
-                }
-                u0 = f.u0
-                v0 = f.v0
-                u1 = f.u1
-                v1 = f.v1
+      eachChunkSlice(col, row, w, h, chunkTiles, chunkCols, (index, colA, colB, rowA, rowB) => {
+        let chunk = resident.get(index)
+        let r = chunk ? chunk.records : null
+        for (let y = rowA; y < rowB; y++) {
+          let at = slot(colA, y)
+          let i = (y - row) * w + (colA - col)
+          for (let x = colA; x < colB; x++, at += FLOATS_PER_SPRITE, i++) {
+            let u0: number
+            let v0: number
+            let u1: number
+            let v1: number
+            if (idx !== null) {
+              let k = idx[i]!
+              if (k === -1 || k === CLEAR_INDEX) {
+                if (r !== null) clearCell(r, at)
+                continue
               }
-              if (r === null) {
-                chunk = allocate(index)
-                r = chunk.records
+              let b = k * 4
+              u0 = uv![b]!
+              v0 = uv![b + 1]!
+              u1 = uv![b + 2]!
+              v1 = uv![b + 3]!
+            } else {
+              let f = objs![i]
+              if (f === null || f === undefined) {
+                if (r !== null) clearCell(r, at)
+                continue
               }
-              writeCell(r, at, x, y, u0, v0, u1, v1, cellTint)
+              u0 = f.u0
+              v0 = f.v0
+              u1 = f.u1
+              v1 = f.v1
             }
+            if (r === null) {
+              chunk = allocate(index)
+              r = chunk.records
+            }
+            writeCell(r, at, x, y, u0, v0, u1, v1, cellTint)
           }
-          if (chunk) touch(chunk)
         }
-      }
+        if (chunk) touch(chunk)
+      })
     },
     getTile(col, row) {
-      checkCell(col, row, "getTile")
-      let chunk = resident.get(chunkOf(col, row))
+      checkCell("getTile", col, row, cols, rows)
+      let chunk = resident.get(chunkAt(col, row))
       let at = slot(col, row)
       if (!chunk || chunk.records[at + 2] === 0) return null
       let r = chunk.records