@solidrt/2d 0.0.55 → 0.0.57

package/src/layer.ts

@@ -2,17 +2,18 @@
 // 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
-// nodes moved); slot 1 is the style buffer [u0, v0, u1, v1, tint rgba],
-// JS-owned and published through the zero-copy write lease. Never write
+// nodes moved); slot 1 is the style buffer [u0, v0, u1, v1, tint rgba,
+// renderOrder], JS-owned and published through the zero-copy write lease. Never write
 // the pose buffer from JS - the core's staging mirror is the owner and
 // will overwrite. For motion only JS can compute at large populations, the
 // records layer (records.ts) is the escape hatch.
@@ -20,43 +21,69 @@
 // 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 is a shared-params write (uCamera), never per-sprite.
+// 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 } from "@solidrt/core"
-import {
-  beginBufferWrite,
-  createBuffer,
-  createPipelineTexture,
-  destroyBuffer,
-  destroyTexture,
-  endBufferWrite,
-  setDraw,
-  setTargetParams,
-  setTargetSize,
-} from "@solidrt/core/gpu"
+import type { PointerEvent as ElementPointerEvent, WheelEvent as ElementWheelEvent } from "@solidrt/core"
+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 { checkOversample } from "./oversample.ts"
+import type { CameraState, CameraUpdate } from "./camera.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
-/** Floats per style record: [u0, v0, u1, v1, tintR, tintG, tintB, tintA]. */
-export const STYLE_FLOATS = 8
+
+// Float offset of world y in a pose record - what `orderBy: "y"` keys on.
+const POSE_Y_FIELD = 1
+/** Floats per style record:
+ * [u0, v0, u1, v1, tintR, tintG, tintB, tintA, renderOrder]. */
+export const STYLE_FLOATS = 9
+
+// Float offset of renderOrder in a style record - what `orderBy: "renderOrder"`
+// keys on.
+const STYLE_KEY_FIELD = 8
 
 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(6)
+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)
 
 // Settle routing: the core's "spatialTransitionEnd" event carries the node
 // id, so the handles with a transition DECLARED are indexed by node (only
