@solidrt/2d 0.0.56 → 0.0.57

package/src/layer.ts

@@ -2,12 +2,13 @@
 // SPATIAL ARENA node (arena slot: local pose, parent, world matrix, index
 // leaf, record sink - no layout, no paint, no rendertree element) whose
 // Pose2D record sink writes [x, y, angle, sx, sy] into the sprite's slot of
-// the pose instance buffer at the core's flush. Rendering stays one
-// instanced draw into one pipeline target, composited as a single
-// `<texture>` leaf; what changed is who owns the pose upstream of the
-// instance buffer - the arena, so every core producer (native transitions,
-// animation clips, physics) reaches sprites through `sprite.node`, and
-// picking walks the core BVH instead of a JS loop.
+// the pose instance buffer at the core's flush. Rendering is one
+// instanced draw per VIEW (views.ts: the layer shows through its views
+// only, each a target with a camera of its own); what changed is who owns
+// the pose upstream of the instance buffer - the arena, so every core
+// producer (native transitions, animation clips, physics) reaches sprites
+// through `sprite.node`, and picking walks the core BVH instead of a JS
+// loop.
 //
 // Two instance-buffer slots split ownership: slot 0 is the pose buffer,
 // written ONLY by the core (one coalesced write per flush however many
@@ -20,35 +21,24 @@
 // Sprites hold FIXED instance slots (freed slots recycle): draw order is
 // slot order, so removal never shifts records and pose sinks never rebind.
 // Layer space is pixels, top-left origin, y-down - the render tree's
-// frame. The camera (offset, zoom, rotation about a pivot - CameraUpdate
-// in camera.ts) is a shared-params write (uCamera + uCameraRot), never
-// per-sprite; pointer dispatch (dispatch.ts) undoes it with
-// unprojectCamera.
+// frame. A view's camera (offset, zoom, rotation about a pivot -
+// CameraUpdate in camera.ts) is a shared-params write (uCamera +
+// uCameraRot) on that view's target, never per-sprite; pointer dispatch
+// (dispatch.ts) undoes it with unprojectCamera.
 import { getOwner, onCleanup } from "@solidrt/core"
 import type { PointerEvent as ElementPointerEvent, WheelEvent as ElementWheelEvent } from "@solidrt/core"
-import {
-  beginBufferWrite,
-  createBuffer,
-  createPipelineTexture,
-  destroyBuffer,
-  destroyTexture,
-  endBufferWrite,
-  setDraw,
-  setTargetParams,
-  setTargetSize,
-} from "@solidrt/core/gpu"
+import { beginBufferWrite, createBuffer, destroyBuffer, endBufferWrite } from "@solidrt/core/gpu"
 import type { BufferId, TextureId } from "@solidrt/core/gpu"
 import * as spatial from "flux:spatial"
-import type { NodeId, NodeTransition } from "flux:spatial"
+import type { Impact as CoreImpact, MoveOptions as CoreMoveOptions, NodeId, NodeTransition, QueryFilter } from "flux:spatial"
 import { on } from "srt:events"
-import { checkCamera, projectCamera, unprojectCamera } from "./camera.ts"
 import type { CameraState, CameraUpdate } from "./camera.ts"
-import { spriteDispatch } from "./dispatch.ts"
-import { checkOversample, thrashSentinel } from "./oversample.ts"
 import type { Frame } from "./frames.ts"
 import { FULL_FRAME, writeFrame } from "./frames.ts"
 import type { RecordLayer } from "./records.ts"
-import { FRAGMENT, INSTANCE_ATTRIBUTES_SPLIT, VERTEX_SPLIT } from "./shaders.ts"
+import { createSpritePipeline, INSTANCE_ATTRIBUTES_SPLIT, VERTEX_SPLIT } from "./shaders.ts"
+import { createViews } from "./views.ts"
+import type { ViewHandle, ViewOptions } from "./views.ts"
 
 /** Floats per pose record (the core's Pose2D projection). */
 export const POSE_FLOATS = 5
@@ -67,10 +57,31 @@ const RESOLVED = Promise.resolve()
 
 // Shared marshalling scratch (the bindings copy synchronously).
 const TRANSFORM = new Float32Array(10)
-const FLAT_BOUNDS = new Float32Array([-0.5, -0.5, 0, 0.5, 0.5, 0])
+// Half depth of a sprite's index box along z, node units (a sprite's z
+// scale is 1, so world units too). A sprite is a COLUMN in the index, not
+// a flat quad: a volume query at z = 0 then only ever meets its side
+// faces, so every contact normal and depth is in the plane, and a circle
+// whose center lies over a sprite pushes out sideways instead of along z
+// (the core's contact against a flat triangle is the plane normal). Far
+// larger than any volume's reach, so the end faces never take part.
+const SPRITE_DEPTH = 1e4
+const COLUMN_BOUNDS = new Float32Array([-0.5, -0.5, -SPRITE_DEPTH, 0.5, 0.5, SPRITE_DEPTH])
 const RAY_ORIGIN = new Float32Array(3)
