@solidrt/2d 0.0.55 → 0.0.57

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/2d",
-  "version": "0.0.55",
+  "version": "0.0.57",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -15,7 +15,7 @@
     "AGENTS.md"
   ],
   "peerDependencies": {
-    "@solidjs/signals": "2.0.0-rc.4",
-    "@solidrt/core": "0.0.55"
+    "@solidjs/signals": "2.0.0-rc.6",
+    "@solidrt/core": "0.0.57"
   }
 }

package/src/animation.ts

@@ -0,0 +1,178 @@
+// Sprite frame animation: a clip (frames + fps) with a shared clock that
+// steps every attached sprite's frame through setSprite. One timer per
+// playing clip and one frame write per attached sprite per STEP (not per
+// display frame), so an 8fps walk cycle generates 8 publishes a second and
+// a paused clip costs nothing - the demand-gate story unchanged. The clip
+// does not own its sprites (removeSprite prunes lazily on the next step),
+// and a sprite belongs to at most one animation. Plain JS over setSprite,
+// so it works on both layer kinds and composes with <Sprite> via ref (leave
+// the frame prop off - the clip owns that field).
+import { getOwner, onCleanup } from "@solidrt/core"
+import type { Frame } from "./frames.ts"
+import type { Sprite } from "./layer.ts"
+import { setSprite } from "./layer.ts"
+
+// Timer period as a fraction of the clip's frame duration: the step index
+// is computed from the wall clock (drift-free), so the timer only decides
+// how late after a frame boundary the step lands - half a frame bounds
+// that lateness at half a frame, where a full-frame period could show a
+// frame almost a whole frame late.
+const TICK_RATIO = 0.5
+
+export type AnimationOptions = {
+  /** Wrap around (default) or play once and hold the last frame. */
+  loop?: boolean
+  /** Skip the owner-scoped auto-dispose (the core resource contract). */
+  autoFree?: boolean
+}
+
+export type SpriteAnimation = {
+  /** Current frame index into the clip. */
+  readonly frame: number
+  /** True while the clock advances: born playing, false after pause() and
+   * after a one-shot ends. */
+  readonly playing: boolean
+  /**
+   * Attach a sprite: it shows the clip's current frame immediately and
+   * steps with the shared clock (every attached sprite shows the SAME
+   * index). A sprite belongs to at most one animation - attaching detaches
+   * it from its previous one.
+   */
+  add(sprite: Sprite): void
+  /** Detach; the sprite keeps the frame it is showing. */
+  remove(sprite: Sprite): void
+  /** Resume a paused clip (phase kept), or replay a finished one-shot
+   * from frame 0. */
+  play(): void
+  /** Freeze the clock; attached sprites hold the current frame. */
+  pause(): void
+  /** One-shot clips (loop: false): the last frame finished its display
+   * time. Fires once per play-through, never on pause or dispose. */
+  onFinish?: () => void
+  /** Stop the clock and detach every sprite. Owner-scoped like a layer
+   * (opt out with autoFree: false). */
+  dispose(): void
+}
+
+// A sprite's current animation - add() moves the sprite here, so two clips
+// never fight over one sprite's frame field.
+let attachedTo = new WeakMap<Sprite, SpriteAnimation>()
+
+/**
+ * A frame animation clip: `frames` (usually a slice of a `grid()` result)
+ * played at `fps`. Sprites attach with `add`; the clip steps their `frame`
+ * on its own wall-clock timer, independent of display rate.
+ */
+export function createAnimation(frames: Frame[], fps: number, opts?: AnimationOptions): SpriteAnimation {
+  if (frames.length === 0) throw new Error("createAnimation: frames is empty")
+  if (!(Number.isFinite(fps) && fps > 0)) {
+    throw new Error(`createAnimation: fps must be positive, got ${fps}`)
+  }
+  let loop = opts?.loop !== false
+  let sprites = new Set<Sprite>()
+  let current = 0
+  let playing = true
+  let ended = false
+  let disposed = false
+  let timer: number | null = null
+  let elapsedBase = 0 // ms of clip time accumulated before the running stretch
+  let runStart = 0 // performance.now() when the clock last started
+
+  function startClock(): void {
+    if (timer !== null || !playing || sprites.size === 0) return
+    // A looping single-frame clip never changes; a one-shot still needs
+    // the clock once, to end.
+    if (loop && frames.length === 1) return
+    runStart = performance.now()
+    timer = setInterval(tick, (1000 / fps) * TICK_RATIO)
+  }
+
+  function stopClock(): void {
+    if (timer === null) return
+    elapsedBase += performance.now() - runStart
+    clearInterval(timer)
+    timer = null
+  }
+
+  function writeAll(): void {
+    let frame = frames[current]!
+    for (let sprite of sprites) {
+      if (sprite.layer === null) {
+        // Removed sprite: prune (deleting during for..of is safe on a Set).
+        sprites.delete(sprite)
+        attachedTo.delete(sprite)
+      } else setSprite(sprite, { frame })
+    }
+    if (sprites.size === 0) stopClock()
+  }
+
+  function setIndex(idx: number): void {
+    if (idx === current) return
+    current = idx
+    writeAll()
+  }
+
+  function tick(): void {
+    let raw = Math.floor(((elapsedBase + performance.now() - runStart) * fps) / 1000)
+    if (!loop && raw >= frames.length) {
+      // The last frame has shown for its full duration: hold it and stop.
+      setIndex(frames.length - 1)
+      stopClock()
+      playing = false
+      ended = true
+      handle.onFinish?.()
+      return
+    }
+    setIndex(loop ? raw % frames.length : Math.min(raw, frames.length - 1))
+  }
+
+  let handle: SpriteAnimation = {
+    get frame() {
+      return current
+    },
+    get playing() {
+      return playing
+    },
+    onFinish: undefined,
+    add(sprite) {
+      if (disposed) throw new Error("createAnimation: add on a disposed animation")
+      attachedTo.get(sprite)?.remove(sprite)
+      attachedTo.set(sprite, handle)
+      sprites.add(sprite)
+      setSprite(sprite, { frame: frames[current]! })
+      startClock()
+    },
+    remove(sprite) {
+      if (!sprites.delete(sprite)) return
+      attachedTo.delete(sprite)
+      if (sprites.size === 0) stopClock()
+    },
+    play() {
+      if (disposed || playing) return
+      if (ended) {
+        ended = false
+        elapsedBase = 0
+        current = 0
+        writeAll()
+      }
+      playing = true
+      startClock()
+    },
+    pause() {
+      if (!playing) return
+      stopClock()
+      playing = false
+    },
+    dispose() {
+      if (disposed) return
+      stopClock()
+      playing = false
+      disposed = true
+      for (let sprite of sprites) attachedTo.delete(sprite)
+      sprites.clear()
+    },
+  }
+
+  if (opts?.autoFree !== false && getOwner()) onCleanup(() => handle.dispose())
+  return handle
+}

