@solidrt/2d 0.0.67 → 0.0.69

package/examples/views.tsx

@@ -49,7 +49,7 @@ 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" })
+  let layer = createSpriteLayer([atlas], { 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) => {
@@ -83,7 +83,7 @@ function App() {
     label: "minimap",
   })
 
-  cam = createCamera2d(main, { viewport: () => win, world: WORLD, maxZoom: MAX_ZOOM })
+  cam = createCamera2d(main, { 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()
@@ -98,7 +98,7 @@ function App() {
   })
   // 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) })
+  map.listen({ onTap: e => cam.glideTo({ x: e.x, y: e.y }) })
 
   createEffect(
     () => ({ size: windowSize(), scale: displayScale() }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/2d",
-  "version": "0.0.67",
+  "version": "0.0.69",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -15,10 +15,10 @@
     "AGENTS.md"
   ],
   "devDependencies": {
-    "@solidrt/test": "0.0.67"
+    "@solidrt/test": "0.0.69"
   },
   "peerDependencies": {
     "@solidjs/signals": "2.0.0-rc.13",
-    "@solidrt/core": "0.0.67"
+    "@solidrt/core": "0.0.69"
   }
 }

package/src/atlas.ts

@@ -1,31 +1,48 @@
 // 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
+// slicers measure in, and the checks a layer runs over the atlases it
+// declares. 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 { limits } from "@solidrt/core/gpu"
 import type { SamplerOptions, TextureId } from "@solidrt/core/gpu"
+import type { Frame } from "./frames.ts"
 
 /**
- * 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 }`.
+ * A texture with its pixel size: what `grid`, `namedFrames` and
+ * `fullFrame` slice (stamping the texture on every frame), and what a
+ * layer declares in its `atlases` list. 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. */
+  /** The atlas texture: what the frames cut from it name, and what a layer
+   * declaring this atlas binds. */
   texture: TextureId
   /** Pixel size, the space the slicers measure rects and gaps in. */
   width: number
   height: number
+  /**
+   * The sheet is a distance field, not colour: a multi-channel signed
+   * distance field in rgb (the edge is the median at 0.5) with the true
+   * field in alpha, `range` texels wide (what `flux:font`'s msdf atlas
+   * holds, see createSpriteFont). A layer declaring it decodes the field
+   * in its fragment stage - sharp edges at any zoom from one sheet, and
+   * the per-sprite outline - instead of sampling colour; the sprite's
+   * tint is the fill colour. Fixed at the layer's creation like the list
+   * itself: the fragment stage is generated per layer.
+   */
+  sdf?: { range: number }
 }
 
 /**
  * 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`.
+ * for atlases drawn far below their texel size - extrude the sheet first,
+ * see extrude.ts) and `anisotropy`.
  */
 export type AtlasOptions = SamplerOptions & {
   label?: string
@@ -39,9 +56,10 @@ export type AtlasOptions = SamplerOptions & {
  * 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 }`).
+ * `await file("assets/sheet.png").bytes()` - and pixels built in code
+ * (or repacked by `extrudeGrid`/`extrudeRects`) pass as they are. Freed
+ * with the owning reactive scope like any core texture (opt out with
+ * `{ autoFree: false }`).
  */
 export function createAtlas(image: DecodedImage, opts?: AtlasOptions): Atlas {
   let { data, width, height } = image
@@ -52,3 +70,48 @@ export function createAtlas(image: DecodedImage, opts?: AtlasOptions): Atlas {
   })
   return { texture, width, height }
 }
+
+/** Whether a value is an atlas record: a non-negative integer texture id
+ * and a positive pixel size. */
+export function isAtlas(a: unknown): a is Atlas {
+  let o = a as Atlas | null
+  return typeof o === "object" && o !== null && Number.isInteger(o.texture) && o.texture >= 0 && o.width > 0 && o.height > 0
+}
+
+/**
+ * Validate a layer's `atlases` list (throws - the dev validation policy):
+ * a non-empty array of distinct atlas records, no more than the device
+ * binds in one pass (`limits.maxTextureUnits`, 16 on every GLES 3.0
+ * device). Returns the texture -> sampler index map the layer resolves
+ * frames through; the index is the atlas's position in the list.
+ * Internal - every layer kind calls it.
+ */
+export function checkAtlases(verb: string, atlases: readonly Atlas[]): Map<TextureId, number> {
+  if (!Array.isArray(atlases) || atlases.length === 0) {
+    throw new Error(`${verb}: atlases must be a non-empty array of atlas records (createAtlas, or { texture, width, height })`)
+  }
+  if (atlases.length > limits.maxTextureUnits) {
+    throw new Error(`${verb}: ${atlases.length} atlases exceed the ${limits.maxTextureUnits} sampler inputs one pass may bind (limits.maxTextureUnits); pack sheets together`)
+  }
+  let index = new Map<TextureId, number>()
+  atlases.forEach((atlas, i) => {
+    if (!isAtlas(atlas)) throw new Error(`${verb}: atlases[${i}] is not an atlas record, got ${JSON.stringify(atlas)}`)
+    if (index.has(atlas.texture)) throw new Error(`${verb}: atlases[${i}] declares texture ${atlas.texture} a second time`)
+    index.set(atlas.texture, i)
+  })
+  return index
+}
+
+/**
+ * The sampler index of a frame's texture in a layer's atlas list, or a
+ * throw naming the list: a frame from a sheet the layer did not declare
+ * is the wrong-sheet bug, caught at the write instead of drawn from the
+ * wrong texture. Internal - the layers' frame writes go through it.
+ */
+export function frameIndex(verb: string, index: Map<TextureId, number>, frame: Frame): number {
+  let i = index.get(frame.texture)
+  if (i === undefined) {
+    throw new Error(`${verb}: the frame's texture ${frame.texture} is not one of the layer's atlases (${[...index.keys()].join(", ")}); frames come from grid/namedFrames/fullFrame over a declared atlas`)
+  }
+  return i
+}

package/src/camera2d.ts

@@ -53,7 +53,9 @@
 // Pose is plain mutable state; a nudge or a verb pushes it at once (the
 // next paint carries the new camera, no frame loop needed for a drag),
 // and update(dt) advances glides, follow, inertia, the lanes and the axis
-// rates from the app's own onFrame. `active()` is the reactive frame-loop
+// rates from the app's own onFrame (onBeforeRender when it follows
+// something the frame moves, so it sees the frame's final position).
+// `active()` is the reactive frame-loop
 // gate (a glide, fling, fit, follow, shake or damped bound in flight, or
 // a rate driving); a resting camera costs nothing. update() pushes the
 // pose to the layers only when it changed (one setCamera per driven
@@ -85,24 +87,22 @@ const PAN_RATE = 1
 const ZOOM_RATE = 1
 const ROLL_RATE = 0.5
 
-/** What a 2d camera drives: anything with the layers' `setCamera`. */
-export type Camera2dTarget = { setCamera(update: CameraUpdate): void }
+/** What a 2d camera drives: anything with the layers' `setCamera` and a
+ * `size()` (the viewport in layer pixels, read whenever the camera needs
+ * it - a resize re-clamps at the next update; zeros while unknown, and
+ * clamping and fitting wait for a real size). A view is one. */
+export type Camera2dTarget = { setCamera(update: CameraUpdate): void; size(): { width: number; height: number } }
 
-/** The control's parameters: what set() takes and pose() returns filled. */
-export type Camera2dPose = {
-  x?: number
-  y?: number
-  zoom?: number
-  rotation?: number
-}
+/** The control's parameters, filled: what pose() returns (the 3d
+ * controls' OrbitPoseState and FirstPersonPoseState). */
+export type Camera2dPoseState = { x: number; y: number; zoom: number; rotation: number }
+
+/** The parameters, each optional: what set() and glideTo() take. */
+export type Camera2dPose = Partial<Camera2dPoseState>
 
 export type Rect2d = { x: number; y: number; width: number; height: number }
 
 export type Camera2dOptions = Camera2dPose & {
-  /** Viewport size in layer pixels, read whenever the camera needs it (a
-   * resize re-clamps at the next update). Return zeros while unknown -
-   * clamping and fitting wait for a real size. */
-  viewport: () => { width: number; height: number }
   /** World bounds (origin 0,0) the view is kept inside: an axis whose view
    * is wider than the world centers. Absent = unbounded. `damping` eases
    * a MOTION (a follow, a glide, a fling) into the bounds instead of
@@ -118,7 +118,10 @@ export type Camera2dOptions = Camera2dPose & {
   maxZoom?: number
   /** Where in the viewport the camera's world point sits, as fractions of
    * its size; default the center. glideTo and follow land their point
-   * here and rotation turns about it. */
+   * here and rotation and zoom turn about it: the pivot is the 3d orbit
+   * control's target - the point the camera turns about - which that
+   * control holds at the view centre and re-seats in WORLD space
+   * (`setPivot`), where this one places it on screen. */
   pivot?: { x: number; y: number }
   /** How follow(x, y) chases its point (the framing stage): damping per
    * axis, the dead zone and hard limits as fractions of the viewport
@@ -151,9 +154,9 @@ export type Camera2d = {
    * call, every field set): the pose plus the lanes - the argument for
    * projectCamera/unprojectCamera. */
   camera(): CameraState
-  /** Pose snapshot - the control's own four values, the shape set() takes
-   * (the 3d controls' pose()); no lane in it. */
-  pose(): Required<Camera2dPose>
+  /** Pose snapshot - the control's own four values, filled, the shape
+   * set() and glideTo() take (the 3d controls' pose()); no lane in it. */
+  pose(): Camera2dPoseState
   /** Merge a pose in (clamps apply) and push it. A snap: an x/y/zoom
    * write drops a glide or fling in flight and ends the follow; a
    * rotation write leaves them running. */
@@ -172,11 +175,13 @@ export type Camera2d = {
   zoomAt(sx: number, sy: number, factor: number, opts?: { glide?: boolean }): void
   /** Turn the world about the pivot by radians (clockwise, y-down) and push. */
   rollBy(angle: number): void
-  /** Ease the pose to put world (x, y) at the pivot, at `zoom` (default
-   * the current, or a pending wheel or double-tap zoom's target) and
-   * `rotation` (default the current), landing exactly; a fling or a
-   * follow yields. */
-  glideTo(x: number, y: number, zoom?: number, rotation?: number): void
+  /** Ease to a pose (the fields given, the rest as they are: `x`/`y` put
+   * that world point at the pivot, `zoom` defaults to the current or a
+   * pending wheel or double-tap zoom's target, `rotation` to the current;
+   * clamps apply) inside update(dt), landing exactly; a new glideTo
+   * retargets, and a fling or a follow yields. The 3d controls'
+   * glideTo(pose). */
+  glideTo(pose: Camera2dPose): void
   /** Frame a world rect (default the whole world): centered in the view
    * at the zoom that fits it, clamped. A snap unless `glide`. Waits for
    * the viewport when its size is not known yet. */
@@ -201,8 +206,10 @@ export type Camera2d = {
   viewRect(): Rect2d
   /** Advance glides, follow, inertia, the lanes and the axis rates, then
    * push the camera to the layers if it changed. Call from onFrame with
-   * the frame's dt in seconds; returns whether the camera changed since
-   * the previous update (nudges and verbs included). */
+   * the frame's dt in seconds - or from onBeforeRender when the camera
+   * follows something the frame moves, so it reads that frame's final
+   * position; returns whether the camera changed since the previous
+   * update (nudges and verbs included). */
   update(dt: number): boolean
   /**
    * Reactive: whether update() still has work - a glide, fling or
@@ -265,8 +272,9 @@ function checkOptions(options: Camera2dOptions): void {
 /**
  * Create a 2d camera driving `target`'s camera, where `target` is a sprite
  * or record layer's view (or several: a view and its overlay layer's
- * share one camera), or anything else with the layers' `setCamera`, such
- * as a signal setter feeding `<TileLayer camera>`. The initial pose
+ * share one camera, the FIRST one's `size()` the viewport), or anything
+ * else with the layers' `setCamera` and a `size()`, such as a signal
+ * setter feeding `<TileLayer camera>` beside its size. The initial pose
  * applies immediately: the world fitted when `world` is given and no
  * `zoom`. The pose options are initial values; every other option is read
  * where it applies, so a caller holding the options object (or a props
@@ -277,7 +285,11 @@ function checkOptions(options: Camera2dOptions): void {
  */
 export function createCamera2d(target: Camera2dTarget | Camera2dTarget[], options: Camera2dOptions): Camera2d {
   let targets = Array.isArray(target) ? target : [target]
-  if (typeof options.viewport !== "function") throw new Error("createCamera2d: viewport must be a function returning { width, height }")
+  for (let t of targets) {
+    if (!t || typeof t.setCamera !== "function" || typeof t.size !== "function") throw new Error("createCamera2d: every target needs setCamera() and size() (a view)")
+  }
+  let first = targets[0]
+  if (first === undefined) throw new Error("createCamera2d: at least one target")
   checkOptions(options)
   checkPose("", options)
   // Everything below the pose is read from `options` where it applies
@@ -301,15 +313,15 @@ export function createCamera2d(target: Camera2dTarget | Camera2dTarget[], option
   let zoom = options.zoom ?? 1
   let rotation = options.rotation ?? 0
 
-  // The viewport as last read; zeros mean unknown (nothing clamps or fits
-  // until a real size arrives).
+  // The viewport (the first target's size) as last read; zeros mean
+  // unknown (nothing clamps or fits until a real size arrives).
   let vw = 0
   let vh = 0
   let known = () => vw > 0 && vh > 0
   let readViewport = () => {
-    let v = options.viewport()
+    let v = first.size()
     if (!(Number.isFinite(v.width) && Number.isFinite(v.height) && v.width >= 0 && v.height >= 0)) {
-      throw new Error(`createCamera2d: viewport() must return non-negative finite width/height, got ${v.width}x${v.height}`)
+      throw new Error(`createCamera2d: the target's size() must return non-negative finite width/height, got ${v.width}x${v.height}`)
     }
     vw = v.width
     vh = v.height
@@ -651,8 +663,9 @@ export function createCamera2d(target: Camera2dTarget | Camera2dTarget[], option
       rollBy(angle)
       flush()
     },
-    glideTo(tx, ty, tz, tr) {
-      glideTo(tx, ty, tz, tr)
+    glideTo(pose) {
+      checkPose("glideTo", pose)
+      glideTo(pose.x ?? x, pose.y ?? y, pose.zoom, pose.rotation)
       notify()
     },
     fit(rect, opts) {

package/src/collision.ts

@@ -0,0 +1,20 @@
+// The kinematic character move, Godot's CharacterBody2D.move_and_slide
+// and Unity's Rigidbody2D mover as one pure function: no sprite, no
+// velocity state. It takes a volume where the body IS and the motion it
+// WANTS, and returns the motion it gets plus what it touched; a
+// sprite-driven body applies the result with setSprite. The loop itself
+// (depenetration, sweep, slide, floor snap) runs in the spatial core as
+// layer.moveAndSlide; this is its free-function spelling, the same as
+// @solidrt/3d's moveAndSlide(scene, ...).
+
+import type { MoveOptions, MoveResult, SpriteLayer, Volume } from "./layer.ts"
+
+/** What moveAndSlide needs of a layer. */
+export type MoveLayer = Pick<SpriteLayer, "moveAndSlide">
+
+/** Move a body by (dx, dy) through the layer's sprites, sliding along
+ * what it hits: layer.moveAndSlide as a function (see it for the
+ * contract). */
+export function moveAndSlide(layer: MoveLayer, volume: Volume, dx: number, dy: number, opts: MoveOptions = {}): MoveResult {
+  return layer.moveAndSlide(volume, dx, dy, opts)
+}

package/src/components/camera2d.tsx

@@ -4,10 +4,7 @@ import { createCamera2d } from "../camera2d.ts"
 import type { Camera2d as Camera2dHandle, Camera2dAxes, Camera2dOptions } from "../camera2d.ts"
 import { useSpriteLayer } from "./context.ts"
 
-export type Camera2dProps = Omit<Camera2dOptions, "viewport"> & {
-  /** Viewport in layer pixels; defaults to the driven view's own size
-   * (live: a fill layer's box, a setSize, a `<View2d>` resize). */
-  viewport?: () => { width: number; height: number }
+export type Camera2dProps = Camera2dOptions & {
   /** The input map driving the control (InputMap.drive): its `pan`,
    * `zoom` and `roll` actions, or the ones `actions` names. Live: a new
    * map reconnects. Without one the control moves only through `ref`. */
@@ -35,21 +32,17 @@ const MAX_CAMERA_DT = 0.1
  * getter and read where it applies, so a world, a zoom range, a pivot,
  * 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.
+ * the `<OrbitCamera>` rule. The view's `size()` is the viewport (live: a
+ * fill layer's box, a setSize, a `<View2d>` resize). Frames run only
+ * while the camera moves (`active()`), so a resting camera leaves the
+ * app demand-driven idle.
  */
 export let Camera2d: VoidComponent<Camera2dProps> = props => {
   let target = useSpriteLayer().viewport
   // Through merge, not a spread: a props object hands out getters, and
   // merge keeps them, so the control reads each option live where it
   // applies.
-  let options: Camera2dOptions = merge(props, {
-    get viewport() {
-      return props.viewport ?? (() => ({ width: target.width, height: target.height }))
-    },
-  })
+  let options: Camera2dOptions = merge(props, {})
   let cam = untrack(() => createCamera2d(target, options))
   createEffect(
     () => props.input,

package/src/components/group.tsx

@@ -1,11 +1,14 @@
 import { createEffect, onCleanup, untrack, useContext } from "@solidrt/core"
 import type { ParentComponent } from "@solidrt/core"
 import { addGroup, destroyGroup, setGroup, setGroupTransition } from "../layer.ts"
-import type { SpriteGroup, SpritePointerEvent, SpriteTapEvent, SpriteWheelEvent, TransitionEndEvent } from "../layer.ts"
+import type { SpriteGroup, TransitionEndEvent } from "../layer.ts"
 import type { SpriteTransition } from "../layer.ts"
 import { GroupContext, LayerContext } from "./context.ts"
+import type { BubblingSpritePointerProps } from "./sprite.tsx"
 
-export type GroupProps = {
+/** A group's props: the pose, the bubbling pointer events (from a hit
+ * child sprite; a group never receives enter/leave) and the transition. */
+export type GroupProps = BubblingSpritePointerProps & {
   /** Position in the parent frame (layer pixels at the root). */
   x?: number
   y?: number
@@ -16,14 +19,6 @@ export type GroupProps = {
   /** Show or hide the whole subtree (default true); see
    * GroupOptions.visible. */
   visible?: boolean
-  /** Bubbled from a hit child sprite (see SpritePointerProps); a group
-   * never receives enter/leave. */
-  onPointerDown?: (event: SpritePointerEvent) => void
-  onPointerMove?: (event: SpritePointerEvent) => void
-  onPointerUp?: (event: SpritePointerEvent) => void
-  onPointerCancel?: (event: SpritePointerEvent) => void
-  onWheel?: (event: SpriteWheelEvent) => void
-  onTap?: (event: SpriteTapEvent) => void
   /** How pose-prop changes animate (see setGroupTransition). The mount
    * pose snaps, unless a component's `from` animates it in from there. */
   transition?: SpriteTransition | string | null

package/src/components/index.ts

@@ -19,7 +19,9 @@ export type { LayerPointerProps, SpriteLayerProps } from "./sprite-layer.tsx"
 export { Group } from "./group.tsx"
 export type { GroupProps } from "./group.tsx"
 export { Sprite } from "./sprite.tsx"
-export type { SpritePointerProps, SpriteProps } from "./sprite.tsx"
+export { Text2d } from "./text2d.tsx"
+export type { Text2dProps } from "./text2d.tsx"
+export type { BubblingSpritePointerProps, SpritePointerProps, SpriteProps } from "./sprite.tsx"
 export { Camera2d } from "./camera2d.tsx"
 export type { Camera2dProps } from "./camera2d.tsx"
 export { Shot, Shots } from "./shots.tsx"

package/src/components/sprite-layer.tsx

@@ -1,5 +1,7 @@
 import { createEffect, displayScale, getBoundingBoxViewport, getLayoutBox, onCleanup, onLayout, untrack } from "@solidrt/core"
 import type { Element, ParentComponent, PointerFeed, TextureId } from "@solidrt/core"
+import type { BlendMode } from "@solidrt/core/gpu"
+import type { Atlas } from "../atlas.ts"
 import { createSpriteLayer } from "../layer.ts"
 import { feedPointer } from "../views.ts"
 import type { LayerPointerEvent, LayerTapEvent, LayerWheelEvent, SpriteLayer as LayerHandle } from "../layer.ts"
@@ -39,10 +41,27 @@ export type SpriteLayerProps = LayerPointerProps & {
    */
   width?: number
   height?: number
-  /** The atlas texture every sprite samples (create with createAtlas). */
-  atlas: TextureId
+  /** The atlases the sprites draw from (createAtlas records), bound as
+   * one draw; every `<Sprite frame>` comes from one of them. Fixed at
+   * mount. Give these (a layer of the component's own, disposed with it)
+   * or `layer`, not both. */
+  atlases?: Atlas[]
+  /**
+   * An existing layer (createSpriteLayer) to adopt instead of making one:
+   * the component shows and populates it - the view and the leaf are
+   * still its own, `<Sprite>`, `<Group>` and `<Text2d>` children mount
+   * into it - and leaves its lifetime to its maker, so the component
+   * face sits over an imperative layer. The creation props (atlases,
+   * capacity, blend, orderBy) describe a layer the component makes, so
+   * with `layer` they have nothing to apply to and throw.
+   */
+  layer?: LayerHandle
   /** Initial record reservation (grows on demand); default 1024. */
   capacity?: number
+  /** How the sprites blend into the layer's views (see
+   * SpriteLayerOptions.blend); default "alpha", "add" for glows and
+   * additive particles. Fixed at mount. */
+  blend?: BlendMode
   /** The own view's clear color. */
   clearColor?: [number, number, number, number]
   /** Pan/zoom/rotate the own view over the world (in-shader); a
@@ -129,6 +148,10 @@ export type SpriteLayerProps = LayerPointerProps & {
 // before the first paint, so it only has to be a valid target size.
 const FILL_INITIAL_SIZE = 1
 
+// The props that describe a layer the component creates - meaningless,
+// hence rejected, on an adopted one (`layer`), which was created already.
+const CREATION_PROPS = ["atlases", "capacity", "blend", "orderBy"] as const
+
 // The props that configure the layer's own view - meaningless, hence
 // rejected, on a layer without one (output={false}).
 const VIEW_PROPS = [
@@ -150,25 +173,35 @@ const VIEW_PROPS = [
 ] as const
 
 /**
- * Owns a sprite layer and, unless `output={false}`, its own view,
- * composited as an ordinary `<texture>` leaf so the output takes layout,
- * transforms, blendMode, and pointer events like any element - or hand
- * `output` the texture id and compose it yourself. A layout component:
- * it cannot sit inside a d-* subtree; `output` with a `<d-texture>` is
- * the detached form. Children (`<Sprite>`) render nothing themselves -
- * they populate the retained layer through context; `<View2d>` children
- * are further views of the same sprites.
+ * Owns a sprite layer (over `atlases`; or adopts an existing one through
+ * `layer`, owning only what follows) and, unless `output={false}`, its
+ * own view, composited as an ordinary `<texture>` leaf so the output
+ * takes layout, transforms, blendMode, and pointer events like any
+ * element - or hand `output` the texture id and compose it yourself. A
+ * layout component: it cannot sit inside a d-* subtree; `output` with a
+ * `<d-texture>` is the detached form. Children (`<Sprite>`) render
+ * nothing themselves - they populate the retained layer through context;
+ * `<View2d>` children are further views of the same sprites.
  */
 export let SpriteLayer: ParentComponent<SpriteLayerProps> = props => {
-  let layer = untrack(() =>
-    createSpriteLayer(props.atlas, {
+  let layer = untrack(() => {
+    let adopted = props.layer
+    if (adopted) {
+      for (let name of CREATION_PROPS) {
+        if (props[name] !== undefined) throw new Error(`SpriteLayer: layer adopts an existing layer - ${name} was fixed when it was created`)
+      }
+      return adopted
+    }
+    if (props.atlases === undefined) throw new Error("SpriteLayer: give atlases (a layer of its own) or layer (an existing one)")
+    return createSpriteLayer(props.atlases, {
       capacity: props.capacity,
+      blend: props.blend,
       tint: props.tint,
       orderBy: props.orderBy,
       stagger: props.stagger,
       label: props.label,
-    }),
-  )
+    })
+  })
   createEffect(
     () => props.tint,
     tint => {

package/src/components/sprite.tsx

@@ -14,14 +14,22 @@ import { GroupContext, LayerContext } from "./context.ts"
  * carries layer.handlers - the built-in `<SpriteLayer>` leaf does (opt
  * out with events={false}); an `output` leaf spreads them itself.
  */
-export type SpritePointerProps = {
+export type SpritePointerProps = BubblingSpritePointerProps & {
+  /** Sprites only: a Group never receives enter/leave. */
+  onPointerEnter?: (event: SpritePointerEvent) => void
+  onPointerLeave?: (event: SpritePointerEvent) => void
+}
+
+/** The pointer props a `<Group>` takes as well: the events that bubble
+ * from the hit sprite up through the Groups above it, without the hover
+ * pair (@solidrt/3d's BubblingNodePointerProps). */
+export type BubblingSpritePointerProps = {
   onPointerDown?: (event: SpritePointerEvent) => void
   onPointerMove?: (event: SpritePointerEvent) => void
   onPointerUp?: (event: SpritePointerEvent) => void
+  /** The pointer's other end: the system took it away (see core's
+   * onPointerCancel); bubbles like up, and the press it ends never taps. */
   onPointerCancel?: (event: SpritePointerEvent) => void
-  /** Sprites only: a Group never receives enter/leave. */
-  onPointerEnter?: (event: SpritePointerEvent) => void
-  onPointerLeave?: (event: SpritePointerEvent) => void
   onWheel?: (event: SpriteWheelEvent) => void
   /** A press released on the sprite without dragging; `tapCount` counts
    * repeats (2 = double tap). */
@@ -45,9 +53,9 @@ export let Sprite: VoidComponent<SpriteProps> = props => {
   let parent = useContext(GroupContext)
   let sprite = untrack(() => addSprite(layer, { parent }))
   createEffect(
-    () => [props.x, props.y, props.w, props.h, props.frame, props.flipX, props.flipY, props.rotation, props.tint, props.renderOrder, props.visible] as const,
-    ([x, y, w, h, frame, flipX, flipY, rotation, tint, renderOrder, visible]) =>
-      setSprite(sprite, { x, y, w, h, frame, flipX, flipY, rotation, tint, renderOrder, visible: visible !== false }),
+    () => [props.x, props.y, props.w, props.h, props.frame, props.flipX, props.flipY, props.rotation, props.tint, props.minScreenPx, props.maxScreenPx, props.renderOrder, props.visible] as const,
+    ([x, y, w, h, frame, flipX, flipY, rotation, tint, minScreenPx, maxScreenPx, renderOrder, visible]) =>
+      setSprite(sprite, { x, y, w, h, frame, flipX, flipY, rotation, tint, minScreenPx, maxScreenPx, renderOrder, visible: visible !== false }),
   )
   // After the pose effect, so the mount pose snaps before writes animate.
   createEffect(