@aethervtt/shard-sprite 0.0.1

package/dist/occluders.d.ts

@@ -0,0 +1,64 @@
+import { ShardError } from '@aethervtt/shard-core';
+import type { TileLayer } from './tilemap.js';
+/**
+ * Occluder geometry. Every shape reduces to segments (ax, ay, bx, by), first in the occluder's
+ * local space, then in world space for the shadow pass. Pure functions: tested headless.
+ */
+/** Segments of a closed polygon (x, y pairs), appended to `out`. */
+export declare function polygonSegments(points: ArrayLike<number>, out: number[]): void;
+/** A w × h box centered on the origin, as a polygon. */
+export declare function boxPolygon(w: number, h: number, cx?: number, cy?: number): number[];
+/** Sides of a circle's polygon: its chord error is under 1% of the radius. */
+export declare const CIRCLE_SIDES = 24;
+export declare function circlePolygon(r: number, sides?: number): number[];
+/** A capsule along Y: two half circles `halfHeight` from the center, joined by straight sides. */
+export declare function capsulePolygon(r: number, halfHeight: number, sides?: number): number[];
+/** The convex hull of points (x, y pairs), counter-clockwise (monotone chain). */
+export declare function convexHull(points: ArrayLike<number>): number[];
+/**
+ * Why a polygon can't occlude, or undefined when it can: fewer than 3 points, no area, or two
+ * edges that cross.
+ */
+export declare function polygonProblem(points: ArrayLike<number>): string | undefined;
+export declare function invalidOccluder(message: string, path?: string): ShardError;
+/** The fields of LightOccluder2d a shape needs. */
+export interface OccluderShapeValue {
+    shape: 'box' | 'circle' | 'polygon' | 'sprite' | 'collider';
+    size: ArrayLike<number>;
+    points: ArrayLike<number>[];
+}
+/** The fields of physics/Collider an occluder reads (2D reads x and y). */
+export interface ColliderValue {
+    shape: string;
+    radius: number;
+    halfExtents: ArrayLike<number>;
+    halfHeight: number;
+    points: ArrayLike<number>[];
+}
+/**
+ * Local-space segments of an occluder. `sprite` takes the outline polygon the caller resolved
+ * from the sprite; `collider` the entity's Collider. Throws `sprite/invalid-occluder`.
+ */
+export declare function occluderSegments(value: OccluderShapeValue, extra?: {
+    outline?: ArrayLike<number>;
+    collider?: ColliderValue;
+}): number[];
+/**
+ * A sprite's outline in its local space: an atlas outline (normalized region coordinates, y down)
+ * placed by the sprite's size, anchor, and flips; without one, the sprite's rectangle.
+ */
+export declare function spriteOutline(outline: ArrayLike<number> | undefined, w: number, h: number, ax: number, ay: number, flipX: boolean, flipY: boolean): number[];
+/**
+ * Boundary edges of one chunk of an occluding tile layer, in tile units (tile (x, y) covers
+ * [x, x + 1] × [−y − 1, −y]), appended to `out`. A side is an edge when exactly one of its two
+ * cells is filled, counting cells outside the chunk as empty: edits only rebuild their chunk, and
+ * the extra edges on chunk borders sit inside walls where no light reaches them first. Collinear
+ * runs merge into one segment.
+ */
+export declare function tileChunkEdges(layer: Pick<TileLayer, 'tiles' | 'width' | 'height'>, chunkSize: number, chunk: number, out: number[]): void;
+/**
+ * Transforms local segments by an affine (3 × 4 rows, the entity's GlobalTransform) into world
+ * XY, writing `count` segments from `src` to `dst` at `offset` (in segments). Returns the world
+ * bounds in `bounds` (minX, minY, maxX, maxY).
+ */
+export declare function transformSegments(src: ArrayLike<number>, g: ArrayLike<number>, go: number, sx: number, sy: number, dst: Float32Array, offset: number, bounds: Float32Array): void;

package/dist/occluders.js