package/src/atlas.ts

@@ -1,52 +1,54 @@
-// Atlas creation: encoded image bytes to a GPU texture plus its frame table.
-// Thin by design - the frame math lives in frames.ts (pure, checkable) and
-// the texture is an ordinary core texture. createImage is NOT used here: it
-// never forwards sampler options, and pixel-art atlases want
-// `filter: "nearest"` (render small, display big with hard pixels).
-import { createTexture, decodeImage } from "@solidrt/core"
-import type { TextureId } from "@solidrt/core/gpu"
-import type { Frame } from "./frames.ts"
-import { grid } from "./frames.ts"
-import type { GridOptions } from "./frames.ts"
+// Atlas creation: decoded pixels to a GPU texture plus the pixel size the
+// slicers measure in. Thin by design - the frame math lives in frames.ts
+// (pure, checkable) and the texture is an ordinary core texture. createImage
+// is NOT used here: it never forwards sampler options, and pixel-art atlases
+// want `filter: "nearest"` (render small, display big with hard pixels).
+import { createTexture } from "@solidrt/core"
+import type { DecodedImage } from "@solidrt/core"
+import type { SamplerOptions, TextureId } from "@solidrt/core/gpu"
 
+/**
+ * A texture with its pixel size: what `grid` and `namedFrames` slice, and
+ * whose `texture` a layer samples. A plain record, so a texture that did not
+ * come through `createAtlas` - a render target, a camera frame - is an atlas
+ * as a literal: `{ texture, width, height }`.
+ */
 export type Atlas = {
   /** The atlas texture, sampled by every sprite in layers created over it. */
   texture: TextureId
+  /** Pixel size, the space the slicers measure rects and gaps in. */
   width: number
   height: number
-  /** Frames in cell order when created via the grid option, else empty. */
-  frames: Frame[]
 }
 