-const RAY_DIR = new Float32Array([0, 0, 1])
-const BOX = new Float32Array([0, 0, 0, 0, 0, 1, 0, 0, 0, 1])
+const RAY_DIR = new Float32Array(3)
+// Volume scratch: a "capsule" is a, b, radius (7 floats), a "box" is
+// center, half extents, quaternion (10); both packed at z = 0.
+const CAPSULE = new Float32Array(7)
+const BOX = new Float32Array(10)
+const MOTION = new Float32Array(3)
+// A box volume's half depth: any positive value inside the columns.
+const BOX_HALF_DEPTH = 1
+// The pick ray starts this far in front of the plane; it crosses every
+// column at z = 0 whatever the start, but a start inside the column meets
+// only its far end face, which is fine for pick (draw order sorts, not
+// distance).
+const PICK_RAY_START = -1
+// The direction floors face in a y-down world.
+const UP_2D: [number, number] = [0, -1]
 // worldPosition's world-matrix scratch (column-major; translation at 12, 13).
 const WORLD = new Float32Array(16)
 
@@ -207,6 +218,12 @@ export type SpriteOptions = {
   visible?: boolean
 }
 
+/**
+ * addSprite's bag: the sprite fields plus the mount point. The pool idiom
+ * for a game: reserve `capacity`, add every sprite at mount with `visible:
+ * false`, then show/hide - a hidden sprite keeps its slot, so draw order
+ * stays stable and a spawn is one setSprite, never an add.
+ */
 export type AddSpriteOptions = SpriteOptions & {
   /** Mount under this group (node layer only; null = the layer root, the
    * default); pose fields are then local to it. Reparent later with
@@ -254,13 +271,13 @@ export type SpritePointerEvent = LayerEventBase & {
 }
 
 /**
- * The event as the LAYER's listeners see it (LayerBase.listen), the last
+ * The event as the VIEW's listeners see it (ViewHandle.listen), the last
  * stop of the walk: `sprite` is the hit sprite it bubbled from, or null
- * over empty space, where the layer is the only target.
+ * over empty space, where the view is the only target.
  */
 export type LayerPointerEvent = LayerEventBase & {
   sprite: Sprite | null
-  currentTarget: SpriteLayer | RecordLayer
+  currentTarget: ViewHandle
 }
 
 type WheelFields = {
@@ -287,7 +304,7 @@ export type LayerWheelEvent = LayerPointerEvent & WheelFields
 export type SpriteTapEvent = SpritePointerEvent & TapFields
 export type LayerTapEvent = LayerPointerEvent & TapFields
 
-/** A listener at the layer root; see LayerBase.listen. */
+/** A listener at a view's root; see ViewHandle.listen. */
 export type LayerPointerListener = {
   onPointerDown?: (event: LayerPointerEvent) => void
   onPointerMove?: (event: LayerPointerEvent) => void
@@ -319,20 +336,13 @@ export type SpriteLayerOptions = {
    * limit.
    */
   capacity?: number
-  clearColor?: [number, number, number, number]
   /** Layer tint, [r, g, b, a] in 0..1, multiplied over every sprite's own
-   * tint; default opaque white (sprites as-is). See setTint. */
+   * tint in every view; default opaque white (sprites as-is). See
+   * setTint. */
   tint?: [number, number, number, number]
+  /** Names the GPU resources (buffers, pipeline; views default to
+   * `<label>-view`); default "sprites". */
   label?: string
-  /**
-   * Target texels per layer pixel (positive integer, default 1). The layer
-   * renders at `oversample` times its size and is composited down, so a
-   * fractional or HiDPI display scale resamples properly instead of snapping
-   * (nearest) or smearing (linear); see setOversample. The components pick
-   * it from the leaf's on-screen size - set it here when composing the
-   * output yourself.
-   */
-  oversample?: number
   /** Skip the owner-scoped auto-dispose (see createSpriteLayer). */
   autoFree?: boolean
   /**
@@ -423,57 +433,23 @@ export type GroupOptions = {
 }
 
 /** What both layer kinds share; the free sprite functions dispatch on it. */
+/**
+ * What both layer kinds share: the sprites and what applies to all of
+ * them. A layer has no output of its own - it shows through its views
+ * (createView), each a target with a camera, a size and pointer dispatch
+ * of its own (ViewHandle), as a Unity scene shows only through Cameras
+ * and a Godot World2D only through Viewports.
+ */
 export type LayerBase = {
-  /** The layer's output: an ordinary texture id (`<texture src>`). */
-  texture: TextureId
-  /** Element handlers wiring the layer's pointer events (sprites, groups
-   * and the root listeners); see handlersFor. */
-  handlers: SpriteHandlers
   /** Live sprite count. */
   readonly count: number
-  /** Layer pixels, as created or last set by setSize. */
-  readonly width: number
-  readonly height: number
-  setSize(width: number, height: number): void
-  /**
-   * Listen at the root of the event walk. Every down, move, up, wheel and
-   * tap arrives here after the hit sprite and its enclosing groups
-   * (`sprite` set) or as the walk's only stop over empty space (`sprite`
-   * null), unless a handler stopped it on the way. Listeners run in
-   * registration order and all of them run - the root is the last stop,
-   * there is nothing left to claim. Returns the remover. The app's own
-   * root handling (deselect on a miss, a marquee) and controls
-   * (createCamera2d's attach) meet here, which is why the root is a list
-   * where a sprite has plain fields.
-   */
-  listen(listener: LayerPointerListener): () => void
-  /** Target texels per layer pixel; see setOversample. */
-  readonly oversample: number
-  /**
-   * Re-render at `n` target texels per layer pixel (positive integer): the
-   * target resizes in place at its stable id, layer pixels, records, camera
-   * and picking are untouched. Pick `n` as the ceiling of the device pixels
-   * one layer pixel covers on screen (display scale times any designSize
-   * fit or layout scaling), which the components do in onLayout.
-   */
-  setOversample(n: number): void
-  setCamera(update: CameraUpdate): void
-  /** The camera as last set (a fresh object per call, every field
-   * present): the argument for projectCamera/unprojectCamera -
-   * @solidrt/3d's scene.camera(). */
-  camera(): CameraState
-  /** World (layer) pixels -> viewport pixels under the current camera:
-   * projectCamera over camera(). */
-  project(x: number, y: number): [number, number]
-  /** Viewport pixels -> world (layer) pixels, the inverse: what pointer
-   * dispatch applies to every event. */
-  unproject(x: number, y: number): [number, number]
   /**
    * Tint the whole layer, [r, g, b, a] in 0..1: a uniform multiplied over
    * every sprite's own tint (day/night, a dimmed parallax plane, a
-   * fade-in). One shared-params write - no record touches, cheap to
-   * animate - and the same contract as TileLayer.setTint, so one signal
-   * drives a whole scene across layer kinds.
+   * fade-in) in every view. One shared-params write per view - no record
+   * touches, cheap to animate - and the same contract as
+   * TileLayer.setTint, so one signal drives a whole scene across layer
+   * kinds.
    */
   setTint(tint: [number, number, number, number]): void
   /** Every shown sprite whose rotated rect contains the layer-pixel point
@@ -481,15 +457,21 @@ export type LayerBase = {
    * all-hits shape of @solidrt/3d's pick; `pick(x, y)[0]` is the topmost.
    * Topmost means draw order (highest slot on the node layer, last added
    * on a record layer); an `orderBy` key is not consulted (see
-   * SpriteLayerOptions.orderBy's known limitation). */
+   * SpriteLayerOptions.orderBy's known limitation). World space: a view
+   * undoes its camera before asking. */
   pick(x: number, y: number): Sprite[]
   /**
-   * handlers for a leaf whose LAYOUT size differs from the layer size
-   * (events scale by layer/layout; a leaf laid out AT layer size just uses
-   * `handlers`). `layout` is read per event, so a resize-reactive layout
-   * just works - @solidrt/3d's handlersFor, one dimension down.
+   * A rendering of the layer's world from a camera of its own - the main
+   * view, a minimap, a zoomed inset, one split-screen pane -
+   * @solidrt/3d's scene.createView one dimension down. One more target
+   * drawing the SAME instance buffers (no sprite is mirrored, no per-frame
+   * JS beyond the view's camera writes), key order included; the layer's
+   * tint fans out to it. The view carries the viewport contract (texture,
+   * setSize, setOversample, setCamera, listen and handlers with sprite
+   * events walking to the view as root); sprites stay the layer's. Views
+   * die with the layer.
    */
-  handlersFor(layout: () => { width: number; height: number }): SpriteHandlers
+  createView(opts: ViewOptions): ViewHandle
   dispose(): void
   _add(opts?: AddSpriteOptions): Sprite
   _write(sprite: SpriteState, opts: SpriteOptions): void
@@ -498,14 +480,129 @@ export type LayerBase = {
   _schedule(): void
 }
 
+/** A query volume for overlap/sweep/moveAndSlide, in layer pixels: a
+ * circle, a capsule (the radius swept along the segment a-b: a character)
+ * or a rect (`rotation` radians about its center, 0 when absent) - Godot's
+ * CircleShape2D/CapsuleShape2D/RectangleShape2D, @solidrt/3d's Volume one
+ * dimension down. */
+export type Circle = { x: number; y: number; radius: number }
+export type Capsule = { ax: number; ay: number; bx: number; by: number; radius: number }
+export type Rect = { x: number; y: number; width: number; height: number; rotation?: number }
+export type Volume = Circle | Capsule | Rect
+
+/** Filters for one raycast/overlap/sweep/moveAndSlide query. */
+export type QueryOptions = {
+  /** Only these sprites report hits (an include-list); every shown sprite
+   * of the layer otherwise. */
+  sprites?: Sprite[]
+}
+
+/** One sprite a raycast() ray strikes: the distance along the ray, the
+ * point on the sprite's edge and the unit edge normal facing the ray. */
+export type RayHit = { sprite: Sprite; distance: number; point: [number, number]; normal: [number, number] }
+
+/** One sprite an overlap() volume touches: its deepest contact - the
+ * point on the sprite's edge, the unit direction out of the sprite, and
+ * the depth along that direction that clears the contact. */
+export type Overlap = { sprite: Sprite; point: [number, number]; normal: [number, number]; depth: number }
+
+/** One sprite a sweep() volume touches on its way: `time` is the fraction
+ * of the motion at first touch (0 for a volume already in contact and
+ * moving in), `point` the touch point on the sprite's edge, `normal` the
+ * unit normal there facing the volume. */
+export type Impact = { sprite: Sprite; time: number; point: [number, number]; normal: [number, number] }
+
+export type MoveOptions = QueryOptions & {
+  /** The direction floors face (default [0, -1]: y-down, floors face up
+   * the screen). */
+  up?: [number, number]
+  /** Largest angle (radians) between a contact normal and `up` that still
+   * counts as floor (default 45 degrees). Steeper contacts are walls, and
+   * the body slides down them. */
+  floorMaxAngle?: number
+  /** Most contacts one call slides along (default 6). */
+  maxSlides?: number
+  /** Gap kept from every surface, layer pixels (default 0.01). */
+  skin?: number
+  /** How far below the body a floor is pulled to when the motion does not
+   * rise (default 0.1; 0 disables): what keeps a walker on a ramp going
+   * down, and what decides `floor` at the end of the move - a body that
+   * ends higher than this above its floor is airborne, whatever it
+   * touched on the way. A rising motion (a jump) never snaps. */
+  floorSnap?: number
+}
+
+export type MoveResult = {
+  /** The displacement the body gets: add it to the body's position. */
+  motion: [number, number]
+  /** The unit normal of the floor the body ends the move on - within
+   * `floorSnap` below it, snapped onto - else null (airborne, or on a
+   * slope too steep to stand on). With `floorSnap: 0` it is a floor met
+   * during the move instead. */
+  floor: [number, number] | null
+  /** Whether a wall (a contact steeper than a floor and flatter than a
+   * ceiling) or a ceiling was met. */
+  wall: boolean
+  ceiling: boolean
+  /** Every contact met, in order, the floor snap's last. */
+  hits: Impact[]
+}
+
 export type SpriteLayer = LayerBase & {
   /**
    * Every shown sprite whose rotated rect overlaps the layer-pixel rect
    * (the core BVH overlap query, exact for rotated sprites), unordered -
-   * the marquee query. Node layer only.
+   * the marquee query: `overlap` over an unrotated rect, sprites only.
+   * Node layer only.
    */
   pickRect(x: number, y: number, width: number, height: number): Sprite[]
+  /**
+   * Every shown sprite the ray from (x, y) along (dx, dy) strikes, nearest
+   * first, with the distance (layer pixels along the normalized
+   * direction), the point on the sprite's edge and the edge normal.
+   * `pick` is the point form; this is the shot and the line of sight.
+   * Reads the index as of the last flush, the pending batch run first,
+   * like pick.
+   */
+  raycast(x: number, y: number, dx: number, dy: number, opts?: QueryOptions): RayHit[]
+  /**
+   * Every shown sprite the volume touches, each with its deepest contact
+   * (Godot's intersect_shape, Unity's OverlapCircle/Box/Capsule: a blast
+   * radius, a pickup range, a melee arc), unordered. Sprites are tested
+   * as their rotated rects, so any rotation holds; a volume wholly inside
+   * a sprite touches it (a sprite is a solid rect to a volume, its
+   * push-out the nearest edge's). Same index contract as raycast.
+   */
+  overlap(volume: Volume, opts?: QueryOptions): Overlap[]
+  /**
+   * The volume moved by (dx, dy): every shown sprite it touches on the
+   * way, at its first touch, earliest first (Godot's cast_motion, Unity's
+   * CircleCast/BoxCast: a bullet, a dash). A volume already in contact
+   * reports time 0 while the motion closes in, and nothing while it leaves
+   * or slides along the contact, which is what lets a slide along a wall
+   * proceed. A zero motion touches nothing.
+   */
+  sweep(volume: Volume, dx: number, dy: number, opts?: QueryOptions): Impact[]
+  /**
+   * Move a body by (dx, dy) through the layer's sprites, sliding along
+   * what it hits (Godot's CharacterBody2D.move_and_slide, the platformer
+   * and top-down character mover), as one pure call: 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. The
+   * body first pushes out of anything it starts inside, then sweeps and
+   * slides up to `maxSlides` times, then, unless the motion rises, snaps
+   * down onto a floor within `floorSnap` - the floor it reports is the
+   * one it ends on. The loop runs in the spatial core: one call per body
+   * per frame. Gravity is the caller's: fold the fall into the motion
+   * each frame and zero it while `floor` is set; a walkable floor absorbs
+   * the vertical part, so a body never creeps down a slope it can stand
+   * on. Colliders are the layer's shown sprites, or `opts.sprites`.
+   */
+  moveAndSlide(volume: Volume, dx: number, dy: number, opts?: MoveOptions): MoveResult
   _groups: Set<GroupState>
+  /** The core node every sprite and group of the layer sits under: what
+   * scopes the layer's queries in the arena shared with 3d scenes. */
+  _root: NodeId
 }
 
 /** The stored UVs at `at` un-mirrored by the sprite's flags: the frame as
@@ -533,6 +630,48 @@ function fillTransform(x: number, y: number, rot: number, sx: number, sy: number
   TRANSFORM[9] = 1
 }
 
+// The core mover's options, refilled per call (the binding reads it
+// synchronously); `up` is the 2d direction lifted into the plane.
+const MOVE_OPTIONS: CoreMoveOptions & { up: [number, number, number] } = { up: [0, -1, 0] }
+
+/** Pack a 2d volume into the core's scratch at z = 0: a circle is a
+ * capsule with a == b, a rect a "box" turned about z. Returns the kind. */
+function packVolume(volume: Volume, site: string): "capsule" | "box" {
+  if ("width" in volume) {
+    if (!(volume.width >= 0 && volume.height >= 0)) {
+      throw new Error(site + ": width and height must be >= 0, got " + volume.width + " x " + volume.height)
+    }
+    let half = (volume.rotation ?? 0) / 2
+    BOX[0] = volume.x + volume.width / 2
+    BOX[1] = volume.y + volume.height / 2
+    BOX[2] = 0
+    BOX[3] = volume.width / 2
+    BOX[4] = volume.height / 2
+    BOX[5] = BOX_HALF_DEPTH
+    BOX[6] = 0
+    BOX[7] = 0
+    BOX[8] = Math.sin(half)
+    BOX[9] = Math.cos(half)
+    return "box"
+  }
+  if (!(volume.radius >= 0)) throw new Error(site + ": radius must be >= 0, got " + volume.radius)
+  if ("x" in volume) {
+    CAPSULE[0] = volume.x
+    CAPSULE[1] = volume.y
+    CAPSULE[3] = volume.x
+    CAPSULE[4] = volume.y
+  } else {
+    CAPSULE[0] = volume.ax
+    CAPSULE[1] = volume.ay
+    CAPSULE[3] = volume.bx
+    CAPSULE[4] = volume.by
+  }
+  CAPSULE[2] = 0
+  CAPSULE[5] = 0
+  CAPSULE[6] = volume.radius
+  return "capsule"
+}
+
 /** Compose and push a node-backed sprite's local transform - through the
  * node's transition declaration, so with one set (setSpriteTransition)
  * the write is a target the core animates toward. */
@@ -542,73 +681,25 @@ function writeTransform(sprite: Sprite): void {
 }
 
 /**
- * Create a sprite layer rendering into a `width` x `height` texture from one
- * atlas texture. Disposed automatically with the owning reactive scope (opt
- * out with `{ autoFree: false }`); the atlas is NOT owned - dispose it
- * yourself (it commonly outlives layers).
+ * Create a sprite layer over one atlas texture. It renders nothing by
+ * itself: `layer.createView({ width, height })` (or a `<SpriteLayer>` /
+ * `<View2d>`) is where it shows, once or many times. Disposed
+ * automatically with the owning reactive scope (opt out with
+ * `{ autoFree: false }`); the atlas is NOT owned - dispose it yourself
+ * (it commonly outlives layers).
  */
-export function createSpriteLayer(
-  width: number,
-  height: number,
-  atlas: TextureId,
-  opts?: SpriteLayerOptions,
-): SpriteLayer {
+export function createSpriteLayer(atlas: TextureId, opts?: SpriteLayerOptions): SpriteLayer {
   let capacity = opts?.capacity ?? 1024
   if (!(capacity > 0 && Number.isInteger(capacity))) {
     throw new Error(`createSpriteLayer: capacity must be a positive integer, got ${capacity}`)
   }
   let label = opts?.label ?? "sprites"
-  let oversample = opts?.oversample ?? 1
-  checkOversample("createSpriteLayer", oversample, width, height)
   let tint = opts?.tint ?? [1, 1, 1, 1]
   checkTint("createSpriteLayer", tint)
-  let thrash = thrashSentinel(`sprite layer "${label}"`)
-  // One unit quad (triangle strip), reused by every instance.
-  let quad = createBuffer(new Float32Array([-0.5, -0.5, 0.5, -0.5, -0.5, 0.5, 0.5, 0.5]), {
-    label: `${label}-quad`,
-    autoFree: false,
-  })
   let pose: BufferId = createBuffer(capacity * POSE_FLOATS * 4, { label: `${label}-pose`, autoFree: false })
   let style: BufferId = createBuffer(capacity * STYLE_FLOATS * 4, { label: `${label}-style`, autoFree: false })
-  let texture = createPipelineTexture(
-    VERTEX_SPLIT,
-    FRAGMENT,
-    width * oversample,
-    height * oversample,
-    { uViewport: [width, height], uCamera: [0, 0, 1, 1], uCameraRot: [1, 0, 0, 0], uTint: tint },
-    {
-      label,
-      topology: "triangle-strip",
-      vertexCount: 4,
-      attributes: [{ name: "aPos", format: "vec2" }],
-      buffer: quad,
-      instanceAttributes: INSTANCE_ATTRIBUTES_SPLIT,
-      instanceBuffers: [pose, style],
-      // "y" keys on world y in the pose record (slot 0), "renderOrder" on the
-      // app-owned key in the style record (slot 1); either way the core
-      // gathers BOTH buffers under the one permutation at every publish
-      // and republishes the sibling itself when the key buffer re-orders.
-      instanceOrder:
-        opts?.orderBy === "y"
-          ? { field: POSE_Y_FIELD }
-          : opts?.orderBy === "renderOrder"
-            ? { field: STYLE_KEY_FIELD, slot: 1 }
-            : undefined,
-      instanceCount: 0,
-      blend: "alpha",
-      textures: { uAtlas: atlas },
-      clearColor: opts?.clearColor ?? [0, 0, 0, 0],
-      autoFree: false,
-    },
-  )
+  let gpu = createSpritePipeline(label, VERTEX_SPLIT, INSTANCE_ATTRIBUTES_SPLIT)
 
-  // Camera state, mirrored for picking (the inverse mapping).
-  let camX = 0
-  let camY = 0
-  let camZoom = 1
-  let camRot = 0
-  let camPivotX = 0
-  let camPivotY = 0
   let disposed = false
   let scheduled = false
   let styleDirty = false
@@ -622,6 +713,30 @@ export function createSpriteLayer(
   let gpuCapacity = capacity
   let styleData = new Float32Array(capacity * STYLE_FLOATS)
   let byNode = new Map<NodeId, SpriteState>()
+  // The layer's root node (identity): parentless sprites and groups hang
+  // off it, so a query scoped to it sees exactly this layer.
+  fillTransform(0, 0, 0, 1, 1)
+  let root = spatial.createNode(TRANSFORM, true)
+  let filter: QueryFilter = { root }
+  // Refill the layer's one filter for a query: the root always, the
+  // include-list as the sprites' nodes when given.
+  let queryFilter = (opts: QueryOptions | undefined, site: string): void => {
+    if (opts?.sprites === undefined) {
+      filter.nodes = undefined
+      return
+    }
+    let nodes: NodeId[] = []
+    for (let sprite of opts.sprites) {
+      if (sprite.layer !== layer) throw new Error(site + ": a sprite in `sprites` belongs to another layer")
+      nodes.push(sprite.node!)
+    }
+    filter.nodes = nodes
+  }
+  let impactOf = (h: CoreImpact): Impact | null => {
+    let sprite = byNode.get(h.node)
+    if (!sprite) return null
+    return { sprite, time: h.time, point: [h.point[0], h.point[1]], normal: [h.normal[0], h.normal[1]] }
+  }
 
   let flush = () => {
     scheduled = false
@@ -633,7 +748,7 @@ export function createSpriteLayer(
       endBufferWrite(style, highWater * STYLE_FLOATS * 4)
     }
     if (published !== highWater) {
-      setDraw(texture, { instanceCount: highWater })
+      views.setCount(highWater)
       published = highWater
     }
     // The core recomputes moved subtrees and publishes every dirty pose
@@ -644,7 +759,7 @@ export function createSpriteLayer(
   // Grow both instance buffers to `next` slots: the pose sinks move in one
   // retargetRecords call (the whole used range republishes at the next
   // flush), the style mirror grows in JS and republishes through the lease.
-  // The entry holds the old buffers alive until the swap lands, so the
+  // The entries hold the old buffers alive until the swaps land, so the
   // destroys are safe to issue right after.
   let grow = (next: number) => {
     let newPose = createBuffer(next * POSE_FLOATS * 4, { label: `${label}-pose`, autoFree: false })
@@ -653,7 +768,7 @@ export function createSpriteLayer(
     let grownStyle = new Float32Array(next * STYLE_FLOATS)
     grownStyle.set(styleData)
     styleData = grownStyle
-    setDraw(texture, { instanceBuffers: [newPose, newStyle] })
+    views.setBuffers({ instanceBuffers: [newPose, newStyle] })
     destroyBuffer(pose)
     destroyBuffer(style)
     pose = newPose
@@ -690,71 +805,41 @@ export function createSpriteLayer(
     }
   }
 
-  let listeners = new Set<LayerPointerListener>()
+  let views = createViews({
+    label,
+    pipeline: gpu.pipeline,
+    quad: gpu.quad,
+    atlas,
+    buffers: () => ({ instanceBuffers: [pose, style] }),
+    count: () => published,
+    tint: () => tint,
+    pick: (x, y) => layer.pick(x, y),
+    // The order key one view entry declares: "y" on world y in the pose
+    // record (slot 0), "renderOrder" on the app-owned key in the style
+    // record (slot 1); either way the core gathers BOTH buffers under the
+    // one permutation at every publish and republishes the sibling itself
+    // when the key buffer re-orders.
+    order:
+      opts?.orderBy === "y"
+        ? { field: POSE_Y_FIELD }
+        : opts?.orderBy === "renderOrder"
+          ? { field: STYLE_KEY_FIELD, slot: 1 }
+          : undefined,
+  })
 
   let layer: SpriteLayer = {
-    texture,
-    handlers: undefined as unknown as SpriteHandlers,
     get count() {
       return byNode.size
     },
-    get width() {
-      return width
-    },
-    get height() {
-      return height
-    },
-    setSize(w, h) {
-      if (disposed || (w === width && h === height)) return
-      checkOversample("setSize", oversample, w, h)
-      width = w
-      height = h
-      setTargetSize(texture, w * oversample, h * oversample)
-      setTargetParams(texture, { uViewport: [w, h] })
-    },
-    listen(listener) {
-      listeners.add(listener)
-      return () => {
-        listeners.delete(listener)
-      }
-    },
-    get oversample() {
-      return oversample
-    },
-    setOversample(n) {
-      if (disposed || n === oversample) return
-      checkOversample("setOversample", n, width, height)
-      thrash()
-      oversample = n
-      setTargetSize(texture, width * n, height * n)
-    },
-    setCamera(update) {
-      if (disposed) return
-      checkCamera(update)
-      if (update.x !== undefined) camX = update.x
-      if (update.y !== undefined) camY = update.y
-      if (update.zoom !== undefined) camZoom = update.zoom
-      if (update.rotation !== undefined) camRot = update.rotation
-      if (update.pivotX !== undefined) camPivotX = update.pivotX
-      if (update.pivotY !== undefined) camPivotY = update.pivotY
-      setTargetParams(texture, {
-        uCamera: [camX, camY, camZoom, camZoom],
-        uCameraRot: [Math.cos(camRot), Math.sin(camRot), camPivotX, camPivotY],
-      })
-    },
-    camera() {
-      return { x: camX, y: camY, zoom: camZoom, rotation: camRot, pivotX: camPivotX, pivotY: camPivotY }
-    },
-    project(x, y) {
-      return projectCamera(layer.camera(), x, y)
-    },
-    unproject(x, y) {
-      return unprojectCamera(layer.camera(), x, y)
-    },
     setTint(next) {
       if (disposed) return
       checkTint("setTint", next)
-      setTargetParams(texture, { uTint: next })
+      tint = next
+      views.setTint(next)
+    },
+    createView(vopts) {
+      if (disposed) throw new Error("createView: layer is disposed")
+      return views.create(vopts)
     },
     pick(x, y) {
       // The index reads as of the last core flush; run any pending batch
@@ -762,11 +847,13 @@ export function createSpriteLayer(
       if (scheduled) flush()
       RAY_ORIGIN[0] = x
       RAY_ORIGIN[1] = y
-      RAY_ORIGIN[2] = -1
+      RAY_ORIGIN[2] = PICK_RAY_START
+      RAY_DIR[0] = 0
+      RAY_DIR[1] = 0
+      RAY_DIR[2] = 1
+      filter.nodes = undefined
       let out: Sprite[] = []
-      for (let hit of spatial.raycast(RAY_ORIGIN, RAY_DIR)) {
-        // The arena is shared (a 3d scene lives in the same index): only
-        // this layer's nodes count.
+      for (let hit of spatial.raycast(RAY_ORIGIN, RAY_DIR, filter)) {
         let sprite = byNode.get(hit.node)
         if (sprite) out.push(sprite)
       }
@@ -774,29 +861,82 @@ export function createSpriteLayer(
       return out.sort((a, b) => b._slot - a._slot)
     },
     pickRect(x, y, width, height) {
-      if (scheduled) flush()
-      // The marquee as a "box" volume: center, half extents, no rotation,
-      // a unit deep so every sprite plane (z = 0) lies inside it.
-      BOX[0] = x + width / 2
-      BOX[1] = y + height / 2
-      BOX[2] = 0
-      BOX[3] = width / 2
-      BOX[4] = height / 2
-      BOX[5] = 1
       let out: Sprite[] = []
-      for (let hit of spatial.overlap("box", BOX)) {
-        let sprite = byNode.get(hit.node)
-        if (sprite) out.push(sprite)
+      for (let hit of layer.overlap({ x, y, width, height })) out.push(hit.sprite)
+      return out
+    },
+    raycast(x, y, dx, dy, opts) {
+      if (scheduled) flush()
+      RAY_ORIGIN[0] = x
+      RAY_ORIGIN[1] = y
+      RAY_ORIGIN[2] = 0
+      RAY_DIR[0] = dx
+      RAY_DIR[1] = dy
+      RAY_DIR[2] = 0
+      queryFilter(opts, "raycast")
+      let out: RayHit[] = []
+      for (let h of spatial.raycast(RAY_ORIGIN, RAY_DIR, filter)) {
+        let sprite = byNode.get(h.node)
+        if (sprite) out.push({ sprite, distance: h.distance, point: [h.point[0], h.point[1]], normal: [h.normal[0], h.normal[1]] })
       }
       return out
     },
-    handlersFor(layout) {
-      return dispatch(layout)
+    overlap(volume, opts) {
+      if (scheduled) flush()
+      let kind = packVolume(volume, "overlap")
+      queryFilter(opts, "overlap")
+      let out: Overlap[] = []
+      for (let h of spatial.overlap(kind, kind === "box" ? BOX : CAPSULE, filter)) {
+        let sprite = byNode.get(h.node)
+        if (sprite) out.push({ sprite, point: [h.point[0], h.point[1]], normal: [h.normal[0], h.normal[1]], depth: h.depth })
+      }
+      return out
+    },
+    sweep(volume, dx, dy, opts) {
+      if (scheduled) flush()
+      let kind = packVolume(volume, "sweep")
+      MOTION[0] = dx
+      MOTION[1] = dy
+      MOTION[2] = 0
+      queryFilter(opts, "sweep")
+      let out: Impact[] = []
+      for (let h of spatial.sweep(kind, kind === "box" ? BOX : CAPSULE, MOTION, filter)) {
+        let impact = impactOf(h)
+        if (impact) out.push(impact)
+      }
+      return out
+    },
+    moveAndSlide(volume, dx, dy, opts) {
+      if (scheduled) flush()
+      let kind = packVolume(volume, "moveAndSlide")
+      MOTION[0] = dx
+      MOTION[1] = dy
+      MOTION[2] = 0
+      queryFilter(opts, "moveAndSlide")
+      let up = opts?.up ?? UP_2D
+      MOVE_OPTIONS.up[0] = up[0]
+      MOVE_OPTIONS.up[1] = up[1]
+      MOVE_OPTIONS.floorMaxAngle = opts?.floorMaxAngle
+      MOVE_OPTIONS.maxSlides = opts?.maxSlides
+      MOVE_OPTIONS.skin = opts?.skin
+      MOVE_OPTIONS.floorSnap = opts?.floorSnap
+      let r = spatial.moveAndSlide(kind, kind === "box" ? BOX : CAPSULE, MOTION, MOVE_OPTIONS, filter)
+      let hits: Impact[] = []
+      for (let h of r.hits) {
+        let impact = impactOf(h)
+        if (impact) hits.push(impact)
+      }
+      return {
+        motion: [r.motion[0], r.motion[1]],
+        floor: r.floor === null ? null : [r.floor[0], r.floor[1]],
+        wall: r.wall,
+        ceiling: r.ceiling,
+        hits,
+      }
     },
     dispose() {
       if (disposed) return
       disposed = true
-      listeners.clear()
       for (let sprite of byNode.values()) {
         sprite.layer = null
         declared.delete(sprite.node!)
@@ -809,13 +949,14 @@ export function createSpriteLayer(
         spatial.destroyNode(group.node)
       }
       layer._groups.clear()
+      spatial.destroyNode(root)
       // Let the core emit its final slot-zeroing writes while the pose
       // buffer still exists, then free everything.
       spatial.flush()
-      destroyTexture(texture)
+      views.dispose()
       destroyBuffer(pose)
       destroyBuffer(style)
-      destroyBuffer(quad)
+      gpu.dispose()
     },
     _add(opts) {
       if (disposed) throw new Error("addSprite: layer is disposed")
@@ -842,8 +983,10 @@ export function createSpriteLayer(
         if (opts.parent.layer !== layer) throw new Error("addSprite: parent group belongs to another layer")
         spatial.setParent(node, opts.parent.node)
         opts.parent._children.add(sprite)
+      } else {
+        spatial.setParent(node, root)
       }
-      spatial.setBounds(node, FLAT_BOUNDS)
+      spatial.setBounds(node, COLUMN_BOUNDS)
       spatial.bindPoseRecord(node, pose, slot)
       byNode.set(node, sprite)
       // renderOrder defaults to 0 explicitly: a recycled slot holds the
@@ -912,16 +1055,8 @@ export function createSpriteLayer(
       RESOLVED.then(flush)
     },
     _groups: new Set(),
+    _root: root,
   }
-  let dispatch = spriteDispatch({
-    size: () => [width, height],
-    camera: () => layer.camera(),
-    pick: (x, y) => layer.pick(x, y),
-    root: layer,
-    listeners,
-  })
-  layer.handlers = dispatch(null)
-
   if (opts?.autoFree !== false && getOwner()) onCleanup(() => layer.dispose())
   return layer
 }
@@ -991,7 +1126,9 @@ export function setSpriteParent(sprite: Sprite, parent: SpriteGroup | null): voi
   if (!layer) return
   if (sprite.node === null) throw new Error("setSpriteParent: record layers have no groups")
   if (parent && parent.layer !== layer) throw new Error("setSpriteParent: group belongs to another layer")
-  spatial.setParent(sprite.node, parent ? parent.node : null)
+  // A sprite with a node is on a node layer (the throw above), which TS
+  // cannot narrow through sprite.layer.
+  spatial.setParent(sprite.node, parent ? parent.node : (layer as SpriteLayer)._root)
   let s: SpriteState = sprite
   if (s._parent) s._parent._children.delete(s)
   s._parent = parent
@@ -1046,6 +1183,8 @@ export function addGroup(layer: SpriteLayer, opts?: GroupOptions): SpriteGroup {
     if (opts.parent.layer !== layer) throw new Error("addGroup: parent group belongs to another layer")
     spatial.setParent(group.node, opts.parent.node)
     opts.parent._children.add(group)
+  } else {
+    spatial.setParent(group.node, layer._root)
   }
   layer._groups.add(group)
   layer._schedule()
@@ -1077,7 +1216,7 @@ export function setGroup(group: SpriteGroup, opts: GroupOptions): void {
   }
   if (opts.parent !== undefined) {
     if (opts.parent && opts.parent.layer !== layer) throw new Error("setGroup: parent group belongs to another layer")
-    spatial.setParent(group.node, opts.parent ? opts.parent.node : null)
+    spatial.setParent(group.node, opts.parent ? opts.parent.node : layer._root)
     if (g._parent) g._parent._children.delete(g)
     g._parent = opts.parent
     if (opts.parent) opts.parent._children.add(g)