@solidrt/2d 0.0.57 → 0.0.59

package/src/layer.ts

@@ -30,13 +30,21 @@ import type { PointerEvent as ElementPointerEvent, WheelEvent as ElementWheelEve
 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 { Impact as CoreImpact, MoveOptions as CoreMoveOptions, NodeId, NodeTransition, QueryFilter } from "flux:spatial"
+import type {
+  Impact as CoreImpact,
+  MoveOptions as CoreMoveOptions,
+  NodeEndpoint,
+  NodeId,
+  NodeTransition,
+  NodeTransitionSpec,
+  QueryFilter,
+} from "flux:spatial"
 import { on } from "srt:events"
 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 { createSpritePipeline, INSTANCE_ATTRIBUTES_SPLIT, VERTEX_SPLIT } from "./shaders.ts"
+import { createSpritePipeline, INSTANCE_LAYOUTS_SPLIT, VERTEX_SPLIT } from "./shaders.ts"
 import { createViews } from "./views.ts"
 import type { ViewHandle, ViewOptions } from "./views.ts"
 
@@ -93,6 +101,26 @@ const WORLD = new Float32Array(16)
 let declared = new Map<NodeId, Sprite | SpriteGroup>()
 let subscribed = false
 
+// Free routing: a destroyed sprite or group whose declaration carries an
+// `exit` stays in the core as a LEAVING node (drawn, picked by nothing)
+// until its exits settle, and the core's "spatialNodeFreed" event says
+// when it is gone - the cue to recycle what the layer kept for it (a
+// sprite's pose slot). One lazy subscription, keyed by node.
+let freeing = new Map<NodeId, () => void>()
+let freeingSubscribed = false
+
+function onFreed(node: NodeId, done: () => void): void {
+  freeing.set(node, done)
+  if (freeingSubscribed) return
+  freeingSubscribed = true
+  on("spatialNodeFreed", (event: { node: NodeId }) => {
+    let done = freeing.get(event.node)
+    if (!done) return
+    freeing.delete(event.node)
+    done()
+  })
+}
+
 function declareTransition(node: NodeId, handle: Sprite | SpriteGroup, transition: NodeTransition | string | null): void {
   if (transition === null) {
     declared.delete(node)
@@ -118,12 +146,12 @@ 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 (which owns the write). */
+  /** The owning layer, null after destroySprite (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
+   * still owns the node's life; destroy it only via destroySprite). Null
    * on a record layer's sprites.
    */
   readonly node: NodeId | null
@@ -313,7 +341,9 @@ export type LayerPointerListener = {
   onTap?: (event: LayerTapEvent) => void
 }
 
-export type SpriteHandlers = {
+/** The element handlers for the leaf that shows a view (`ViewHandle.handlers`);
+ * spread onto the host element. */
+export type LayerHandlers = {
   onPointerDown: (event: ElementPointerEvent) => void
   onPointerMove: (event: ElementPointerEvent) => void
   onPointerUp: (event: ElementPointerEvent) => void
@@ -343,6 +373,12 @@ export type SpriteLayerOptions = {
   /** Names the GPU resources (buffers, pipeline; views default to
    * `<label>-view`); default "sprites". */
   label?: string
+  /** Stagger (ms) on the layer's root: every sprite or group added
+   * straight under the layer (no group) that enters or leaves in one
+   * frame is spaced by `index * stagger` - the whole-layer form of a
+   * group's `stagger` (a group declaring its own wins for what is under
+   * it). See setStagger. */
+  stagger?: number
   /** Skip the owner-scoped auto-dispose (see createSpriteLayer). */
   autoFree?: boolean
   /**
@@ -381,7 +417,7 @@ export type SpriteLayerOptions = {
  * on the sprite alone), so one group handler covers a whole assembly.
  */
 export type SpriteGroup = {
-  /** The owning layer, null after removeGroup (which owns the write). */
+  /** The owning layer, null after destroyGroup (which owns the write). */
   readonly layer: SpriteLayer | null
   /** The group's spatial arena node. */
   readonly node: NodeId
@@ -395,7 +431,7 @@ export type SpriteGroup = {
   readonly _visible: boolean
   /** See Sprite._parent. */
   readonly _parent: SpriteGroup | null
-  /** The handles parented here (removeGroup removes them with it);
+  /** The handles parented here (destroyGroup removes them with it);
    * internal -
    * membership writes go through addSprite/addGroup/setSpriteParent/
    * setGroup. */
@@ -476,7 +512,7 @@ export type LayerBase = {
   _add(opts?: AddSpriteOptions): Sprite
   _write(sprite: SpriteState, opts: SpriteOptions): void
   _read(sprite: Sprite): Required<SpriteOptions>
-  _remove(sprite: SpriteState): void
+  _destroy(sprite: SpriteState): void
   _schedule(): void
 }
 
@@ -499,7 +535,7 @@ export type QueryOptions = {
 
 /** 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] }
+export type Hit = { 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
@@ -564,7 +600,7 @@ export type SpriteLayer = LayerBase & {
    * 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[]
+  raycast(x: number, y: number, dx: number, dy: number, opts?: QueryOptions): Hit[]
   /**
    * Every shown sprite the volume touches, each with its deepest contact
    * (Godot's intersect_shape, Unity's OverlapCircle/Box/Capsule: a blast
@@ -600,9 +636,15 @@ export type SpriteLayer = LayerBase & {
    */
   moveAndSlide(volume: Volume, dx: number, dy: number, opts?: MoveOptions): MoveResult
   _groups: Set<GroupState>
+  /** Set (or with null clear) the stagger on the layer's root: the
+   * spacing, in ms, of the enters and exits of the sprites and groups
+   * straight under the layer that begin in one frame (SpriteLayerOptions
+   * `stagger`). */
+  setStagger(ms: number | null): void
   /** 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
+  _destroyGroup(group: GroupState): void
 }
 
 /** The stored UVs at `at` un-mirrored by the sprite's flags: the frame as
@@ -698,7 +740,7 @@ export function createSpriteLayer(atlas: TextureId, opts?: SpriteLayerOptions):
   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 gpu = createSpritePipeline(label, VERTEX_SPLIT, INSTANCE_ATTRIBUTES_SPLIT)
+  let gpu = createSpritePipeline(label, VERTEX_SPLIT, INSTANCE_LAYOUTS_SPLIT)
 
   let disposed = false
   let scheduled = false
@@ -710,6 +752,9 @@ export function createSpriteLayer(atlas: TextureId, opts?: SpriteLayerOptions):
   // collapses the instance - so holes draw nothing).
   let highWater = 0
   let freeSlots: number[] = []
+  // Destroyed handles still leaving in the core (see onFreed): a sprite's
+  // slot stays taken until the core says it is gone; dispose frees them.
+  let leaving = new Set<NodeId>()
   let gpuCapacity = capacity
   let styleData = new Float32Array(capacity * STYLE_FLOATS)
   let byNode = new Map<NodeId, SpriteState>()
@@ -718,6 +763,7 @@ export function createSpriteLayer(atlas: TextureId, opts?: SpriteLayerOptions):
   fillTransform(0, 0, 0, 1, 1)
   let root = spatial.createNode(TRANSFORM, true)
   let filter: QueryFilter = { root }
+  if (opts?.stagger !== undefined) spatial.setTransition(root, { stagger: opts.stagger })
   // 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 => {
@@ -768,7 +814,7 @@ export function createSpriteLayer(atlas: TextureId, opts?: SpriteLayerOptions):
     let grownStyle = new Float32Array(next * STYLE_FLOATS)
     grownStyle.set(styleData)
     styleData = grownStyle
-    views.setBuffers({ instanceBuffers: [newPose, newStyle] })
+    views.setBuffers([newPose, newStyle])
     destroyBuffer(pose)
     destroyBuffer(style)
     pose = newPose
@@ -810,7 +856,7 @@ export function createSpriteLayer(atlas: TextureId, opts?: SpriteLayerOptions):
     pipeline: gpu.pipeline,
     quad: gpu.quad,
     atlas,
-    buffers: () => ({ instanceBuffers: [pose, style] }),
+    buffers: () => [pose, style],
     count: () => published,
     tint: () => tint,
     pick: (x, y) => layer.pick(x, y),
@@ -823,7 +869,7 @@ export function createSpriteLayer(atlas: TextureId, opts?: SpriteLayerOptions):
       opts?.orderBy === "y"
         ? { field: POSE_Y_FIELD }
         : opts?.orderBy === "renderOrder"
-          ? { field: STYLE_KEY_FIELD, slot: 1 }
+          ? { field: STYLE_KEY_FIELD, buffer: 2 }
           : undefined,
   })
 
@@ -874,7 +920,7 @@ export function createSpriteLayer(atlas: TextureId, opts?: SpriteLayerOptions):
       RAY_DIR[1] = dy
       RAY_DIR[2] = 0
       queryFilter(opts, "raycast")
-      let out: RayHit[] = []
+      let out: Hit[] = []
       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]] })
@@ -949,6 +995,12 @@ export function createSpriteLayer(atlas: TextureId, opts?: SpriteLayerOptions):
         spatial.destroyNode(group.node)
       }
       layer._groups.clear()
+      // Corpses mid-exit go now: their slots must not outlive the buffer.
+      for (let node of leaving) {
+        freeing.delete(node)
+        spatial.destroyNode(node)
+      }
+      leaving.clear()
       spatial.destroyNode(root)
       // Let the core emit its final slot-zeroing writes while the pose
       // buffer still exists, then free everything.
@@ -1035,20 +1087,45 @@ export function createSpriteLayer(atlas: TextureId, opts?: SpriteLayerOptions):
         visible: sprite._visible,
       }
     },
-    _remove(sprite) {
+    _destroy(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!)
-      declared.delete(sprite.node!)
-      spatial.destroyNode(sprite.node!)
-      freeSlots.push(sprite._slot)
+      let node = sprite.node!
+      byNode.delete(node)
+      declared.delete(node)
+      // A declared exit keeps the node leaving: its slot keeps drawing the
+      // exit until the core frees it (the freed event lands after the
+      // flush that zeroed the slot), then recycles. Otherwise the free is
+      // immediate: the slot zeroes at the next core flush (zero scale =
+      // nothing drawn) and recycles now.
+      let slot = sprite._slot
+      if (spatial.exitNode(node)) {
+        leaving.add(node)
+        onFreed(node, () => {
+          leaving.delete(node)
+          freeSlots.push(slot)
+        })
+      } else {
+        freeSlots.push(slot)
+      }
       layer._schedule()
     },
+    _destroyGroup(group) {
+      let node = group.node
+      declared.delete(node)
+      if (spatial.exitNode(node)) {
+        leaving.add(node)
+        onFreed(node, () => leaving.delete(node))
+      }
+      layer._schedule()
+    },
+    setStagger(ms) {
+      if (disposed) return
+      spatial.setTransition(root, ms === null ? null : { stagger: ms })
+    },
     _schedule() {
       if (disposed || scheduled) return
       scheduled = true
@@ -1086,11 +1163,19 @@ export function getSprite(sprite: Sprite): Required<SpriteOptions> | null {
 }
 
 /**
- * Remove a sprite. The handle goes inert (layer null); further setSprite
- * calls are no-ops.
+ * Destroy a sprite - PixiJS's `sprite.destroy()`, Unity's Destroy: the
+ * handle goes inert (layer null; further setSprite calls are no-ops) and
+ * the sprite is gone for good. With an `exit` in its transition
+ * declaration it animates out first: each component with one plays to
+ * its exit value and the sprite stays drawn meanwhile, a ghost that no
+ * pick, raycast, overlap or sweep sees, then frees when the last exit
+ * settles (no onTransitionEnd fires for an exit: the app already let go).
+ * The one removal verb on a sprite: it cannot exist outside its layer, so
+ * there is no detach; a sprite that should come back is hidden
+ * (`visible: false`), Unity's SetActive.
  */
-export function removeSprite(sprite: Sprite): void {
-  sprite.layer?._remove(sprite)
+export function destroySprite(sprite: Sprite): void {
+  sprite.layer?._destroy(sprite)
 }
 
 /**
@@ -1106,7 +1191,7 @@ export function removeSprite(sprite: Sprite): void {
 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.
+  // destroyGroup); 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]
@@ -1136,6 +1221,92 @@ export function setSpriteParent(sprite: Sprite, parent: SpriteGroup | null): voi
   layer._schedule()
 }
 
+/** A lifecycle endpoint in the object form: the value (2d units, as the
+ * bare form) plus the motion that direction plays - a field left out is
+ * the entry's; naming a `curve` or a `bounce` decides the kind outright,
+ * so an ease-out enter pairs with an ease-in exit. */
+export type SpriteEndpoint<Value> = {
+  value: Value
+  duration?: number
+  curve?: Extract<NodeTransitionSpec, { curve: unknown }>["curve"]
+  bounce?: number
+  delay?: number
+}
+
+/** One spec of a sprite or group transition: the node vocabulary
+ * (`{ duration, bounce? }` a spring, `{ duration, curve }` a tween, or a
+ * shorthand string like "300ms ease-out 100ms"; `delay` in ms holds every
+ * write that long first) with the lifecycle endpoints in 2d units, each a
+ * bare value or a SpriteEndpoint: `from` is the component's enter value,
+ * where a freshly added sprite starts before animating to its mount pose;
+ * `exit` where it animates to when destroySprite/destroyGroup lets go of
+ * it. */
+export type SpriteTransitionSpec<Value> =
+  | { duration: number; bounce?: number; delay?: number; from?: Value | SpriteEndpoint<Value>; exit?: Value | SpriteEndpoint<Value> }
+  | {
+      duration: number
+      curve: Extract<NodeTransitionSpec, { curve: unknown }>["curve"]
+      delay?: number
+      from?: Value | SpriteEndpoint<Value>
+      exit?: Value | SpriteEndpoint<Value>
+    }
+  | string
+
+/** A sprite or group transition declaration: a spec per pose component
+ * plus `all` as a catch-all. `position` is x/y (`from: [x, y]`),
+ * `rotation` the rotation in radians (`from: angle`), `scale` a sprite's
+ * w/h (`from: [w, h]`) or a group's uniform scale (`from: s`); `exit`
+ * takes the same units. `stagger` (ms) goes on a GROUP's declaration and
+ * spaces the enters and exits of the sprites and groups under it that
+ * begin in one frame by `index * stagger` (add order for enters, tree
+ * order for exits; the nearest declaring group wins); a sprite has no
+ * children, so on a sprite it does nothing. */
+export type SpriteTransition = {
+  position?: SpriteTransitionSpec<[number, number]>
+  rotation?: SpriteTransitionSpec<number>
+  scale?: SpriteTransitionSpec<[number, number] | number>
+  all?: NodeTransitionSpec
+  stagger?: number
+}
+
+/** The 2d declaration in the arena's own lanes: endpoint values lifted
+ * into the plane (z = 0, a unit z scale, the rotation a quaternion about
+ * z), bare or inside the endpoint object; everything else passes
+ * through. */
+function toNodeTransition(transition: SpriteTransition | string | null): NodeTransition | string | null {
+  if (transition === null || typeof transition === "string") return transition
+  let out: NodeTransition = {}
+  if (transition.all !== undefined) out.all = transition.all
+  if (transition.stagger !== undefined) out.stagger = transition.stagger
+  if (transition.position !== undefined) out.position = liftSpec(transition.position, ([x, y]) => [x, y, 0])
+  if (transition.rotation !== undefined) {
+    out.rotation = liftSpec(transition.rotation, angle => [0, 0, Math.sin(angle / 2), Math.cos(angle / 2)])
+  }
+  if (transition.scale !== undefined) {
+    out.scale = liftSpec(transition.scale, s => (typeof s === "number" ? [s, s, 1] : [s[0], s[1], 1]))
+  }
+  return out
+}
+
+function liftSpec<Value>(spec: SpriteTransitionSpec<Value>, lift: (value: Value) => number[]): NodeTransitionSpec {
+  if (typeof spec === "string") return spec
+  let { from, exit, ...rest } = spec
+  let out: NodeTransitionSpec = rest
+  if (from !== undefined) out.from = liftEndpoint(from, lift)
+  if (exit !== undefined) out.exit = liftEndpoint(exit, lift)
+  return out
+}
+
+function liftEndpoint<Value>(endpoint: Value | SpriteEndpoint<Value>, lift: (value: Value) => number[]): number[] | NodeEndpoint {
+  // The object form is the one shape here with a `value` key; a bare
+  // value is a number or a pair.
+  if (typeof endpoint === "object" && endpoint !== null && !Array.isArray(endpoint)) {
+    let { value, ...motion } = endpoint as SpriteEndpoint<Value>
+    return { ...motion, value: lift(value) }
+  }
+  return lift(endpoint as Value)
+}
+
 /**
  * Declare (or with null clear) how the sprite's pose writes animate: once
  * set, setSprite writes are TARGETS the core animates toward - JS writes
@@ -1145,24 +1316,32 @@ export function setSpriteParent(sprite: Sprite, parent: SpriteGroup | null): voi
  * rotation (always the short arc) and `scale` its w/h; each spec is
  * `{ duration, bounce? }` (a spring, the retargeting-safe default) /
  * `{ duration, curve }` (a tween) / a shorthand string like
- * "300ms ease-out". Clearing cancels running tracks in place (the sprite
- * keeps its mid-flight pose) and later writes snap. Each natural settle
- * calls the sprite's `onTransitionEnd` with the component. Node layer
- * only.
+ * "300ms ease-out". A `from` on a component is its enter value: a sprite
+ * declared in the tick that added it starts there and animates to its
+ * mount pose (once, at add; a later declaration animates writes only).
+ * An `exit` is where it animates to when destroySprite lets go of it
+ * (see there); either endpoint takes a SpriteEndpoint to own its
+ * direction's motion, and `delay` holds writes. Clearing cancels running
+ * tracks in place (the sprite keeps its mid-flight pose) and later writes
+ * snap. Each natural settle calls the sprite's `onTransitionEnd` with the
+ * component. Node layer only.
  */
-export function setSpriteTransition(sprite: Sprite, transition: NodeTransition | string | null): void {
+export function setSpriteTransition(sprite: Sprite, transition: SpriteTransition | string | null): void {
   if (sprite.layer === null) return
   if (sprite.node === null) throw new Error("setSpriteTransition: record sprites have no node transitions")
-  spatial.setTransition(sprite.node, transition)
-  declareTransition(sprite.node, sprite, transition)
+  let node = toNodeTransition(transition)
+  spatial.setTransition(sprite.node, node)
+  declareTransition(sprite.node, sprite, node)
 }
 
 /** The group counterpart of setSpriteTransition (`scale` is the group's
- * uniform scale). */
-export function setGroupTransition(group: SpriteGroup, transition: NodeTransition | string | null): void {
+ * uniform scale), and the home of `stagger`: a group declaring one spaces
+ * the enters and exits of everything under it (see SpriteTransition). */
+export function setGroupTransition(group: SpriteGroup, transition: SpriteTransition | string | null): void {
   if (group.layer === null) return
-  spatial.setTransition(group.node, transition)
-  declareTransition(group.node, group, transition)
+  let node = toNodeTransition(transition)
+  spatial.setTransition(group.node, node)
+  declareTransition(group.node, group, node)
 }
 
 /** Add a transform group (see SpriteGroup). */
@@ -1226,24 +1405,26 @@ export function setGroup(group: SpriteGroup, opts: GroupOptions): void {
 }
 
 /**
- * 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.)
+ * Destroy a group AND everything under it: child sprites and groups die
+ * with it - Unity's Destroy, Godot's queue_free, the subtree form of
+ * destroySprite (@solidrt/3d's `destroy` is the same verb one dimension
+ * up). To keep a child, re-parent it out first (setSpriteParent /
+ * setGroup's `parent`). Every destroyed handle goes inert. Exits play
+ * through the whole subtree: children are let go of first, each
+ * animating its own `exit`, and the group - its own exit or not - stays
+ * in the core as their frame until the last of them has settled, then
+ * frees. A component tree unmounts children first and never sees the
+ * recursion.
  */
-export function removeGroup(group: SpriteGroup): void {
+export function destroyGroup(group: SpriteGroup): void {
   let layer = group.layer
   if (!layer) return
   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)
+    if ("_children" in child) destroyGroup(child)
+    else destroySprite(child)
   }
   g.layer = null
   if (g._parent) {
@@ -1251,7 +1432,5 @@ export function removeGroup(group: SpriteGroup): void {
     g._parent = null
   }
   layer._groups.delete(group)
-  declared.delete(group.node)
-  spatial.destroyNode(group.node)
-  layer._schedule()
+  layer._destroyGroup(g)
 }

package/src/records.ts

@@ -47,7 +47,7 @@ export type RecordLayerOptions = Omit<SpriteLayerOptions, "orderBy"> & {
    * further up the screen = drawn first); or an explicit `{ field,
    * descending? }` float offset into the record for a custom sort key.
    * Record slots stay stable - record i keeps meaning sprite i, and
-   * removeSprite still shifts - only the draw order changes. Ties keep
+   * destroySprite still shifts - only the draw order changes. Ties keep
    * record order, so an unset key draws exactly as before. Known
    * limitation: pick() resolves overlapping sprites by record order, not
    * visual order, when a key is set.
@@ -63,7 +63,7 @@ export type RecordLayer = LayerBase & {
    * is draw order - unless the layer was created with `orderBy`, which
    * draws in key order while record i keeps meaning sprite i. Write fields
    * directly for large per-frame populations, then call touch() once. Do
-   * not cache indices across removeSprite - records shift - and do not
+   * not cache indices across destroySprite - records shift - and do not
    * cache the array across addSprite - growth replaces it.
    */
   records: Float32Array
@@ -104,7 +104,7 @@ export function createRecordLayer(atlas: TextureId, opts?: RecordLayerOptions):
       : orderBy === "y"
         ? { field: Y_FIELD_OFFSET }
         : { field: orderBy.field, descending: orderBy.descending }
-  let gpu = createSpritePipeline(label, VERTEX, INSTANCE_ATTRIBUTES)
+  let gpu = createSpritePipeline(label, VERTEX, [INSTANCE_ATTRIBUTES])
 
   let disposed = false
   let dirty = false
@@ -132,7 +132,7 @@ export function createRecordLayer(atlas: TextureId, opts?: RecordLayerOptions):
     out.set(layer.records.subarray(0, count * FLOATS_PER_SPRITE))
     endBufferWrite(target, count * FLOATS_PER_SPRITE * 4)
     if (grown !== null) {
-      views.setBuffers({ instanceBuffer: grown })
+      views.setBuffers([grown])
       views.setCount(count)
       if (instanceOrder !== undefined) {
         // The growth publish above landed BEFORE the swap (the entry must
@@ -192,7 +192,7 @@ export function createRecordLayer(atlas: TextureId, opts?: RecordLayerOptions):
     pipeline: gpu.pipeline,
     quad: gpu.quad,
     atlas,
-    buffers: () => ({ instanceBuffer: records }),
+    buffers: () => [records],
     count: () => published,
     tint: () => tint,
     pick: (x, y) => layer.pick(x, y),
@@ -282,7 +282,7 @@ export function createRecordLayer(atlas: TextureId, opts?: RecordLayerOptions):
         visible: true,
       }
     },
-    _remove(sprite) {
+    _destroy(sprite) {
       // Later sprites shift down one draw slot (order preserved).
       sprite.layer = null
       let index = sprite._slot

package/src/shaders.ts

@@ -21,7 +21,7 @@
 // against oracles but NOT against these shaders - if you touch one
 // rotation, touch all.
 import { compileShader, createBuffer, createRenderPipeline, destroyBuffer, destroyProgram, destroyRenderPipeline, destroyShader, glsl, linkProgram } from "@solidrt/core/gpu"
-import type { BufferId, InstanceAttribute, RenderPipelineId, VertexAttribute } from "@solidrt/core/gpu"
+import type { BufferId, RenderPipelineId, VertexAttribute } from "@solidrt/core/gpu"
 
 export let VERTEX = glsl`
   in vec2 aPos;
@@ -84,11 +84,11 @@ export let FRAGMENT = glsl`
 
 /** The instance attribute list matching the 13-float record layout. */
 export const INSTANCE_ATTRIBUTES: VertexAttribute[] = [
-  { name: "iCenter", format: "vec2" },
-  { name: "iSize", format: "vec2" },
-  { name: "iUv", format: "vec4" },
-  { name: "iRot", format: "f32" },
-  { name: "iTint", format: "vec4" },
+  { name: "iCenter", format: "float32x2" },
+  { name: "iSize", format: "float32x2" },
+  { name: "iUv", format: "float32x4" },
+  { name: "iRot", format: "float32" },
+  { name: "iTint", format: "float32x4" },
 ]
 
 export let VERTEX_SPLIT = glsl`
@@ -119,15 +119,20 @@ export let VERTEX_SPLIT = glsl`
   }
 `
 
-/** The split layout: slot 0 the Pose2D record, slot 1 the style record
- * (iRenderOrder is layout-only - see the header note). */
-export const INSTANCE_ATTRIBUTES_SPLIT: InstanceAttribute[] = [
-  { name: "iPos", format: "vec2" },
-  { name: "iRot", format: "f32" },
-  { name: "iScale", format: "vec2" },
-  { name: "iUv", format: "vec4", slot: 1 },
-  { name: "iTint", format: "vec4", slot: 1 },
-  { name: "iRenderOrder", format: "f32", slot: 1 },
+/** The split layout: one instance buffer holding the Pose2D record, a
+ * second holding the style record (iRenderOrder is layout-only - see the
+ * header note). */
+export const INSTANCE_LAYOUTS_SPLIT: VertexAttribute[][] = [
+  [
+    { name: "iPos", format: "float32x2" },
+    { name: "iRot", format: "float32" },
+    { name: "iScale", format: "float32x2" },
+  ],
+  [
+    { name: "iUv", format: "float32x4" },
+    { name: "iTint", format: "float32x4" },
+    { name: "iRenderOrder", format: "float32" },
+  ],
 ]
 
 /** What a layer's targets draw with: the unit quad every instance reuses
@@ -142,7 +147,7 @@ export type SpritePipeline = { quad: BufferId; pipeline: RenderPipelineId; dispo
  * view - add entries over the one pipeline. The program lives as long as
  * the pipeline; `dispose` frees both and the quad.
  */
-export function createSpritePipeline(label: string, vertex: string, instanceAttributes: InstanceAttribute[]): SpritePipeline {
+export function createSpritePipeline(label: string, vertex: string, instanceLayouts: VertexAttribute[][]): SpritePipeline {
   // 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`,
@@ -156,8 +161,7 @@ export function createSpritePipeline(label: string, vertex: string, instanceAttr
   let pipeline = createRenderPipeline(program, {
     label,
     topology: "triangle-strip",
-    attributes: [{ name: "aPos", format: "vec2" }],
-    instanceAttributes,
+    buffers: [{ attributes: [{ name: "aPos", format: "float32x2" }] }, ...instanceLayouts.map(attributes => ({ stepMode: "instance" as const, attributes }))],
     blend: "alpha",
   })
   return {

package/src/tiles.ts

@@ -304,10 +304,10 @@ export function createTileLayer(
         label: `${label}-chunk`,
         topology: "triangle-strip",
         vertexCount: 4,
-        attributes: [{ name: "aPos", format: "vec2" }],
-        buffer: quad,
-        instanceAttributes: INSTANCE_ATTRIBUTES,
-        instanceBuffer: buffer,
+        buffers: [
+          { attributes: [{ name: "aPos", format: "float32x2" }], buffer: quad },
+          { stepMode: "instance", attributes: INSTANCE_ATTRIBUTES, buffer },
+        ],
         instanceCount: perChunk,
         blend: "alpha",
         textures: { uAtlas: atlas },