-export type AtlasOptions = {
-  /**
-   * Sampling: "nearest" is the pixel-art path (hard pixels at any scale),
-   * "linear" (default) the photographic one. Fixed at creation, like every
-   * core texture.
-   */
-  filter?: "nearest" | "linear"
-  /** Slice a uniform sheet at creation: cols x rows of equal cells. */
-  grid?: { cols: number; rows: number } & Omit<GridOptions, "width" | "height">
+/**
+ * Sampling is core's `SamplerOptions`, fixed at creation like every core
+ * texture: `filter` ("nearest" is the pixel-art path with hard pixels at any
+ * scale, "linear" the default photographic one), `wrap`, `mipmap` (a chain
+ * for atlases drawn far below their texel size) and `anisotropy`.
+ */
+export type AtlasOptions = SamplerOptions & {
   label?: string
   /** Skip the owner-scoped auto-free (the core createTexture contract). */
   autoFree?: boolean
 }
 
 /**
- * Decode encoded image bytes (PNG, JPEG, ...) into an atlas texture. Bytes
- * come from `import sheet from "./sheet.png" with { type: "binary" }` or
- * `await file("assets/sheet.png").bytes()`. Freed with the owning reactive
- * scope like any core texture (opt out with `{ autoFree: false }`).
+ * Upload decoded pixels as an atlas texture. `image` is a core
+ * `DecodedImage` (`{ data, width, height }`, premultiplied RGBA8): an
+ * encoded sheet goes through `decodeImage` first -
+ * `createAtlas(decodeImage(sheet), { filter: "nearest" })`, with `sheet`
+ * from `import sheet from "./sheet.png" with { type: "binary" }` or
+ * `await file("assets/sheet.png").bytes()` - and pixels built in code pass
+ * as they are. Freed with the owning reactive scope like any core texture
+ * (opt out with `{ autoFree: false }`).
  */
-export function createAtlas(bytes: Uint8Array, opts?: AtlasOptions): Atlas {
-  let decoded = decodeImage(bytes)
-  let texture = createTexture(decoded.data, decoded.width, decoded.height, {
+export function createAtlas(image: DecodedImage, opts?: AtlasOptions): Atlas {
+  let { data, width, height } = image
+  let texture = createTexture(data, width, height, {
+    ...opts,
     filter: opts?.filter ?? "linear",
     label: opts?.label ?? "atlas",
-    autoFree: opts?.autoFree,
   })
-  let frames = opts?.grid
-    ? grid(opts.grid.cols, opts.grid.rows, { ...opts.grid, width: decoded.width, height: decoded.height })
-    : []
-  return { texture, width: decoded.width, height: decoded.height, frames }
+  return { texture, width, height }
 }

package/src/camera.ts

@@ -0,0 +1,111 @@
+// The 2d camera vocabulary, pure: the one camera type both layers share
+// and its world <-> screen mapping as plain functions - no GPU or GUI
+// imports, so the checks rig (checks/camera-check.ts) exercises this
+// module headless on the flux binary. Three consumers implement or undo
+// exactly this mapping and must agree with it: the vertex stages
+// (shaders.ts, uCamera + uCameraRot), the tile layer's composite
+// transform (the <view> props in components/tile-layer.tsx) and the pointer inverse
+// (spriteDispatch in layer.ts, which calls unprojectCamera directly). The
+// check keeps the spellings from drifting.
+
+/**
+ * A camera over a 2d world - the sprite layer's `setCamera`/`camera` prop
+ * and the tile layer's `TileCamera` alike. The world point (`x`, `y`) is
+ * shown at the viewport point (`pivotX`, `pivotY`), the world scaled by
+ * `zoom` and rotated by `rotation` ABOUT that pivot. Rotation turns the
+ * world clockwise (y-down) about the pivot; to render a heading `h`
+ * upward use `rotation = -h - Math.PI / 2`. The pivot defaults to (0, 0),
+ * which makes `{ x, y, zoom }` mean "world x/y at the viewport top-left" -
+ * the plain scrolling camera.
+ *
+ * As a `setCamera` update, absent keys keep their values (the params
+ * rule); as an argument to projectCamera/unprojectCamera, absent keys
+ * read as the defaults (x/y/rotation 0, zoom 1, pivot (0, 0)).
+ */
+export type CameraUpdate = {
+  /** World pixel shown at the pivot (the viewport top-left by default). */
+  x?: number
+  y?: number
+  /** World-to-screen scale; 1 is pixel-for-pixel. */
+  zoom?: number
+  /** Rotation, radians, clockwise (y-down), about the pivot. */
+  rotation?: number
+  /** Viewport point the camera's world point pins to; default (0, 0). */
+  pivotX?: number
+  pivotY?: number
+}
+
+/** A camera snapshot (a layer's `camera()`): CameraUpdate's fields, all
+ * present - the argument for projectCamera/unprojectCamera. */
+export type CameraState = Required<CameraUpdate>
+
+const CAMERA_FIELDS = ["x", "y", "zoom", "rotation", "pivotX", "pivotY"] as const
+
+/**
+ * Validate a setCamera update (throws - the dev validation policy): every
+ * present field must be finite, zoom additionally positive. A NaN rotation
+ * or pivot would otherwise poison the uniforms and blank the layer with no
+ * error. Internal - both layer kinds call it at the top of setCamera.
+ */
+export function checkCamera(update: CameraUpdate): void {
+  for (let key of CAMERA_FIELDS) {
+    let value = update[key]
+    if (value !== undefined && !Number.isFinite(value)) {
+      throw new Error(`setCamera: ${key} must be a finite number, got ${value}`)
+    }
+  }
+  if (update.zoom !== undefined && update.zoom <= 0) {
+    throw new Error(`setCamera: zoom must be positive, got ${update.zoom}`)
+  }
+}
+
+/**
+ * World -> screen under a camera:
+ * `pivot + R(rotation) * zoom * (world - cam)`. Screen means the layer's
+ * viewport pixels (the sprite layer's output, the tile world's container).
+ */
+export function projectCamera(camera: CameraUpdate, worldX: number, worldY: number): [number, number] {
+  let zoom = camera.zoom ?? 1
+  let rotation = camera.rotation ?? 0
+  let c = Math.cos(rotation)
+  let s = Math.sin(rotation)
+  let dx = (worldX - (camera.x ?? 0)) * zoom
+  let dy = (worldY - (camera.y ?? 0)) * zoom
+  return [(camera.pivotX ?? 0) + dx * c - dy * s, (camera.pivotY ?? 0) + dx * s + dy * c]
+}
+
+/** Screen -> world: the exact inverse of projectCamera. */
+export function unprojectCamera(camera: CameraUpdate, screenX: number, screenY: number): [number, number] {
+  let zoom = camera.zoom ?? 1
+  let rotation = camera.rotation ?? 0
+  let c = Math.cos(rotation)
+  let s = Math.sin(rotation)
+  let dx = screenX - (camera.pivotX ?? 0)
+  let dy = screenY - (camera.pivotY ?? 0)
+  return [(camera.x ?? 0) + (dx * c + dy * s) / zoom, (camera.y ?? 0) + (dy * c - dx * s) / zoom]
+}
+
+/** A camera at the defaults: what a layer or view starts with. */
+export function defaultCamera(): CameraState {
+  return { x: 0, y: 0, zoom: 1, rotation: 0, pivotX: 0, pivotY: 0 }
+}
+
+/** Apply a setCamera update in place: absent keys keep their values (the
+ * params rule). Validate with checkCamera first. */
+export function applyCamera(camera: CameraState, update: CameraUpdate): void {
+  if (update.x !== undefined) camera.x = update.x
+  if (update.y !== undefined) camera.y = update.y
+  if (update.zoom !== undefined) camera.zoom = update.zoom
+  if (update.rotation !== undefined) camera.rotation = update.rotation
+  if (update.pivotX !== undefined) camera.pivotX = update.pivotX
+  if (update.pivotY !== undefined) camera.pivotY = update.pivotY
+}
+
+/** The shared params the vertex stages (shaders.ts) read for a camera:
+ * uCamera [x, y, zoom, zoom] and uCameraRot [cos, sin, pivotX, pivotY]. */
+export function cameraParams(camera: CameraState): { uCamera: [number, number, number, number]; uCameraRot: [number, number, number, number] } {
+  return {
+    uCamera: [camera.x, camera.y, camera.zoom, camera.zoom],
+    uCameraRot: [Math.cos(camera.rotation), Math.sin(camera.rotation), camera.pivotX, camera.pivotY],
+  }
+}