@@ -91,37 +118,60 @@ function declareTransition(node: NodeId, handle: Sprite | SpriteGroup, transitio
  * fields - they touch no GPU state (the scene-graph handler rule).
  */
 export type Sprite = {
-  /** The owning layer, null after removeSprite. */
-  layer: SpriteLayer | RecordLayer | null
+  /** The owning layer, null after removeSprite (which owns the write). */
+  readonly layer: SpriteLayer | RecordLayer | null
   /**
    * The sprite's SPATIAL ARENA node - the citizenship handle: bind core
    * producers to it or reach it through flux:spatial directly (the layer
    * still owns the node's life; destroy it only via removeSprite). Null
    * on a record layer's sprites.
    */
-  node: NodeId | null
+  readonly node: NodeId | null
   /** Instance slot: fixed for the sprite's life on the node layer, the
-   * shifting draw-order index on a record layer. */
-  _slot: number
-  /** Pose mirror (node layer): what setSprite composes transforms from. */
-  _x: number
-  _y: number
-  _w: number
-  _h: number
-  _rot: number
-  /** Mirror flags (both layer kinds): re-applied to every frame write. */
-  _flipX: boolean
-  _flipY: boolean
+   * shifting draw-order index on a record layer. Readable (readonly, like
+   * the other underscore fields: cheap reads without getSprite's
+   * allocation); writes go through setSprite. */
+  readonly _slot: number
+  /** Pose mirror (node layer): what setSprite composes transforms from.
+   * On a RECORD layer this mirror goes stale once records are written
+   * raw - there the records array is the truth. */
+  readonly _x: number
+  readonly _y: number
+  readonly _w: number
+  readonly _h: number
+  readonly _rot: number
+  /** Mirror flags (both layer kinds): re-applied to every frame write.
+   * The cheap way to read flip state. */
+  readonly _flipX: boolean
+  readonly _flipY: boolean
+  /** Visibility mirror (node layer; always true on a record layer's
+   * sprites). The cheap read; writes go through setSprite. */
+  readonly _visible: boolean
+  /** The enclosing group (null at the layer root, always null on a record
+   * layer's sprites) - the bubble path; writes go through
+   * setSpriteParent/addSprite's `parent`. */
+  readonly _parent: SpriteGroup | null
   onPointerDown?: (event: SpritePointerEvent) => void
   onPointerMove?: (event: SpritePointerEvent) => void
   onPointerUp?: (event: SpritePointerEvent) => void
   onPointerEnter?: (event: SpritePointerEvent) => void
   onPointerLeave?: (event: SpritePointerEvent) => void
+  /** A wheel notch over the sprite; bubbles like down/move/up. */
+  onWheel?: (event: SpriteWheelEvent) => void
+  /** A press that released on this sprite without dragging (see
+   * SpriteTapEvent); bubbles like down/move/up. */
+  onTap?: (event: SpriteTapEvent) => void
   /** A declared transition (setSpriteTransition) settled naturally on
    * one component; a cancel or snap never fires. */
   onTransitionEnd?: (event: TransitionEndEvent) => void
 }
 
+/** The layer-internal mutable view of a Sprite: the readonly on the
+ * underscore fields is for the public surface; internal write sites
+ * annotate with this (readonly does not affect assignability, so the two
+ * types flow into each other freely). */
+export type SpriteState = { -readonly [K in keyof Sprite]: Sprite[K] }
+
 /** The settled component of a node transition: `position` is x/y,
  * `scale` w/h (a group's uniform scale). */
 export type TransitionEndEvent = {
@@ -148,17 +198,41 @@ export type SpriteOptions = {
   rotation?: number
   /** RGBA multiplier 0..1 each; default opaque white (the texture as-is). */
   tint?: [number, number, number, number]
+  /**
+   * Explicit draw-order key, read only by a layer created with `orderBy:
+   * "renderOrder"` (default 0; ties keep slot order, so untouched sprites draw
+   * as without one). The raise idiom: `setSprite(hit, { renderOrder: ++top })`
+   * on interaction, back to 0 to restore. Node layer only - a record
+   * layer's 13-float record has no key field (order it by one of its own
+   * fields with `orderBy: { field }`); setting this there throws.
+   */
+  renderOrder?: number
+  /**
+   * Show or hide the sprite (default true), @solidrt/3d's setVisible in
+   * the setSprite bag: hidden, its pose slot zeroes (nothing drawn) and
+   * pick/pickRect skip it; the handle, slot, style records and any
+   * running transition state stay, so showing again restores the sprite
+   * as it was. Node layer only - a record sprite has no node (hide it by
+   * zeroing w or h); setting this there throws.
+   */
+  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); pose fields are then local
-   * to it. Reparent later with setSpriteParent. */
-  parent?: SpriteGroup
+  /** Mount under this group (node layer only; null = the layer root, the
+   * default); pose fields are then local to it. Reparent later with
+   * setSpriteParent. */
+  parent?: SpriteGroup | null
 }
 
-export type SpritePointerEvent = {
-  /** The sprite hit (the topmost at the point), constant while captured. */
-  sprite: Sprite
+/** What every layer pointer event carries, whichever handler sees it. */
+export type LayerEventBase = {
   /** Pointer position in LAYER pixels (the camera mapping undone). */
   x: number
   y: number
@@ -169,6 +243,74 @@ export type SpritePointerEvent = {
   ctrlKey: boolean
   altKey: boolean
   metaKey: boolean
+  /**
+   * The element event the layer's leaf received, in the leaf's own frame
+   * (localX/localY, clientX/clientY, movementX/Y): what core's
+   * recognizers consume, so a sprite drags itself through `createPan` and
+   * a camera rides `createTransform` on the same events the walk carries.
+   */
+  native: ElementPointerEvent
+  /**
+   * Stops the walk after the current handler: no enclosing group and none
+   * of the layer's listeners see the event. Stopping a DOWN claims the
+   * whole press - that pointer's move, up and tap never reach the layer
+   * either, so a sprite that drags itself stops its down once and a
+   * camera attached at the root never pans it.
+   */
+  stopPropagation(): void
+}
+
+/** The event as a sprite's or group's handler sees it. */
+export type SpritePointerEvent = LayerEventBase & {
+  /** The sprite the event is about (the topmost hit at the point, or the
+   * captured sprite during a drag) - constant while the event bubbles. */
+  sprite: Sprite
+  /** The sprite or group whose handler is running; changes as the event
+   * bubbles from the hit sprite through its enclosing groups. */
+  currentTarget: Sprite | SpriteGroup
+}
+
+/**
+ * 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 view is the only target.
+ */
+export type LayerPointerEvent = LayerEventBase & {
+  sprite: Sprite | null
+  currentTarget: ViewHandle
+}
+
+type WheelFields = {
+  /** The wheel delta as the element event reports it. */
+  deltaX: number
+  deltaY: number
+  native: ElementWheelEvent
+}
+type TapFields = {
+  /** 1 for a tap, 2 for the second of a double tap (the same target,
+   * within the repeat interval and distance), and so on - DOM's `detail`,
+   * Unity's `clickCount`. */
+  tapCount: number
+}
+
+export type SpriteWheelEvent = SpritePointerEvent & WheelFields
+export type LayerWheelEvent = LayerPointerEvent & WheelFields
+/**
+ * A press that released on the target it pressed without travelling past
+ * the slop, the only pointer down for its whole press (a pinch never taps).
+ * Dispatched after the up, bubbling the same way; `x`/`y` are the release
+ * point.
+ */
+export type SpriteTapEvent = SpritePointerEvent & TapFields
+export type LayerTapEvent = LayerPointerEvent & TapFields
+
+/** A listener at a view's root; see ViewHandle.listen. */
+export type LayerPointerListener = {
+  onPointerDown?: (event: LayerPointerEvent) => void
+  onPointerMove?: (event: LayerPointerEvent) => void
+  onPointerUp?: (event: LayerPointerEvent) => void
+  onWheel?: (event: LayerWheelEvent) => void
+  onTap?: (event: LayerTapEvent) => void
 }
 
 export type SpriteHandlers = {
@@ -176,14 +318,15 @@ export type SpriteHandlers = {
   onPointerMove: (event: ElementPointerEvent) => void
   onPointerUp: (event: ElementPointerEvent) => void
   onPointerLeave: (event: ElementPointerEvent) => void
+  onWheel: (event: ElementWheelEvent) => void
 }
 
-export type CameraUpdate = {
-  /** World pixel at the viewport's top-left corner. */
-  x?: number
-  y?: number
-  /** World-to-screen scale; 1 is pixel-for-pixel. */
-  zoom?: number
+/** Validate an [r, g, b, a] tint (throws - the dev validation policy).
+ * Internal - every layer kind (sprite, record, tile) calls it. */
+export function checkTint(verb: string, tint: [number, number, number, number]): void {
+  if (!(Array.isArray(tint) && tint.length === 4 && tint.every(Number.isFinite))) {
+    throw new Error(`${verb}: tint must be [r, g, b, a], got ${JSON.stringify(tint)}`)
+  }
 }
 
 export type SpriteLayerOptions = {
@@ -193,19 +336,39 @@ 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 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
+  /**
+   * Draw sprites in KEY order instead of slot order, produced by core at
+   * every publish (the gpu `instanceOrder` primitive across the pose/style
+   * buffer pair - no per-sprite JS anywhere): `"y"` keys on the sprite's
+   * WORLD y, the pose the core itself writes, so a perspective crowd
+   * paints back to front (smaller y = further up the screen = drawn
+   * first) - and because the key is core-owned, sprites moved by native
+   * transitions or any other core producer re-sort with zero JS per
+   * frame. Slots stay fixed - handles, picking and the style records are
+   * untouched, only the draw order changes - and ties keep slot order, so
+   * sprites at equal y draw exactly as without it.
+   *
+   * `"renderOrder"` keys on the app-owned per-sprite `renderOrder` field instead
+   * (setSprite, default 0): explicit layering for painter-order scenes -
+   * raise a dragged piece, click-to-front, hover emphasis - with stable
+   * handles and no record churn.
+   *
+   * Known limitation for both keys: pick() resolves overlapping sprites by
+   * slot order, not visual order, when a key is set. (The record layer's
+   * RecordLayerOptions instead takes `"y"` or a raw `{ field }` offset
+   * into its own records; pose records are core-owned, so the node layer
+   * names its keys.)
+   */
+  orderBy?: "y" | "renderOrder"
 }
 
 /**
@@ -213,21 +376,44 @@ export type SpriteLayerOptions = {
  * uniform scale - never a sprite size) that sprites and other groups
  * parent under, so a ship with turrets or a dragged stack moves as one
  * subtree recomputed in native code. Groups render nothing and cannot be
- * picked; sprites are always the leaves.
+ * picked - sprites are always the leaves - but down/move/up events bubble
+ * from a hit child sprite through its enclosing groups (enter/leave pair
+ * on the sprite alone), so one group handler covers a whole assembly.
  */
 export type SpriteGroup = {
-  /** The owning layer, null after removeGroup. */
-  layer: SpriteLayer | null
+  /** The owning layer, null after removeGroup (which owns the write). */
+  readonly layer: SpriteLayer | null
   /** The group's spatial arena node. */
-  node: NodeId
-  _x: number
-  _y: number
-  _rot: number
-  _scale: number
+  readonly node: NodeId
+  /** Pose mirror (readonly, like Sprite's underscore fields: cheap reads);
+   * writes go through setGroup. */
+  readonly _x: number
+  readonly _y: number
+  readonly _rot: number
+  readonly _scale: number
+  /** Visibility mirror; writes go through setGroup. */
+  readonly _visible: boolean
+  /** See Sprite._parent. */
+  readonly _parent: SpriteGroup | null
+  /** The handles parented here (removeGroup removes them with it);
+   * internal -
+   * membership writes go through addSprite/addGroup/setSpriteParent/
+   * setGroup. */
+  readonly _children: Set<SpriteState | GroupState>
+  /** Bubbled from a hit child sprite; see SpritePointerEvent. A group
+   * never receives enter/leave (hover pairs on the sprite alone). */
+  onPointerDown?: (event: SpritePointerEvent) => void
+  onPointerMove?: (event: SpritePointerEvent) => void
+  onPointerUp?: (event: SpritePointerEvent) => void
+  onWheel?: (event: SpriteWheelEvent) => void
+  onTap?: (event: SpriteTapEvent) => void
   /** See Sprite.onTransitionEnd. */
   onTransitionEnd?: (event: TransitionEndEvent) => void
 }
 
+/** The layer-internal mutable view of a SpriteGroup (see SpriteState). */
+export type GroupState = { -readonly [K in keyof SpriteGroup]: SpriteGroup[K] }
+
 /** Group fields, all optional: absent keys keep values. */
 export type GroupOptions = {
   /** Position in the parent frame (layer pixels at the root). */
@@ -238,142 +424,185 @@ export type GroupOptions = {
   /** Uniform scale on the whole subtree (this one scales child sprites -
    * a group is a frame, not a sprite size). */
   scale?: number
+  /** Show or hide the group's WHOLE subtree (default true); each child
+   * keeps its own `visible`, so showing the group again restores the
+   * subtree as it was. See SpriteOptions.visible. */
+  visible?: boolean
   /** Reparent (null = make the group a root). */
   parent?: SpriteGroup | null
 }
 
 /** 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 sprite pointer events; see handlersFor. */
-  handlers: SpriteHandlers
   /** Live sprite count. */
   readonly count: number
-  setSize(width: number, height: number): 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.
+   * 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) 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.
    */
-  setOversample(n: number): void
-  setCamera(update: CameraUpdate): void
-  /** Topmost sprite whose rotated rect contains the layer-pixel point. */
-  pick(x: number, y: number): Sprite | null
+  setTint(tint: [number, number, number, number]): void
+  /** Every shown sprite whose rotated rect contains the layer-pixel point
+   * (a hidden sprite or subtree is never hit), topmost first - the
+   * 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). 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; null layout means "already layer pixels",
-   * which is what the built-in leaf uses).
+   * 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 } | null) | null): SpriteHandlers
+  createView(opts: ViewOptions): ViewHandle
   dispose(): void
   _add(opts?: AddSpriteOptions): Sprite
-  _write(sprite: Sprite, opts: SpriteOptions): void
+  _write(sprite: SpriteState, opts: SpriteOptions): void
   _read(sprite: Sprite): Required<SpriteOptions>
-  _remove(sprite: Sprite): void
+  _remove(sprite: SpriteState): void
   _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 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.
+   * Every shown sprite whose rotated rect overlaps the layer-pixel rect
+   * (the core BVH overlap query, exact for rotated sprites), unordered -
+   * the marquee query: `overlap` over an unrotated rect, sprites only.
+   * Node layer only.
    */
-  pickRect(x: number, y: number, w: number, h: number): Sprite[]
-  _groups: Set<SpriteGroup>
-}
-
-/**
- * Pointer dispatch shared by both layer kinds: capture per pointer, hover
- * pairing, no bubbling (the sprite list is flat). Layout null = the leaf is
- * laid out at layer size, so localX/localY are layer pixels already (the
- * element hit test undid every ancestor transform - never getBoundingBox
- * here). Internal - layers expose the result as handlers/handlersFor.
- */
-export function spriteDispatch(state: {
-  size: () => [number, number]
-  camera: () => [number, number, number]
-  pick: (x: number, y: number) => Sprite | null
-}): (layout: (() => { width: number; height: number } | null) | null) => SpriteHandlers {
-  let capture = new Map<number, Sprite>()
-  let hover = new Map<number, Sprite>()
-  return layout => {
-    let toLayer = (e: ElementPointerEvent): [number, number] => {
-      let x = e.localX
-      let y = e.localY
-      let l = layout?.()
-      let [width, height] = state.size()
-      if (l && l.width > 0 && l.height > 0) {
-        x *= width / l.width
-        y *= height / l.height
-      }
-      // Undo the camera: screen -> world.
-      let [camX, camY, camZoom] = state.camera()
-      return [x / camZoom + camX, y / camZoom + camY]
-    }
-    let makeEvent = (sprite: Sprite, x: number, y: number, e: ElementPointerEvent): SpritePointerEvent => ({
-      sprite,
-      x,
-      y,
-      pointerId: e.pointerId,
-      pointerType: e.pointerType,
-      button: e.button,
-      shiftKey: e.shiftKey,
-      ctrlKey: e.ctrlKey,
-      altKey: e.altKey,
-      metaKey: e.metaKey,
-    })
-    return {
-      onPointerDown(e) {
-        let [x, y] = toLayer(e)
-        let hit = state.pick(x, y)
-        if (!hit) return
-        capture.set(e.pointerId, hit)
-        hit.onPointerDown?.(makeEvent(hit, x, y, e))
-      },
-      onPointerMove(e) {
-        let [x, y] = toLayer(e)
-        let captured = capture.get(e.pointerId)
-        if (captured) {
-          if (captured.layer) captured.onPointerMove?.(makeEvent(captured, x, y, e))
-          return
-        }
-        let hit = state.pick(x, y)
-        let prev = hover.get(e.pointerId) ?? null
-        if (prev !== hit) {
-          if (prev && prev.layer) prev.onPointerLeave?.(makeEvent(prev, x, y, e))
-          if (hit) hit.onPointerEnter?.(makeEvent(hit, x, y, e))
-          if (hit) hover.set(e.pointerId, hit)
-          else hover.delete(e.pointerId)
-        }
-        hit?.onPointerMove?.(makeEvent(hit, x, y, e))
-      },
-      onPointerUp(e) {
-        let [x, y] = toLayer(e)
-        let captured = capture.get(e.pointerId)
-        if (captured) {
-          capture.delete(e.pointerId)
-          if (captured.layer) captured.onPointerUp?.(makeEvent(captured, x, y, e))
-          return
-        }
-        let hit = state.pick(x, y)
-        hit?.onPointerUp?.(makeEvent(hit, x, y, e))
-      },
-      onPointerLeave(e) {
-        let [x, y] = toLayer(e)
-        let prev = hover.get(e.pointerId)
-        if (prev) {
-          hover.delete(e.pointerId)
-          if (prev.layer) prev.onPointerLeave?.(makeEvent(prev, x, y, e))
-        }
-      },
-    }
-  }
+  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
@@ -401,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. */
@@ -410,57 +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)
-  // 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 tint = opts?.tint ?? [1, 1, 1, 1]
+  checkTint("createSpriteLayer", tint)
   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] },
-    {
-      label,
-      topology: "triangle-strip",
-      vertexCount: 4,
-      attributes: [{ name: "aPos", format: "vec2" }],
-      buffer: quad,
-      instanceAttributes: INSTANCE_ATTRIBUTES_SPLIT,
-      instanceBuffers: [pose, style],
-      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 disposed = false
   let scheduled = false
   let styleDirty = false
@@ -473,7 +712,31 @@ export function createSpriteLayer(
   let freeSlots: number[] = []
   let gpuCapacity = capacity
   let styleData = new Float32Array(capacity * STYLE_FLOATS)
-  let byNode = new Map<NodeId, Sprite>()
+  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
@@ -485,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
@@ -496,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 })
@@ -505,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
@@ -514,7 +777,7 @@ export function createSpriteLayer(
     styleDirty = true
   }
 
-  let writeStyle = (sprite: Sprite, opts: SpriteOptions) => {
+  let writeStyle = (sprite: SpriteState, opts: SpriteOptions) => {
     let at = sprite._slot * STYLE_FLOATS
     let flipX = opts.flipX !== undefined && opts.flipX !== sprite._flipX
     let flipY = opts.flipY !== undefined && opts.flipY !== sprite._flipY
@@ -536,46 +799,47 @@ export function createSpriteLayer(
       styleData[at + 7] = opts.tint[3]
       styleDirty = true
     }
+    if (opts.renderOrder !== undefined) {
+      styleData[at + STYLE_KEY_FIELD] = opts.renderOrder
+      styleDirty = true
+    }
   }
 
-  let dispatch = spriteDispatch({
-    size: () => [width, height],
-    camera: () => [camX, camY, camZoom],
+  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
     },
-    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] })
-    },
-    get oversample() {
-      return oversample
-    },
-    setOversample(n) {
-      if (disposed || n === oversample) return
-      checkOversample("setOversample", n, width, height)
-      oversample = n
-      setTargetSize(texture, width * n, height * n)
-    },
-    setCamera(update) {
+    setTint(next) {
       if (disposed) return
-      if (update.x !== undefined) camX = update.x
-      if (update.y !== undefined) camY = update.y
-      if (update.zoom !== undefined) {
-        if (!(update.zoom > 0)) throw new Error(`setCamera: zoom must be positive, got ${update.zoom}`)
-        camZoom = update.zoom
-      }
-      setTargetParams(texture, { uCamera: [camX, camY, camZoom, camZoom] })
+      checkTint("setTint", 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
@@ -583,33 +847,92 @@ export function createSpriteLayer(
       if (scheduled) flush()
       RAY_ORIGIN[0] = x
       RAY_ORIGIN[1] = y
-      RAY_ORIGIN[2] = -1
-      let best: Sprite | null = null
-      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. Topmost = highest slot (draw order).
+      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, filter)) {
         let sprite = byNode.get(hit.node)
-        if (sprite && (best === null || sprite._slot > best._slot)) best = sprite
+        if (sprite) out.push(sprite)
       }
-      return best
+      // Topmost first: higher slot = drawn later = on top.
+      return out.sort((a, b) => b._slot - a._slot)
     },
-    pickRect(x, y, w, h) {
-      if (scheduled) flush()
-      BOX[0] = x
-      BOX[1] = y
-      BOX[2] = -1
-      BOX[3] = x + w
-      BOX[4] = y + h
-      BOX[5] = 1
+    pickRect(x, y, width, height) {
       let out: Sprite[] = []
-      for (let node of spatial.overlap(BOX)) {
-        let sprite = byNode.get(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
@@ -626,19 +949,20 @@ 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")
       let slot = freeSlots.pop() ?? highWater++
       if (slot >= gpuCapacity) grow(gpuCapacity * 2)
-      let sprite: Sprite = {
+      let sprite: SpriteState = {
         layer,
         node: null,
         _slot: slot,
@@ -649,18 +973,25 @@ export function createSpriteLayer(
         _rot: opts?.rotation ?? 0,
         _flipX: false,
         _flipY: false,
+        _visible: opts?.visible ?? true,
+        _parent: opts?.parent ?? null,
       }
       fillTransform(sprite._x, sprite._y, sprite._rot, sprite._w, sprite._h)
-      let node = spatial.createNode(TRANSFORM, true)
+      let node = spatial.createNode(TRANSFORM, sprite._visible)
       sprite.node = node
       if (opts?.parent) {
         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)
-      writeStyle(sprite, { frame: FULL_FRAME, tint: [1, 1, 1, 1], ...opts })
+      // renderOrder defaults to 0 explicitly: a recycled slot holds the
+      // previous occupant's key otherwise.
+      writeStyle(sprite, { frame: FULL_FRAME, tint: [1, 1, 1, 1], renderOrder: 0, ...opts })
       layer._schedule()
       return sprite
     },
@@ -672,7 +1003,18 @@ export function createSpriteLayer(
       if (opts.h !== undefined && opts.h !== sprite._h) (sprite._h = opts.h), (moved = true)
       if (opts.rotation !== undefined && opts.rotation !== sprite._rot) (sprite._rot = opts.rotation), (moved = true)
       if (moved) writeTransform(sprite)
-      if (opts.frame !== undefined || opts.tint !== undefined || opts.flipX !== undefined || opts.flipY !== undefined) {
+      if (opts.visible !== undefined && opts.visible !== sprite._visible) {
+        sprite._visible = opts.visible
+        spatial.setVisible(sprite.node!, opts.visible)
+        moved = true
+      }
+      if (
+        opts.frame !== undefined ||
+        opts.tint !== undefined ||
+        opts.flipX !== undefined ||
+        opts.flipY !== undefined ||
+        opts.renderOrder !== undefined
+      ) {
         writeStyle(sprite, opts)
       }
       if (moved || styleDirty) layer._schedule()
@@ -689,10 +1031,16 @@ export function createSpriteLayer(
         flipY: sprite._flipY,
         rotation: sprite._rot,
         tint: [styleData[at + 4]!, styleData[at + 5]!, styleData[at + 6]!, styleData[at + 7]!],
+        renderOrder: styleData[at + STYLE_KEY_FIELD]!,
+        visible: sprite._visible,
       }
     },
     _remove(sprite) {
       sprite.layer = null
+      if (sprite._parent) {
+        sprite._parent._children.delete(sprite)
+        sprite._parent = null
+      }
       // Destroying the node zeroes its pose slot at the next core flush
       // (zero scale = nothing drawn); the slot then recycles.
       byNode.delete(sprite.node!)
@@ -707,9 +1055,8 @@ export function createSpriteLayer(
       RESOLVED.then(flush)
     },
     _groups: new Set(),
+    _root: root,
   }
-  layer.handlers = dispatch(null)
-
   if (opts?.autoFree !== false && getOwner()) onCleanup(() => layer.dispose())
   return layer
 }
@@ -719,7 +1066,8 @@ export function createSpriteLayer(
  * order, and a removed sprite's slot recycles to the next add - so unlike
  * the record layer there is no painter's-insertion-order guarantee across
  * removals. Opaque-or-transparent pixel art (the overwhelming case) never
- * notices; z-ordered translucency is the sort-key backlog item. Past the
+ * notices; a scene that needs depth order sorts by world y with the
+ * layer's `orderBy: "y"` (core-produced, zero JS per frame). Past the
  * layer's reservation both instance buffers double (pose sinks move in one
  * core retarget); reserve with `capacity` to avoid the copies.
  */
@@ -745,17 +1093,46 @@ export function removeSprite(sprite: Sprite): void {
   sprite.layer?._remove(sprite)
 }
 
+/**
+ * A sprite's or group's position in LAYER pixels: its local x/y composed
+ * through every enclosing group (@solidrt/3d's worldPosition, Three's
+ * getWorldPosition), read from the core's world matrix as the tree stands
+ * now, pending writes included. Under a transition this is the
+ * mid-flight pose - what picking and the screen show - where the handle's
+ * own fields hold the target. A record layer's sprite has no groups, so
+ * its world position is its own, read as getSprite reads it (the records
+ * array). A fresh pair per call; null once the handle is inert.
+ */
+export function worldPosition(target: Sprite | SpriteGroup): [number, number] | null {
+  if (target.layer === null) return null
+  // The set only groups carry tells the two handle kinds apart (as in
+  // removeGroup); a node-less sprite is a record layer's.
+  if (!("_children" in target) && target.node === null) {
+    let s = target.layer._read(target)
+    return [s.x, s.y]
+  }
+  spatial.worldMatrix(target.node!, WORLD)
+  return [WORLD[12]!, WORLD[13]!]
+}
+
 /**
  * Re-parent a sprite under a group (null = back to the layer root); its
  * pose fields then read in the new parent's frame, where the sprite keeps
- * them (it holds its local pose, not its world pose). Node layer only.
+ * them (it holds its local pose, not its world pose; worldPosition reads
+ * the composed one). Node layer only.
  */
 export function setSpriteParent(sprite: Sprite, parent: SpriteGroup | null): void {
   let layer = sprite.layer
   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
+  if (parent) parent._children.add(s)
   layer._schedule()
 }
 
@@ -796,12 +1173,18 @@ export function addGroup(layer: SpriteLayer, opts?: GroupOptions): SpriteGroup {
     _y: opts?.y ?? 0,
     _rot: opts?.rotation ?? 0,
     _scale: opts?.scale ?? 1,
-  } as SpriteGroup
+    _visible: opts?.visible ?? true,
+    _parent: opts?.parent ?? null,
+    _children: new Set(),
+  } as GroupState
   writeGroupTransform(group)
-  group.node = spatial.createNode(TRANSFORM, true)
+  group.node = spatial.createNode(TRANSFORM, group._visible)
   if (opts?.parent) {
     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()
@@ -816,33 +1199,57 @@ function writeGroupTransform(group: SpriteGroup): void {
 export function setGroup(group: SpriteGroup, opts: GroupOptions): void {
   let layer = group.layer
   if (!layer) return
+  let g: GroupState = group
   let moved = false
-  if (opts.x !== undefined && opts.x !== group._x) (group._x = opts.x), (moved = true)
-  if (opts.y !== undefined && opts.y !== group._y) (group._y = opts.y), (moved = true)
-  if (opts.rotation !== undefined && opts.rotation !== group._rot) (group._rot = opts.rotation), (moved = true)
-  if (opts.scale !== undefined && opts.scale !== group._scale) (group._scale = opts.scale), (moved = true)
+  if (opts.x !== undefined && opts.x !== g._x) (g._x = opts.x), (moved = true)
+  if (opts.y !== undefined && opts.y !== g._y) (g._y = opts.y), (moved = true)
+  if (opts.rotation !== undefined && opts.rotation !== g._rot) (g._rot = opts.rotation), (moved = true)
+  if (opts.scale !== undefined && opts.scale !== g._scale) (g._scale = opts.scale), (moved = true)
   if (moved) {
     writeGroupTransform(group)
     spatial.writeTransform(group.node, TRANSFORM)
   }
+  if (opts.visible !== undefined && opts.visible !== g._visible) {
+    g._visible = opts.visible
+    spatial.setVisible(group.node, opts.visible)
+    moved = true
+  }
   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)
     moved = true
   }
   if (moved) layer._schedule()
 }
 
 /**
- * Remove a group: its children (sprites and groups) become layer roots and
- * KEEP THEIR LOCAL POSE, so they jump to root frame unless the caller
- * removes or re-parents them too (a component tree unmounts children first
- * and never sees this). The handle goes inert.
+ * Remove a group AND everything under it: child sprites and groups are
+ * removed with it - Unity's Destroy, Godot's free, the subtree form of
+ * removeSprite. To keep a child, re-parent it out first (setSpriteParent /
+ * setGroup's `parent`). Every removed handle goes inert. A component tree
+ * unmounts children first and never sees the recursion. (@solidrt/3d's
+ * `remove` DETACHES a re-addable subtree instead - its nodes exist outside
+ * a scene; a sprite cannot exist outside its layer, so here remove means
+ * destroy, exactly as it does for removeSprite.)
  */
 export function removeGroup(group: SpriteGroup): void {
   let layer = group.layer
   if (!layer) return
-  group.layer = null
+  let g: GroupState = group
+  // Children first, over a snapshot (each removal edits _children); the
+  // set only groups carry tells the two handle kinds apart.
+  for (let child of [...g._children]) {
+    if ("_children" in child) removeGroup(child)
+    else removeSprite(child)
+  }
+  g.layer = null
+  if (g._parent) {
+    g._parent._children.delete(g)
+    g._parent = null
+  }
   layer._groups.delete(group)
   declared.delete(group.node)
   spatial.destroyNode(group.node)