@@ -0,0 +1,241 @@
+import { ShardError } from "@aethervtt/shard-core";
+function polygonSegments(points, out) {
+  const n = points.length / 2;
+  for (let i = 0, j = n - 1; i < n; j = i++) {
+    out.push(points[j * 2], points[j * 2 + 1], points[i * 2], points[i * 2 + 1]);
+  }
+}
+function boxPolygon(w, h, cx = 0, cy = 0) {
+  const x = w / 2;
+  const y = h / 2;
+  return [cx - x, cy - y, cx + x, cy - y, cx + x, cy + y, cx - x, cy + y];
+}
+const CIRCLE_SIDES = 24;
+function circlePolygon(r, sides = CIRCLE_SIDES) {
+  const out = [];
+  for (let k = 0; k < sides; k++) {
+    const a = k / sides * Math.PI * 2;
+    out.push(Math.cos(a) * r, Math.sin(a) * r);
+  }
+  return out;
+}
+function capsulePolygon(r, halfHeight, sides = CIRCLE_SIDES) {
+  const out = [];
+  const half = sides / 2;
+  for (let k = 0; k <= half; k++) {
+    const a = k / half * Math.PI;
+    out.push(Math.cos(a) * r, halfHeight + Math.sin(a) * r);
+  }
+  for (let k = 0; k <= half; k++) {
+    const a = Math.PI + k / half * Math.PI;
+    out.push(Math.cos(a) * r, -halfHeight + Math.sin(a) * r);
+  }
+  return out;
+}
+function convexHull(points) {
+  const idx = Array.from({ length: points.length / 2 }, (_, i) => i).sort(
+    (a, b) => points[a * 2] - points[b * 2] || points[a * 2 + 1] - points[b * 2 + 1]
+  );
+  const cross = (o, a, b) => (points[a * 2] - points[o * 2]) * (points[b * 2 + 1] - points[o * 2 + 1]) - (points[a * 2 + 1] - points[o * 2 + 1]) * (points[b * 2] - points[o * 2]);
+  const lower = [];
+  for (const i of idx) {
+    while (lower.length >= 2 && cross(lower.at(-2), lower.at(-1), i) <= 0) lower.pop();
+    lower.push(i);
+  }
+  const upper = [];
+  for (let k = idx.length - 1; k >= 0; k--) {
+    const i = idx[k];
+    while (upper.length >= 2 && cross(upper.at(-2), upper.at(-1), i) <= 0) upper.pop();
+    upper.push(i);
+  }
+  const hull = lower.slice(0, -1).concat(upper.slice(0, -1));
+  const out = [];
+  for (const i of hull) out.push(points[i * 2], points[i * 2 + 1]);
+  return out;
+}
+function segmentsCross(ax, ay, bx, by, cx, cy, dx, dy) {
+  const d1 = (bx - ax) * (cy - ay) - (by - ay) * (cx - ax);
+  const d2 = (bx - ax) * (dy - ay) - (by - ay) * (dx - ax);
+  const d3 = (dx - cx) * (ay - cy) - (dy - cy) * (ax - cx);
+  const d4 = (dx - cx) * (by - cy) - (dy - cy) * (bx - cx);
+  return d1 * d2 < 0 && d3 * d4 < 0;
+}
+function polygonProblem(points) {
+  const n = points.length / 2;
+  if (n < 3) return `a polygon needs at least 3 points, not ${n}`;
+  for (let i = 0; i < n; i++) {
+    const i2 = (i + 1) % n;
+    for (let j = i + 2; j < n; j++) {
+      const j2 = (j + 1) % n;
+      if (j2 === i) continue;
+      if (segmentsCross(
+        points[i * 2],
+        points[i * 2 + 1],
+        points[i2 * 2],
+        points[i2 * 2 + 1],
+        points[j * 2],
+        points[j * 2 + 1],
+        points[j2 * 2],
+        points[j2 * 2 + 1]
+      )) {
+        return `edges ${i} and ${j} cross (self-intersecting)`;
+      }
+    }
+  }
+  let area = 0;
+  for (let i = 0, j = n - 1; i < n; j = i++) {
+    area += points[j * 2] * points[i * 2 + 1] - points[i * 2] * points[j * 2 + 1];
+  }
+  if (Math.abs(area) < 1e-9) return "the polygon has no area";
+  return void 0;
+}
+function invalidOccluder(message, path) {
+  return new ShardError("sprite/invalid-occluder", `Invalid LightOccluder2d: ${message}`, {
+    hint: "Give polygons 3+ points without crossing edges, boxes a nonzero size, and collider occluders a cuboid, ball, capsule, or convex Collider.",
+    path
+  });
+}
+function occluderSegments(value, extra = {}) {
+  const out = [];
+  switch (value.shape) {
+    case "box": {
+      const w = value.size[0];
+      const h = value.size[1];
+      if (!(w > 0 && h > 0)) throw invalidOccluder(`a box of size ${w} \xD7 ${h}`, "/size");
+      polygonSegments(boxPolygon(w, h), out);
+      break;
+    }
+    case "circle": {
+      const r = value.size[0];
+      if (!(r > 0)) throw invalidOccluder(`a circle of radius ${r}`, "/size");
+      polygonSegments(circlePolygon(r), out);
+      break;
+    }
+    case "polygon": {
+      const flat = [];
+      for (const p of value.points) flat.push(p[0], p[1]);
+      const problem = polygonProblem(flat);
+      if (problem) throw invalidOccluder(problem, "/points");
+      polygonSegments(flat, out);
+      break;
+    }
+    case "sprite": {
+      const o = extra.outline;
+      if (!o || o.length < 6) throw invalidOccluder("the sprite has no outline or size");
+      polygonSegments(o, out);
+      break;
+    }
+    case "collider": {
+      const c = extra.collider;
+      if (!c) throw invalidOccluder("shape 'collider' needs a physics/Collider on the entity");
+      if (c.shape === "cuboid") {
+        const w = c.halfExtents[0] * 2;
+        const h = c.halfExtents[1] * 2;
+        if (!(w > 0 && h > 0)) throw invalidOccluder(`a cuboid collider of size ${w} \xD7 ${h}`);
+        polygonSegments(boxPolygon(w, h), out);
+      } else if (c.shape === "ball") {
+        if (!(c.radius > 0)) throw invalidOccluder(`a ball collider of radius ${c.radius}`);
+        polygonSegments(circlePolygon(c.radius), out);
+      } else if (c.shape === "capsule") {
+        polygonSegments(capsulePolygon(c.radius, c.halfHeight), out);
+      } else if (c.shape === "convex") {
+        const flat = [];
+        for (const p of c.points) flat.push(p[0], p[1]);
+        const hull = convexHull(flat);
+        if (hull.length < 6) throw invalidOccluder("a convex collider with fewer than 3 points");
+        polygonSegments(hull, out);
+      } else {
+        throw invalidOccluder(
+          `a ${c.shape} collider (occluders support cuboid, ball, capsule, and convex)`
+        );
+      }
+      break;
+    }
+  }
+  return out;
+}
+function spriteOutline(outline, w, h, ax, ay, flipX, flipY) {
+  const src = outline && outline.length >= 6 ? outline : [0, 0, 1, 0, 1, 1, 0, 1];
+  const out = [];
+  for (let k = 0; k < src.length; k += 2) {
+    const u = flipX ? 1 - src[k] : src[k];
+    const v = flipY ? 1 - src[k + 1] : src[k + 1];
+    out.push((u - ax) * w, (ay - v) * h);
+  }
+  return out;
+}
+function tileChunkEdges(layer, chunkSize, chunk, out) {
+  const chunksX = Math.ceil(layer.width / chunkSize);
+  const x0 = chunk % chunksX * chunkSize;
+  const y0 = Math.floor(chunk / chunksX) * chunkSize;
+  const x1 = Math.min(layer.width, x0 + chunkSize);
+  const y1 = Math.min(layer.height, y0 + chunkSize);
+  const filled = (x, y) => x >= x0 && x < x1 && y >= y0 && y < y1 && layer.tiles[y * layer.width + x] !== 0;
+  for (let y = y0; y <= y1; y++) {
+    let start = -1;
+    for (let x = x0; x <= x1; x++) {
+      const edge = x < x1 && filled(x, y) !== filled(x, y - 1);
+      if (edge && start < 0) start = x;
+      else if (!edge && start >= 0) {
+        out.push(start, -y, x, -y);
+        start = -1;
+      }
+    }
+  }
+  for (let x = x0; x <= x1; x++) {
+    let start = -1;
+    for (let y = y0; y <= y1; y++) {
+      const edge = y < y1 && filled(x, y) !== filled(x - 1, y);
+      if (edge && start < 0) start = y;
+      else if (!edge && start >= 0) {
+        out.push(x, -start, x, -y);
+        start = -1;
+      }
+    }
+  }
+}
+function transformSegments(src, g, go, sx, sy, dst, offset, bounds) {
+  const n = src.length / 4;
+  let minX = Number.POSITIVE_INFINITY;
+  let minY = Number.POSITIVE_INFINITY;
+  let maxX = Number.NEGATIVE_INFINITY;
+  let maxY = Number.NEGATIVE_INFINITY;
+  const m0 = g[go];
+  const m1 = g[go + 1];
+  const m3 = g[go + 3];
+  const m4 = g[go + 4];
+  const m5 = g[go + 5];
+  const m7 = g[go + 7];
+  for (let s = 0; s < n; s++) {
+    for (let e = 0; e < 2; e++) {
+      const lx = src[s * 4 + e * 2] * sx;
+      const ly = src[s * 4 + e * 2 + 1] * sy;
+      const x = m0 * lx + m1 * ly + m3;
+      const y = m4 * lx + m5 * ly + m7;
+      dst[(offset + s) * 4 + e * 2] = x;
+      dst[(offset + s) * 4 + e * 2 + 1] = y;
+      if (x < minX) minX = x;
+      if (x > maxX) maxX = x;
+      if (y < minY) minY = y;
+      if (y > maxY) maxY = y;
+    }
+  }
+  bounds[0] = minX;
+  bounds[1] = minY;
+  bounds[2] = maxX;
+  bounds[3] = maxY;
+}
+export {
+  CIRCLE_SIDES,
+  boxPolygon,
+  capsulePolygon,
+  circlePolygon,
+  convexHull,
+  invalidOccluder,
+  occluderSegments,
+  polygonProblem,
+  polygonSegments,
+  spriteOutline,
+  tileChunkEdges,
+  transformSegments
+};

