@solidrt/2d 0.0.56 → 0.0.58

package/examples/tiles.tsx

@@ -7,15 +7,23 @@
 // The camera flies a ship-style path: a fixed screen pivot near the bottom
 // of the viewport, the world panning and ROTATING under it so the flight
 // heading always points up - the <TileLayer> camera prop with rotation and
-// pivot (a leaf transform, never a re-bake). A timer edits tiles while it
-// runs: beacon markers along the road's center line blink, and each blink's
-// batch of setTile calls re-bakes only the chunks the beacons land in.
+// pivot (a leaf transform, never a re-bake). The world is seeded by ONE
+// setTiles rect write over a Uint16Array of frame indices (-1 where the
+// world is empty), the shape a generator or a worker produces; a timer
+// edits tiles while it runs: beacon markers along the road's center line
+// blink, and each blink's batch of setTile calls re-bakes only the chunks
+// the beacons land in.
 //
 // The atlas is the core logo sliced 2x2 by grid(); a real game would slice
-// a tileset sheet the same way.
-import { createSignal, onFrame, pct, render, windowSize } from "@solidrt/core"
+// a tileset sheet the same way, and the array is the layer's `frames`
+// table the indices name.
+//
+// Debug commands: `state` (resident chunk count) and `cell` ({ col, row }:
+// the frame at a cell, null when empty).
+import { createSignal, decodeImage, onFrame, pct, render, windowSize } from "@solidrt/core"
 import { createAtlas, grid, TileLayer } from "@solidrt/2d"
 import type { TileCamera, TileLayerHandle } from "@solidrt/2d"
+import { registerDebug } from "srt:dev"
 import logoBytes from "./logo.png" with { type: "binary" }
 
 const COLS = 128