package/dist/outline.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Alpha outlines for `shape: 'sprite'` occluders: marching squares over a region's alpha at 0.5,
+ * the largest loop kept, simplified with Douglas–Peucker until it has at most `maxPoints` points.
+ * Runs in the atlas importer, so outlines cost nothing at runtime.
+ */
+/**
+ * Closed loops (x, y pairs in pixels, y down, pixel (x, y) spanning [x, x + 1]) where alpha crosses
+ * `threshold`, interpolated between pixel centers. `alpha(x, y)` is 0..1 and 0 outside the region.
+ */
+export declare function traceAlpha(width: number, height: number, alpha: (x: number, y: number) => number, threshold?: number): number[][];
+/** Signed area of a closed loop (x, y pairs). */
+export declare function loopArea(p: ArrayLike<number>): number;
+/** Distance from a point to a closed polygon's boundary. */
+export declare function distanceToLoop(x: number, y: number, p: ArrayLike<number>): number;
+/** Douglas–Peucker on a closed loop: every dropped point stays within `eps` of the result. */
+export declare function simplifyLoop(p: number[], eps: number): number[];
+/**
+ * A region's outline: the largest alpha loop, simplified to within `eps` texels, loosened until
+ * it has at most `maxPoints` points. Pixel coordinates (y down); empty when nothing is opaque.
+ */
+export declare function alphaOutline(width: number, height: number, alpha: (x: number, y: number) => number, options?: {
+    eps?: number;
+    maxPoints?: number;
+}): number[];

package/dist/outline.js

@@ -0,0 +1,183 @@
+const CASES = [
+  [],
+  [3, 2],
+  [2, 1],
+  [3, 1],
+  [0, 1],
+  [],
+  // saddle, resolved by the center
+  [0, 2],
+  [0, 3],
+  [0, 3],
+  [0, 2],
+  [],
+  // saddle
+  [0, 1],
+  [3, 1],
+  [2, 1],
+  [3, 2],
+  []
+];
+function traceAlpha(width, height, alpha, threshold = 0.5) {
+  const cw = width + 2;
+  const ch = height + 2;
+  const a = new Float32Array(cw * ch);
+  for (let y = 0; y < height; y++)
+    for (let x = 0; x < width; x++) a[(y + 1) * cw + x + 1] = alpha(x, y);
+  const inside = (i, j) => a[j * cw + i] >= threshold;
+  const px = /* @__PURE__ */ new Map();
+  const py = /* @__PURE__ */ new Map();
+  const nbr = /* @__PURE__ */ new Map();
+  const point = (id) => {
+    if (px.has(id)) return;
+    const k = id >> 1;
+    const i = k % cw;
+    const j = (k - i) / cw;
+    const i2 = id & 1 ? i : i + 1;
+    const j2 = id & 1 ? j + 1 : j;
+    const v0 = a[j * cw + i];
+    const v1 = a[j2 * cw + i2];
+    const t = v1 === v0 ? 0.5 : Math.min(1, Math.max(0, (threshold - v0) / (v1 - v0)));
+    px.set(id, i - 0.5 + (i2 - i) * t);
+    py.set(id, j - 0.5 + (j2 - j) * t);
+  };
+  const link = (p, q) => {
+    point(p);
+    point(q);
+    const l = nbr.get(p);
+    if (l) l.push(q);
+    else nbr.set(p, [q]);
+    const m = nbr.get(q);
+    if (m) m.push(p);
+    else nbr.set(q, [p]);
+  };
+  for (let j = 0; j < ch - 1; j++) {
+    for (let i = 0; i < cw - 1; i++) {
+      const c = (inside(i, j) ? 8 : 0) | (inside(i + 1, j) ? 4 : 0) | (inside(i + 1, j + 1) ? 2 : 0) | (inside(i, j + 1) ? 1 : 0);
+      if (c === 0 || c === 15) continue;
+      const e = [
+        (j * cw + i) * 2,
+        (j * cw + i + 1) * 2 + 1,
+        ((j + 1) * cw + i) * 2,
+        (j * cw + i) * 2 + 1
+      ];
+      if (c === 5 || c === 10) {
+        const center = (a[j * cw + i] + a[j * cw + i + 1] + a[(j + 1) * cw + i + 1] + a[(j + 1) * cw + i]) / 4 >= threshold;
+        const cutTlBr = c === 5 === center;
+        if (cutTlBr) {
+          link(e[0], e[3]);
+          link(e[2], e[1]);
+        } else {
+          link(e[0], e[1]);
+          link(e[3], e[2]);
+        }
+        continue;
+      }
+      const s = CASES[c];
+      link(e[s[0]], e[s[1]]);
+    }
+  }
+  const loops = [];
+  const done = /* @__PURE__ */ new Set();
+  for (const start of nbr.keys()) {
+    if (done.has(start)) continue;
+    const loop = [];
+    let cur = start;
+    while (cur !== void 0 && !done.has(cur)) {
+      done.add(cur);
+      loop.push(px.get(cur), py.get(cur));
+      const n = nbr.get(cur);
+      cur = !done.has(n[0]) ? n[0] : n[1];
+    }
+    if (loop.length >= 6) loops.push(loop);
+  }
+  return loops;
+}
+function loopArea(p) {
+  let s = 0;
+  const n = p.length / 2;
+  for (let i = 0, j = n - 1; i < n; j = i++)
+    s += p[j * 2] * p[i * 2 + 1] - p[i * 2] * p[j * 2 + 1];
+  return s / 2;
+}
+function segDist(px, py, ax, ay, bx, by) {
+  const dx = bx - ax;
+  const dy = by - ay;
+  const l2 = dx * dx + dy * dy;
+  const t = l2 > 0 ? Math.min(1, Math.max(0, ((px - ax) * dx + (py - ay) * dy) / l2)) : 0;
+  const x = ax + t * dx - px;
+  const y = ay + t * dy - py;
+  return Math.sqrt(x * x + y * y);
+}
+function distanceToLoop(x, y, p) {
+  let best = Number.POSITIVE_INFINITY;
+  const n = p.length / 2;
+  for (let i = 0, j = n - 1; i < n; j = i++) {
+    best = Math.min(best, segDist(x, y, p[j * 2], p[j * 2 + 1], p[i * 2], p[i * 2 + 1]));
+  }
+  return best;
+}
+function dp(p, first, last, eps, keep) {
+  let worst = -1;
+  let at = -1;
+  const n = p.length / 2;
+  const ax = p[first * 2];
+  const ay = p[first * 2 + 1];
+  const bx = p[last % n * 2];
+  const by = p[last % n * 2 + 1];
+  for (let k = first + 1; k < last; k++) {
+    const d = segDist(p[k * 2], p[k * 2 + 1], ax, ay, bx, by);
+    if (d > worst) {
+      worst = d;
+      at = k;
+    }
+  }
+  if (worst > eps) {
+    keep[at] = 1;
+    dp(p, first, at, eps, keep);
+    dp(p, at, last, eps, keep);
+  }
+}
+function simplifyLoop(p, eps) {
+  const n = p.length / 2;
+  if (n <= 3) return p.slice();
+  let far = 0;
+  let fd = -1;
+  for (let k = 1; k < n; k++) {
+    const dx = p[k * 2] - p[0];
+    const dy = p[k * 2 + 1] - p[1];
+    if (dx * dx + dy * dy > fd) {
+      fd = dx * dx + dy * dy;
+      far = k;
+    }
+  }
+  const keep = new Uint8Array(n);
+  keep[0] = 1;
+  keep[far] = 1;
+  dp(p, 0, far, eps, keep);
+  dp(p, far, n, eps, keep);
+  const out = [];
+  for (let k = 0; k < n; k++) if (keep[k]) out.push(p[k * 2], p[k * 2 + 1]);
+  return out;
+}
+function alphaOutline(width, height, alpha, options = {}) {
+  const loops = traceAlpha(width, height, alpha);
+  if (loops.length === 0) return [];
+  let best = loops[0];
+  for (const l of loops) if (Math.abs(loopArea(l)) > Math.abs(loopArea(best))) best = l;
+  const maxPoints = options.maxPoints ?? 32;
+  let eps = options.eps ?? 0.5;
+  let out = simplifyLoop(best, eps);
+  while (out.length / 2 > maxPoints) {
+    eps *= 1.25;
+    out = simplifyLoop(best, eps);
+  }
+  return out;
+}
+export {
+  alphaOutline,
+  distanceToLoop,
+  loopArea,
+  simplifyLoop,
+  traceAlpha
+};