@@ -29,23 +37,29 @@ const WORLD = COLS * TILE
 const HITCH_FACTOR = 1.5
 
 function App() {
-  let atlas = createAtlas(logoBytes, { label: "logo-atlas" })
-  let frames = grid(2, 2, { width: atlas.width, height: atlas.height })
+  let atlas = createAtlas(decodeImage(logoBytes), { label: "logo-atlas" })
+  let frames = grid(atlas, 2, 2)
 
   let layer!: TileLayerHandle
   let seed = (l: TileLayerHandle) => {
     layer = l
     // A solid ring "road" around the world center: continuous under the
     // flight path, empty everywhere else - the empty regions are the point,
-    // their chunks never allocate.
+    // their chunks never allocate, since a rect write allocates a chunk
+    // only for the first frame it carries there. -1 is the clear (a
+    // Uint16Array holds it as 0xffff, the same bits).
     let c = COLS / 2
+    let cells = new Uint16Array(COLS * ROWS).fill(-1)
     for (let row = 0; row < ROWS; row++) {
       for (let col = 0; col < COLS; col++) {
         let d = Math.hypot(col - c, row - c)
-        if (d > 40 && d < 52) l.setTile(col, row, frames[(col ^ row) % 4]!)
+        if (d > 40 && d < 52) cells[row * COLS + col] = (col ^ row) % 4
       }
     }
+    l.setTiles(0, 0, COLS, ROWS, cells)
   }
+  registerDebug("state", () => ({ chunks: layer.chunks.length }))
+  registerDebug("cell", (args?: { col?: number; row?: number }) => layer.getTile(args?.col ?? 0, args?.row ?? 0))
 
   // Beacon cells on the road's center line every 7.5 degrees; the interval
   // below blinks them between a marker frame and the road pattern.
@@ -99,6 +113,7 @@ function App() {
           tileW={TILE}
           tileH={TILE}
           atlas={atlas.texture}
+          frames={frames}
           camera={camera()}
           label="tile-world"
           ref={seed}

package/examples/views.tsx

@@ -0,0 +1,177 @@
+// Layer views (layer.createView): the world rendered twice from one set of
+// sprites - the window-filling main view under a pannable, zoomable camera
+// and a corner MINIMAP showing the whole world, no sprite mirrored. A view
+// is one more target over the layer's own instance buffers: the sprites
+// are added once, the roamer moves once, and both renderings follow at
+// zero per-frame JS beyond each camera's writes. The minimap carries the
+// layer's pointer dispatch under its own camera: a tap on it glides the
+// main camera to that world point (the view's root listener, `e.x`/`e.y`
+// in world pixels), and a tap on a sprite in the minimap selects it as it
+// would in the main view (the same sprite handlers, the walk ending at
+// the VIEW). A stroked rect over the minimap outlines the main camera's
+// view rect through `map.project`.
+//
+// Debug commands: `state` returns both cameras and the outline rect;
+// `camera` parks the main camera when given x/y/zoom and returns its
+// pose; `selected` the selected sprite's world position (null when none),
+// `first` the first sprite's - the one to aim a synthetic tap at.
+import { createEffect, createInputMap, createPointerFeed, createSignal, decodeImage, displayScale, gamepad, onFrame, render, windowSize } from "@solidrt/core"
+import { addSprite, camera2dActions, camera2dBindings, createAtlas, createCamera2d, createSpriteLayer, feedPointer, fitOversample, grid, setSprite } from "@solidrt/2d"
+import type { Camera2dHandle, SpriteHandle, ViewHandle } from "@solidrt/2d"
+import { registerDebug } from "srt:dev"
+import logoBytes from "./logo.png" with { type: "binary" }
+
+const WORLD = { width: 2400, height: 1600 }
+const COUNT = 300
+const SPRITE = 48
+const ROAMER = 72
+const MAX_ZOOM = 4
+// The minimap's pixel size: the whole world fitted into it.
+const MAP_WIDTH = 240
+const MAP_HEIGHT = 160
+const MAP_MARGIN = 16
+const TINT: [number, number, number, number] = [0.75, 0.8, 0.9, 1]
+const SELECTED_TINT: [number, number, number, number] = [1, 0.4, 0.4, 1]
+// Roamer figure-eight: rates in rad/s and the span as a fraction of the world.
+const ROAM_RATE_X = 0.23
+const ROAM_RATE_Y = 0.31
+const ROAM_SPAN = 0.4
+// Cap on a frame's dt in seconds, so a resumed app cannot leap.
+const MAX_DT = 0.1
+
+let cam!: Camera2dHandle
+let map!: ViewHandle
+let selected: SpriteHandle | null = null
+let first: SpriteHandle | null = null
+let outline = { x: 0, y: 0, width: 0, height: 0 }
+
+function App() {
+  let atlas = createAtlas(decodeImage(logoBytes), { label: "logo-atlas" })
+  let frames = grid(atlas, 2, 2)
+  let win = { width: 1, height: 1 }
+  let layer = createSpriteLayer(atlas.texture, { capacity: COUNT + 1, label: "world" })
+  // The main view: the window, under the pannable camera.
+  let main = layer.createView({ width: win.width, height: win.height, clearColor: [0.05, 0.05, 0.09, 1], label: "world" })
+  let select = (sprite: SpriteHandle | null) => {
+    if (selected) setSprite(selected, { tint: TINT })
+    selected = sprite
+    if (selected) setSprite(selected, { tint: SELECTED_TINT })
+  }
+  for (let i = 0; i < COUNT; i++) {
+    let sprite = addSprite(layer, {
+      x: Math.random() * WORLD.width,
+      y: Math.random() * WORLD.height,
+      w: SPRITE,
+      h: SPRITE,
+      frame: frames[i % 4],
+      rotation: Math.random() * Math.PI * 2,
+      tint: TINT,
+    })
+    sprite.onTap = () => select(sprite)
+    if (first === null) first = sprite
+  }
+  let roamer = addSprite(layer, { x: WORLD.width / 2, y: WORLD.height / 2, w: ROAMER, h: ROAMER, frame: frames[0], tint: [1, 0.8, 0.3, 1] })
+
+  // The minimap: the whole world at the fit zoom, world (0, 0) at the
+  // view's top-left (the default pivot), its own clear color.
+  let mapZoom = Math.min(MAP_WIDTH / WORLD.width, MAP_HEIGHT / WORLD.height)
+  map = layer.createView({
+    width: MAP_WIDTH,
+    height: MAP_HEIGHT,
+    camera: { zoom: mapZoom },
+    clearColor: [0.02, 0.02, 0.05, 0.85],
+    label: "minimap",
+  })
+
+  cam = createCamera2d(main, { viewport: () => win, world: WORLD, maxZoom: MAX_ZOOM })
+  // The main view's gestures and any pad drive the camera through a map;
+  // the minimap binds nothing (its tap glides through listen below).
+  let pointer = createPointerFeed()
+  feedPointer(main, pointer)
+  let input = createInputMap(camera2dActions)
+  input.bind(camera2dBindings({ pointer, gamepad: gamepad() }))
+  input.drive(cam.axes)
+  main.listen({
+    onTap: e => {
+      if (e.sprite === null) select(null)
+    },
+  })
+  // A tap on the minimap, sprite or not, glides the main camera there:
+  // the view's dispatch undoes the MAP camera, so e.x/e.y are world pixels.
+  map.listen({ onTap: e => cam.glideTo(e.x, e.y) })
+
+  createEffect(
+    () => ({ size: windowSize(), scale: displayScale() }),
+    ({ size, scale }) => {
+      win.width = Math.max(1, size.width)
+      win.height = Math.max(1, size.height)
+      main.setSize(win.width, win.height)
+      let budget = win.width * win.height * scale * scale
+      main.setOversample(fitOversample(scale, win.width, win.height, budget))
+      map.setOversample(fitOversample(scale, MAP_WIDTH, MAP_HEIGHT, budget))
+    },
+  )
+
+  // The main view's rect on the minimap, as a signal written only when the
+  // camera moved this frame.
+  let [rect, setRect] = createSignal(outline)
+  let last = 0
+  onFrame(tick => {
+    let t = tick / 1000
+    let dt = Math.min(MAX_DT, Math.max(0, t - last))
+    last = t
+    let rx = WORLD.width / 2 + Math.sin(t * ROAM_RATE_X) * WORLD.width * ROAM_SPAN
+    let ry = WORLD.height / 2 + Math.sin(t * ROAM_RATE_Y) * WORLD.height * ROAM_SPAN
+    setSprite(roamer, { x: rx, y: ry, rotation: t })
+    cam.update(dt)
+    let view = cam.viewRect()
+    let [x0, y0] = map.project(view.x, view.y)
+    let [x1, y1] = map.project(view.x + view.width, view.y + view.height)
+    if (x0 !== outline.x || y0 !== outline.y || x1 - x0 !== outline.width || y1 - y0 !== outline.height) {
+      outline = { x: x0, y: y0, width: x1 - x0, height: y1 - y0 }
+      setRect(outline)
+    }
+  })
+
+  return (
+    <window>
+      <texture src={main.texture} position="absolute" left={0} top={0} width={windowSize().width} height={windowSize().height} {...main.handlers} />
+      <view pointerEvents="none" gap={6} padding={20}>
+        <text color="#eef4ff" fontSize={24} fontWeight={700}>
+          Views
+        </text>
+        <text color="#a9bcd6" fontSize={15}>
+          drag to pan, wheel or pinch to zoom - tap the minimap to glide there - tap a sprite in either view to select it
+        </text>
+      </view>
+      <view position="absolute" right={MAP_MARGIN} bottom={MAP_MARGIN} width={MAP_WIDTH} height={MAP_HEIGHT} overflow="clip">
+        <texture src={map.texture} width={MAP_WIDTH} height={MAP_HEIGHT} {...map.handlers} />
+        <rect
+          position="absolute"
+          left={rect().x}
+          top={rect().y}
+          width={rect().width}
+          height={rect().height}
+          drawStyle="stroke"
+          strokeWidth={1}
+          color="#ffffff"
+          pointerEvents="none"
+        />
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)
+
+registerDebug("state", () => ({ camera: cam.camera(), map: map.camera(), outline }))
+registerDebug("camera", (args?: Record<string, unknown>) => {
+  let pose: Record<string, number> = {}
+  for (let key of ["x", "y", "zoom"]) {
+    if (typeof args?.[key] === "number") pose[key] = args[key] as number
+  }
+  if (Object.keys(pose).length > 0) cam.set(pose)
+  return cam.camera()
+})
+registerDebug("selected", () => (selected && selected.layer !== null ? { x: selected._x, y: selected._y } : null))
+registerDebug("first", () => (first ? { x: first._x, y: first._y } : null))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/2d",
-  "version": "0.0.56",
+  "version": "0.0.58",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -16,6 +16,6 @@
   ],
   "peerDependencies": {
     "@solidjs/signals": "2.0.0-rc.6",
-    "@solidrt/core": "0.0.56"
+    "@solidrt/core": "0.0.58"
   }
 }

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

@@ -4,7 +4,7 @@
 // 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.tsx) and the pointer inverse
+// 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.
 
@@ -84,3 +84,28 @@ export function unprojectCamera(camera: CameraUpdate, screenX: number, screenY:
   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],
+  }
+}