package/dist/plugin.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Sprites, atlases, frame animation, and tilemaps, drawn in the render graph: world sprites after
+ * opaque 3D (so 2D gets HDR and post-processing), screen sprites over the finished image. Cameras
+ * with Lighting2d light them with 2D lights and shadows.
+ */
+export declare const spritePlugin: import("@aethervtt/shard-runtime").Plugin;

package/dist/plugin.js

@@ -0,0 +1,67 @@
+import { Last, Update } from "@aethervtt/shard-core";
+import { Gpu, Graph, Picking, RenderDescribers, RenderSet, Shaders } from "@aethervtt/shard-render";
+import { definePlugin } from "@aethervtt/shard-runtime";
+import * as atlasModule from "./atlas.js";
+import { TextureAtlases } from "./atlas.js";
+import * as clipModule from "./clip.js";
+import { animateSprites, SpriteClips } from "./clip.js";
+import * as lightingModule from "./lighting.js";
+import * as lights2dModule from "./lights2d.js";
+import { lights2dNode, prepareLights2d } from "./lights2d.js";
+import * as renderModule from "./render.js";
+import {
+  describeSprites,
+  drawSpritePicks,
+  observeSpriteRemovals,
+  overlayNode,
+  prepareSprites,
+  SpriteStore,
+  Sprites,
+  spriteNode,
+  Tilemaps
+} from "./render.js";
+import { SPRITE_SHADERS } from "./shaders.js";
+import * as spriteModule from "./sprite.js";
+import { Sprite2dSettings } from "./sprite.js";
+import * as tilemapModule from "./tilemap.js";
+import { TilemapDatas } from "./tilemap.js";
+const spritePlugin = definePlugin({
+  name: "sprite",
+  provides: [
+    atlasModule,
+    clipModule,
+    lightingModule,
+    lights2dModule,
+    renderModule,
+    spriteModule,
+    tilemapModule
+  ],
+  dependencies: ["render/forward"],
+  build(app) {
+    const w = app.world;
+    w.initResource(TextureAtlases);
+    w.initResource(SpriteClips);
+    w.initResource(TilemapDatas);
+    w.initResource(Sprite2dSettings);
+    w.initResource(Tilemaps);
+    observeSpriteRemovals(w);
+    app.addSystems(Update, animateSprites).addSystems(Last, prepareSprites.inSet(RenderSet.Prepare)).addSystems(Last, prepareLights2d.inSet(RenderSet.Prepare));
+  },
+  ready(app) {
+    const world = app.world;
+    app.insertResource(Sprites, new SpriteStore(world.resource(Gpu)));
+    const shaders = world.resource(Shaders);
+    for (const [path, source] of Object.entries(SPRITE_SHADERS)) {
+      shaders.register(path, source, `engine:${path}`);
+    }
+    const graph = world.resource(Graph);
+    graph.addNode("sprites/lights2d", lights2dNode(world));
+    graph.addNode("sprites", spriteNode(world));
+    graph.addNode("sprites/overlay", overlayNode(world));
+    world.initResource(RenderDescribers).set("sprites", (w) => describeSprites(w));
+    world.initResource(Picking).drawers.set("sprites", drawSpritePicks);
+  }
+});
+export {
+  spritePlugin
+};

package/dist/preview.d.ts

@@ -0,0 +1,9 @@
+import type { PreviewImage } from '@aethervtt/shard-assets';
+/** Nearest-neighbour fit of RGBA8 pixels into width × height, keeping the aspect ratio. */
+export declare function fitImage(src: Uint8Array, sw: number, sh: number, width: number, height: number): PreviewImage;
+/** A one-pixel rectangle outline. */
+export declare function outline(image: PreviewImage, x: number, y: number, w: number, h: number, color: readonly number[]): void;
+/** A one-pixel line (DDA). */
+export declare function drawLine(image: PreviewImage, x0: number, y0: number, x1: number, y1: number, color: readonly number[]): void;
+/** Draws a number in a 3×5 pixel font, white on a black box so it reads on any image. */
+export declare function drawLabel(image: PreviewImage, text: string, x: number, y: number): void;

package/dist/preview.js

@@ -0,0 +1,71 @@
+function fitImage(src, sw, sh, width, height) {
+  const scale = Math.min(width / sw, height / sh);
+  const w = Math.max(1, Math.round(sw * scale));
+  const h = Math.max(1, Math.round(sh * scale));
+  const out = new Uint8Array(w * h * 4);
+  for (let y = 0; y < h; y++) {
+    const sy = Math.min(sh - 1, Math.floor(y / scale));
+    for (let x = 0; x < w; x++) {
+      const sx = Math.min(sw - 1, Math.floor(x / scale));
+      out.set(src.subarray((sy * sw + sx) * 4, (sy * sw + sx) * 4 + 4), (y * w + x) * 4);
+    }
+  }
+  return { width: w, height: h, data: out };
+}
+function put(image, x, y, c) {
+  if (x < 0 || y < 0 || x >= image.width || y >= image.height) return;
+  image.data.set(c, (y * image.width + x) * 4);
+}
+function outline(image, x, y, w, h, color) {
+  const x0 = Math.round(x);
+  const y0 = Math.round(y);
+  const x1 = Math.round(x + w) - 1;
+  const y1 = Math.round(y + h) - 1;
+  for (let i = x0; i <= x1; i++) {
+    put(image, i, y0, color);
+    put(image, i, y1, color);
+  }
+  for (let j = y0; j <= y1; j++) {
+    put(image, x0, j, color);
+    put(image, x1, j, color);
+  }
+}
+function drawLine(image, x0, y0, x1, y1, color) {
+  const steps = Math.max(1, Math.ceil(Math.max(Math.abs(x1 - x0), Math.abs(y1 - y0))));
+  for (let k = 0; k <= steps; k++) {
+    const t = k / steps;
+    put(image, Math.floor(x0 + (x1 - x0) * t), Math.floor(y0 + (y1 - y0) * t), color);
+  }
+}
+const DIGITS = [
+  [7, 5, 5, 5, 7],
+  [2, 6, 2, 2, 7],
+  [7, 1, 7, 4, 7],
+  [7, 1, 3, 1, 7],
+  [5, 5, 7, 1, 1],
+  [7, 4, 7, 1, 7],
+  [7, 4, 7, 5, 7],
+  [7, 1, 1, 2, 2],
+  [7, 5, 7, 5, 7],
+  [7, 5, 7, 1, 7]
+];
+function drawLabel(image, text, x, y) {
+  const w = text.length * 4 + 1;
+  for (let j = -1; j < 6; j++) for (let i = -1; i < w; i++) put(image, x + i, y + j, [0, 0, 0, 255]);
+  for (let k = 0; k < text.length; k++) {
+    const glyph = DIGITS[text.charCodeAt(k) - 48];
+    if (!glyph) continue;
+    for (let row = 0; row < 5; row++) {
+      for (let col = 0; col < 3; col++) {
+        if (glyph[row] >> 2 - col & 1)
+          put(image, x + k * 4 + col, y + row, [255, 255, 255, 255]);
+      }
+    }
+  }
+}
+export {
+  drawLabel,
+  drawLine,
+  fitImage,
+  outline
+};