@aethervtt/shard-render 0.0.1

package/dist/picking.js

@@ -0,0 +1,456 @@
+import { defineResource, mat4, ShardError } from "@aethervtt/shard-core";
+import { GlobalTransform } from "@aethervtt/shard-transform";
+import { Meshes } from "./assets.js";
+import { drawMaterials, ForwardStateResource, PASS_PICK } from "./forward.js";
+import { RenderPhase } from "./graph.js";
+import { Lod, Mesh3d } from "./instances.js";
+import { DebugOverlays } from "./overlays.js";
+import { Graph, Views } from "./plugin.js";
+import { cameraOf } from "./view.js";
+import { ComputedVisibility } from "./visibility.js";
+const Picking = defineResource("render/Picking", {
+  description: "GPU picking: pending pick requests per view, and extra pick drawers (sprites).",
+  init: () => ({
+    pending: /* @__PURE__ */ new Map(),
+    drawers: /* @__PURE__ */ new Map(),
+    blockers: /* @__PURE__ */ new Map(),
+    incomplete: /* @__PURE__ */ new Set()
+  })
+});
+function primaryView(world) {
+  let best;
+  for (const view of world.resource(Views).list) {
+    if (!cameraOf(view)) continue;
+    if (!best || view.order < best.order) best = view;
+  }
+  return best;
+}
+function pick(world, camera, x, y) {
+  const name = camera !== void 0 ? `camera:${camera}` : primaryView(world)?.name;
+  if (!name) {
+    return Promise.reject(
+      new ShardError("render/no-view", "Nothing to pick from: no camera renders to a target", {
+        hint: "Spawn an entity with Camera3d, or pass the camera to pick from."
+      })
+    );
+  }
+  const picking = world.resource(Picking);
+  for (const blocked of picking.blockers.values()) {
+    if (blocked(world, name, x, y)) return Promise.resolve(void 0);
+  }
+  return new Promise((resolve, reject) => {
+    let list = picking.pending.get(name);
+    if (!list) {
+      list = [];
+      picking.pending.set(name, list);
+    }
+    list.push({ x, y, resolve, reject });
+  });
+}
+function pickNode(world) {
+  const picking = world.resource(Picking);
+  return {
+    kind: "render",
+    phase: RenderPhase.Debug,
+    enabled: (view) => cameraOf(view) !== void 0 && (picking.pending.get(view.name)?.length ?? 0) > 0,
+    reads: ["culled"],
+    writes: ["pick-id", "pick-normal", "pick-depth"],
+    color: [
+      { resource: "pick-id", clear: { r: 0, g: 0, b: 0, a: 0 } },
+      { resource: "pick-normal", clear: { r: 0, g: 0, b: 0, a: 0 } }
+    ],
+    depth: { resource: "pick-depth", clear: 0 },
+    run: (ctx) => {
+      const cam = cameraOf(ctx.view);
+      const state = ctx.world.resource(ForwardStateResource);
+      const pv = state.views.get(ctx.view.name);
+      if (!pv) return;
+      const skipped = ctx.gpu.pipelines.skipped;
+      drawMaterials(ctx, state, pv, cam, cam.draws, PASS_PICK);
+      if (cam.deferred) drawMaterials(ctx, state, pv, cam, cam.forwardOnly, PASS_PICK);
+      drawMaterials(ctx, state, pv, cam, cam.transparent, PASS_PICK);
+      for (const draw of picking.drawers.values()) draw(ctx, cam);
+      if (ctx.gpu.pipelines.skipped > skipped) picking.incomplete.add(ctx.view.name);
+    }
+  };
+}
+const inv = new Float32Array(16);
+function pickReadbackNode(world) {
+  const picking = world.resource(Picking);
+  return {
+    kind: "raw",
+    phase: RenderPhase.Debug + 1,
+    enabled: (view) => cameraOf(view) !== void 0 && (picking.pending.get(view.name)?.length ?? 0) > 0,
+    reads: ["pick-id", "pick-normal"],
+    sideEffects: true,
+    run: (ctx) => {
+      const requests = picking.pending.get(ctx.view.name);
+      if (!requests || requests.length === 0) return;
+      if (picking.incomplete.delete(ctx.view.name)) return;
+      picking.pending.set(ctx.view.name, []);
+      const cam = cameraOf(ctx.view);
+      const device = ctx.gpu.device;
+      const id = ctx.texture("pick-id");
+      const normal = ctx.texture("pick-normal");
+      const buffer = device.createBuffer({
+        label: "pick/readback",
+        size: requests.length * 512,
+        usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ
+      });
+      const width = id.width;
+      const height = id.height;
+      const sx = width / ctx.view.target.width;
+      const sy = height / ctx.view.target.height;
+      requests.forEach((r, i) => {
+        const x = Math.min(width - 1, Math.max(0, Math.floor(r.x * sx)));
+        const y = Math.min(height - 1, Math.max(0, Math.floor(r.y * sy)));
+        const origin = { x, y };
+        ctx.encoder.copyTextureToBuffer(
+          { texture: id, origin },
+          { buffer, offset: i * 512, bytesPerRow: 256 },
+          [1, 1]
+        );
+        ctx.encoder.copyTextureToBuffer(
+          { texture: normal, origin },
+          { buffer, offset: i * 512 + 256, bytesPerRow: 256 },
+          [1, 1]
+        );
+      });
+      if (!mat4.invert(inv, cam.viewProjNoJitter)) inv.fill(0);
+      const unproject = new Float32Array(inv);
+      const eye = Float32Array.from(cam.position);
+      const name = ctx.world.resource(DebugOverlays).name;
+      const w = ctx.world;
+      ctx.afterSubmit(() => {
+        buffer.mapAsync(GPUMapMode.READ).then(
+          () => {
+            const bytes = buffer.getMappedRange();
+            requests.forEach((r, i) => {
+              const entity = new Uint32Array(bytes, i * 512, 1)[0];
+              const n = new Float32Array(bytes, i * 512 + 256, 4);
+              const d = n[3];
+              if (!(d > 0)) {
+                r.resolve(void 0);
+                return;
+              }
+              const px = Math.min(width - 1, Math.max(0, Math.floor(r.x * sx))) + 0.5;
+              const py = Math.min(height - 1, Math.max(0, Math.floor(r.y * sy))) + 0.5;
+              const nx = px / width * 2 - 1;
+              const ny = 1 - py / height * 2;
+              const m = unproject;
+              const hw = m[3] * nx + m[7] * ny + m[11] * d + m[15];
+              const position = [
+                (m[0] * nx + m[4] * ny + m[8] * d + m[12]) / hw,
+                (m[1] * nx + m[5] * ny + m[9] * d + m[13]) / hw,
+                (m[2] * nx + m[6] * ny + m[10] * d + m[14]) / hw
+              ];
+              const dx = position[0] - eye[0];
+              const dy = position[1] - eye[1];
+              const dz = position[2] - eye[2];
+              r.resolve({
+                entity,
+                path: w.isAlive(entity) ? name(w, entity) : void 0,
+                position,
+                normal: [n[0], n[1], n[2]],
+                distance: Math.sqrt(dx * dx + dy * dy + dz * dz)
+              });
+            });
+            buffer.unmap();
+            buffer.destroy();
+          },
+          (error) => {
+            for (const r of requests) r.reject(error);
+            buffer.destroy();
+          }
+        );
+      });
+    }
+  };
+}
+function addPickNodes(world) {
+  const graph = world.resource(Graph);
+  const usage = GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC;
+  graph.declare({ name: "pick-id", format: "r32uint", usage });
+  graph.declare({ name: "pick-normal", format: "rgba32float", usage });
+  graph.declare({ name: "pick-depth", format: "depth32float" });
+  graph.addNode("picking", pickNode(world));
+  graph.addNode("picking/readback", pickReadbackNode(world));
+}
+const BvhResource = defineResource("render/RaycastBvh", {
+  description: "The CPU raycast acceleration structure.",
+  init: () => ({ bvh: void 0 })
+});
+function meshOf(world, entity) {
+  const meshes = world.tryResource(Meshes);
+  if (!meshes) return void 0;
+  const lod = world.tryGet(entity, Lod);
+  const ref = lod?.levels[0]?.mesh ?? world.get(entity, Mesh3d).mesh;
+  return ref ? meshes.get(ref) : void 0;
+}
+function invertAffine(m, out) {
+  const a = m[0];
+  const b = m[1];
+  const c = m[2];
+  const tx = m[3];
+  const d = m[4];
+  const e = m[5];
+  const f = m[6];
+  const ty = m[7];
+  const g = m[8];
+  const h = m[9];
+  const i = m[10];
+  const tz = m[11];
+  const A = e * i - f * h;
+  const B = -(d * i - f * g);
+  const C = d * h - e * g;
+  const det = a * A + b * B + c * C;
+  const s = det !== 0 ? 1 / det : 0;
+  out[0] = A * s;
+  out[1] = -(b * i - c * h) * s;
+  out[2] = (b * f - c * e) * s;
+  out[4] = B * s;
+  out[5] = (a * i - c * g) * s;
+  out[6] = -(a * f - c * d) * s;
+  out[8] = C * s;
+  out[9] = -(a * h - b * g) * s;
+  out[10] = (a * e - b * d) * s;
+  out[3] = -(out[0] * tx + out[1] * ty + out[2] * tz);
+  out[7] = -(out[4] * tx + out[5] * ty + out[6] * tz);
+  out[11] = -(out[8] * tx + out[9] * ty + out[10] * tz);
+}
+function worldBox(bb, m, out) {
+  for (let r = 0; r < 3; r++) {
+    const o = r * 4;
+    let lo2 = m[o + 3];
+    let hi = m[o + 3];
+    for (let k = 0; k < 3; k++) {
+      const x = m[o + k] * bb[k];
+      const y = m[o + k] * bb[k + 3];
+      lo2 += Math.min(x, y);
+      hi += Math.max(x, y);
+    }
+    out[r] = lo2;
+    out[r + 3] = hi;
+  }
+}
+function buildBvh(world, tick, tables) {
+  const items = [];
+  for (const table of world.query({ with: [Mesh3d, GlobalTransform, ComputedVisibility] }).tables) {
+    const g = table.column(GlobalTransform, "matrix");
+    const vis = table.column(ComputedVisibility, "visible");
+    for (let i = 0; i < table.count; i++) {
+      if (!vis[i]) continue;
+      const entity = table.entities[i];
+      const mesh = meshOf(world, entity);
+      if (!mesh) continue;
+      const m = g.slice(i * 12, i * 12 + 12);
+      const inverse = new Float32Array(12);
+      invertAffine(m, inverse);
+      const box = new Float32Array(6);
+      worldBox(mesh.bounds, m, box);
+      items.push({ entity, mesh, m, inv: inverse, box });
+    }
+  }
+  const n = Math.max(1, items.length);
+  const boxes = new Float32Array(n * 2 * 6);
+  const nodes = new Int32Array(n * 2 * 3);
+  const order = new Int32Array(items.length).map((_, i) => i);
+  let count = 0;
+  const build = (start, end) => {
+    const node = count++;
+    const b = boxes.subarray(node * 6, node * 6 + 6);
+    b.set([Infinity, Infinity, Infinity, -Infinity, -Infinity, -Infinity]);
+    for (let k = start; k < end; k++) {
+      const ib = items[order[k]].box;
+      for (let a = 0; a < 3; a++) {
+        if (ib[a] < b[a]) b[a] = ib[a];
+        if (ib[a + 3] > b[a + 3]) b[a + 3] = ib[a + 3];
+      }
+    }
+    if (end - start <= 4) {
+      nodes[node * 3] = start;
+      nodes[node * 3 + 2] = end - start;
+      return node;
+    }
+    let axis = 0;
+    for (let a = 1; a < 3; a++) if (b[a + 3] - b[a] > b[axis + 3] - b[axis]) axis = a;
+    const part = Array.from(order.subarray(start, end)).sort(
+      (p, q) => items[p].box[axis] + items[p].box[axis + 3] - (items[q].box[axis] + items[q].box[axis + 3])
+    );
+    order.set(part, start);
+    const mid = start + end >> 1;
+    const left = build(start, mid);
+    const right = build(mid, end);
+    nodes[node * 3] = left;
+    nodes[node * 3 + 1] = right;
+    nodes[node * 3 + 2] = 0;
+    return node;
+  };
+  if (items.length > 0) build(0, items.length);
+  return { items, boxes, nodes, order, count, tick, tables };
+}
+function bvhOf(world) {
+  const r = world.initResource(BvhResource);
+  const q = world.query({ with: [Mesh3d, GlobalTransform, ComputedVisibility] });
+  let tick = 0;
+  for (const table of q.tables) {
+    tick = Math.max(
+      tick,
+      table.lastStructural,
+      table.lastChanged(GlobalTransform),
+      table.lastChanged(Mesh3d),
+      table.lastChanged(ComputedVisibility)
+    );
+  }
+  const cur = r.bvh;
+  if (!cur || cur.tick !== tick || cur.tables !== q.tables.length)
+    r.bvh = buildBvh(world, tick, q.tables.length);
+  return r.bvh;
+}
+function slabs(o, d, b, max) {
+  let t0 = 0;
+  let t1 = max;
+  for (let a = 0; a < 3; a++) {
+    const inv2 = 1 / d[a];
+    let near = (b[a] - o[a]) * inv2;
+    let far = (b[a + 3] - o[a]) * inv2;
+    if (near > far) {
+      const t = near;
+      near = far;
+      far = t;
+    }
+    if (Number.isNaN(near)) near = -Infinity;
+    if (Number.isNaN(far)) far = Infinity;
+    if (near > t0) t0 = near;
+    if (far < t1) t1 = far;
+    if (t0 > t1) return -1;
+  }
+  return t0;
+}
+const lo = new Float64Array(3);
+const ld = new Float64Array(3);
+const ln = new Float64Array(3);
+function intersectMesh(mesh, max) {
+  const p = mesh.positions;
+  const idx = mesh.indices;
+  const tris = idx ? idx.length / 3 : p.length / 9;
+  let best = -1;
+  for (let t = 0; t < tris; t++) {
+    const i0 = (idx ? idx[t * 3] : t * 3) * 3;
+    const i1 = (idx ? idx[t * 3 + 1] : t * 3 + 1) * 3;
+    const i2 = (idx ? idx[t * 3 + 2] : t * 3 + 2) * 3;
+    const e1x = p[i1] - p[i0];
+    const e1y = p[i1 + 1] - p[i0 + 1];
+    const e1z = p[i1 + 2] - p[i0 + 2];
+    const e2x = p[i2] - p[i0];
+    const e2y = p[i2 + 1] - p[i0 + 1];
+    const e2z = p[i2 + 2] - p[i0 + 2];
+    const px = ld[1] * e2z - ld[2] * e2y;
+    const py = ld[2] * e2x - ld[0] * e2z;
+    const pz = ld[0] * e2y - ld[1] * e2x;
+    const det = e1x * px + e1y * py + e1z * pz;
+    if (Math.abs(det) < 1e-12) continue;
+    const invDet = 1 / det;
+    const sx = lo[0] - p[i0];
+    const sy = lo[1] - p[i0 + 1];
+    const sz = lo[2] - p[i0 + 2];
+    const u = (sx * px + sy * py + sz * pz) * invDet;
+    if (u < 0 || u > 1) continue;
+    const qx = sy * e1z - sz * e1y;
+    const qy = sz * e1x - sx * e1z;
+    const qz = sx * e1y - sy * e1x;
+    const v = (ld[0] * qx + ld[1] * qy + ld[2] * qz) * invDet;
+    if (v < 0 || u + v > 1) continue;
+    const dist = (e2x * qx + e2y * qy + e2z * qz) * invDet;
+    if (dist < 0 || dist > max || best >= 0 && dist >= best) continue;
+    best = dist;
+    ln[0] = e1y * e2z - e1z * e2y;
+    ln[1] = e1z * e2x - e1x * e2z;
+    ln[2] = e1x * e2y - e1y * e2x;
+  }
+  return best;
+}
+function intersectLocalBox(bb, max) {
+  const t = slabs(lo, ld, bb, max);
+  if (t < 0) return -1;
+  let axis = 0;
+  let bestGap = Infinity;
+  for (let a = 0; a < 3; a++) {
+    const p = lo[a] + ld[a] * t;
+    const gap = Math.min(Math.abs(p - bb[a]), Math.abs(p - bb[a + 3]));
+    if (gap < bestGap) {
+      bestGap = gap;
+      axis = a;
+    }
+  }
+  ln[0] = ln[1] = ln[2] = 0;
+  ln[axis] = ld[axis] > 0 ? -1 : 1;
+  return t;
+}
+function raycast(world, origin, direction, options = {}) {
+  const dl = Math.sqrt(direction[0] ** 2 + direction[1] ** 2 + direction[2] ** 2);
+  if (dl === 0) return [];
+  const d = [direction[0] / dl, direction[1] / dl, direction[2] / dl];
+  const max = options.maxDistance ?? Infinity;
+  const bvh = bvhOf(world);
+  const name = world.tryResource(DebugOverlays)?.name;
+  const hits = [];
+  let nearest = max;
+  const stack = [0];
+  while (stack.length > 0 && bvh.items.length > 0) {
+    const node = stack.pop();
+    const limit = options.all ? max : nearest;
+    if (slabs(origin, d, bvh.boxes.subarray(node * 6, node * 6 + 6), limit) < 0) continue;
+    const count = bvh.nodes[node * 3 + 2];
+    if (count === 0) {
+      stack.push(bvh.nodes[node * 3], bvh.nodes[node * 3 + 1]);
+      continue;
+    }
+    const first = bvh.nodes[node * 3];
+    for (let k = first; k < first + count; k++) {
+      const item = bvh.items[bvh.order[k]];
+      if (slabs(origin, d, item.box, options.all ? max : nearest) < 0) continue;
+      const iv = item.inv;
+      for (let r = 0; r < 3; r++) {
+        lo[r] = iv[r * 4] * origin[0] + iv[r * 4 + 1] * origin[1] + iv[r * 4 + 2] * origin[2] + iv[r * 4 + 3];
+        ld[r] = iv[r * 4] * d[0] + iv[r * 4 + 1] * d[1] + iv[r * 4 + 2] * d[2];
+      }
+      const limit2 = options.all ? max : nearest;
+      const cpu = !options.boundsOnly && item.mesh.positions?.length > 0;
+      const t = cpu ? intersectMesh(item.mesh, limit2) : intersectLocalBox(item.mesh.bounds, limit2);
+      if (t < 0) continue;
+      let nx = iv[0] * ln[0] + iv[4] * ln[1] + iv[8] * ln[2];
+      let ny = iv[1] * ln[0] + iv[5] * ln[1] + iv[9] * ln[2];
+      let nz = iv[2] * ln[0] + iv[6] * ln[1] + iv[10] * ln[2];
+      const nl = Math.sqrt(nx * nx + ny * ny + nz * nz) || 1;
+      nx /= nl;
+      ny /= nl;
+      nz /= nl;
+      if (nx * d[0] + ny * d[1] + nz * d[2] > 0) {
+        nx = -nx;
+        ny = -ny;
+        nz = -nz;
+      }
+      hits.push({
+        entity: item.entity,
+        path: name?.(world, item.entity),
+        position: [origin[0] + d[0] * t, origin[1] + d[1] * t, origin[2] + d[2] * t],
+        normal: [nx, ny, nz],
+        distance: t
+      });
+      if (t < nearest) nearest = t;
+    }
+  }
+  hits.sort((a, b) => a.distance - b.distance);
+  return options.all ? hits : hits.slice(0, 1);
+}
+export {
+  BvhResource,
+  Picking,
+  addPickNodes,
+  pick,
+  pickNode,
+  pickReadbackNode,
+  primaryView,
+  raycast
+};

package/dist/pixel-perfect-plugin.d.ts

@@ -0,0 +1,9 @@
+import type { NodeDescriptor } from './graph.js';
+export declare const PIXEL_PERFECT_SHADERS: Record<string, string>;
+/** Draws a PixelPerfect camera's image onto its real target, scaled by a whole number. */
+export declare function pixelUpscaleNode(): NodeDescriptor;
+/**
+ * Pixel-perfect cameras (spec 0045): PixelPerfect renders at one texel per pixel and scales up by a
+ * whole number. Without it, PixelPerfect cameras render at full resolution.
+ */
+export declare const pixelPerfectPlugin: import("@aethervtt/shard-runtime").Plugin;

package/dist/pixel-perfect-plugin.js

@@ -0,0 +1,135 @@
+import { definePlugin } from "@aethervtt/shard-runtime";
+import { RenderPhase } from "./graph.js";
+import { PixelPerfectPath } from "./pixel-perfect.js";
+import { Graph, Shaders } from "./plugin.js";
+import { registerShaders } from "./shaders.js";
+const PIXEL_PERFECT_SHADERS = {
+  "shard::post::pixel_upscale": `
+struct Upscale {
+  /** offset (xy), scale, 0. */
+  params: vec4f,
+}
+
+@group(0) @binding(0) var source: texture_2d<f32>;
+@group(0) @binding(1) var<uniform> upscale: Upscale;
+
+/** Each texel becomes a scale \xD7 scale block; outside the image, black bars. */
+@fragment fn fs(@builtin(position) frag: vec4f) -> @location(0) vec4f {
+  let p = (frag.xy - upscale.params.xy) / upscale.params.z;
+  let size = vec2f(textureDimensions(source));
+  if (any(p < vec2f(0.0)) || any(p >= size)) { return vec4f(0.0, 0.0, 0.0, 1.0); }
+  return textureLoad(source, vec2i(floor(p)), 0);
+}`
+};
+const layoutKey = /* @__PURE__ */ new WeakMap();
+function pixelUpscaleNode() {
+  const buffers = /* @__PURE__ */ new Map();
+  const groups = /* @__PURE__ */ new Map();
+  const pipelines = /* @__PURE__ */ new Map();
+  const params = new Float32Array(4);
+  let generation = -1;
+  return {
+    kind: "render",
+    phase: RenderPhase.Display,
+    enabled: (view) => view.data.upscale !== void 0,
+    writes: ["view-target"],
+    color: [{ resource: "view-target", clear: { r: 0, g: 0, b: 0, a: 1 } }],
+    run: (ctx) => {
+      const gpu = ctx.gpu;
+      if (generation !== gpu.generation) {
+        generation = gpu.generation;
+        buffers.clear();
+        groups.clear();
+        pipelines.clear();
+      }
+      const layout = ctx.view.data.upscale;
+      const shaders = ctx.world.resource(Shaders);
+      const fs = shaders.module(gpu, { root: "shard::post::pixel_upscale" });
+      const vs = shaders.module(gpu, { root: "shard::fullscreen" });
+      if (!fs || !vs) {
+        gpu.pipelines.skipped++;
+        return;
+      }
+      let bindLayout = layoutKey.get(gpu.device);
+      if (!bindLayout) {
+        bindLayout = gpu.layouts.bindGroupLayout({
+          label: "pixel-upscale",
+          entries: [
+            {
+              binding: 0,
+              visibility: GPUShaderStage.FRAGMENT,
+              texture: { sampleType: "unfilterable-float" }
+            },
+            { binding: 1, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } }
+          ]
+        });
+        layoutKey.set(gpu.device, bindLayout);
+      }
+      const format = ctx.texture("view-target").format;
+      let pipeline = pipelines.get(format);
+      if (!pipeline) {
+        pipeline = gpu.pipelines.render({
+          label: `pixel-upscale/${format}`,
+          layout: gpu.layouts.pipelineLayout({
+            label: "pixel-upscale",
+            bindGroupLayouts: [bindLayout]
+          }),
+          vertex: { module: vs, entryPoint: "vs" },
+          fragment: { module: fs, entryPoint: "fs", targets: [{ format }] }
+        });
+        if (!pipeline) return;
+        pipelines.set(format, pipeline);
+      }
+      let buffer = buffers.get(ctx.view.name);
+      if (!buffer) {
+        buffer = gpu.device.createBuffer({
+          label: `${ctx.view.name}/upscale`,
+          size: 16,
+          usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+        });
+        buffers.set(ctx.view.name, buffer);
+      }
+      params[0] = layout.offsetX;
+      params[1] = layout.offsetY;
+      params[2] = layout.scale;
+      gpu.device.queue.writeBuffer(buffer, 0, params);
+      const source = layout.target.texture();
+      let cached = groups.get(ctx.view.name);
+      if (!cached || cached.texture !== source) {
+        cached = {
+          texture: source,
+          group: gpu.device.createBindGroup({
+            label: "pixel-upscale",
+            layout: bindLayout,
+            entries: [
+              { binding: 0, resource: source.createView() },
+              { binding: 1, resource: { buffer } }
+            ]
+          })
+        };
+        groups.set(ctx.view.name, cached);
+      }
+      const group = cached.group;
+      const pass = ctx.renderPass;
+      pass.setPipeline(pipeline);
+      pass.setBindGroup(0, group);
+      pass.draw(3);
+    }
+  };
+}
+const pixelPerfectPlugin = definePlugin({
+  name: "render/pixel-perfect",
+  dependencies: ["render/forward"],
+  build(app) {
+    app.insertResource(PixelPerfectPath, { installed: true });
+  },
+  ready(app) {
+    registerShaders(app.world.resource(Shaders), PIXEL_PERFECT_SHADERS);
+    app.world.resource(Graph).addNode("pixel-upscale", pixelUpscaleNode());
+  }
+});
+export {
+  PIXEL_PERFECT_SHADERS,
+  pixelPerfectPlugin,
+  pixelUpscaleNode
+};

package/dist/pixel-perfect.d.ts

@@ -0,0 +1,27 @@
+import { type Entity, type World } from '@aethervtt/shard-core';
+import { OffscreenTarget, type RenderTarget } from './target.js';
+export declare const PixelPerfect: import("@aethervtt/shard-core").ComponentDef<{
+    readonly pixelsPerUnit: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly snap: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+}>;
+/** How a PixelPerfect camera renders: its low-resolution target and the integer scale up. */
+export interface PixelPerfectLayout {
+    target: OffscreenTarget;
+    pixelsPerUnit: number;
+    snap: boolean;
+    /** Whole-number magnification. */
+    scale: number;
+    /** Low-resolution size, in texels. */
+    width: number;
+    height: number;
+    /** Top-left of the scaled image on the real target (letterbox), in pixels. */
+    offsetX: number;
+    offsetY: number;
+}
+/** Present when pixelPerfectPlugin is installed; without it PixelPerfect cameras render normally. */
+export declare const PixelPerfectPath: import("@aethervtt/shard-core").ResourceDef<{
+    installed: true;
+}>;
+export declare const PixelTargets: import("@aethervtt/shard-core").ResourceDef<Map<number, PixelPerfectLayout>>;
+/** Sizes (and keeps) a PixelPerfect camera's low-resolution target for the target it shows on. */
+export declare function pixelPerfectLayout(world: World, entity: Entity, shown: RenderTarget, orthoHeight: number, pixelsPerUnit: number, snap: boolean): PixelPerfectLayout;

package/dist/pixel-perfect.js

@@ -0,0 +1,70 @@
+import { defineComponent, defineResource, t } from "@aethervtt/shard-core";
+import { Gpu } from "./plugin.js";
+import { OffscreenTarget } from "./target.js";
+const PixelPerfect = defineComponent(
+  "render/PixelPerfect",
+  {
+    pixelsPerUnit: t.f32({
+      default: 16,
+      min: 0.01,
+      description: "Texels per world unit: the art resolution (16 for 16-px tiles one unit wide)."
+    }),
+    snap: t.bool({
+      default: true,
+      description: "Moves the camera and sprites in whole texels, so scrolling never shimmers."
+    })
+  },
+  {
+    description: "Crisp pixel art on an orthographic camera: renders at one texel per pixel (Camera3d.orthoHeight \xD7 pixelsPerUnit tall), then scales up by the largest whole number that fits the target, with nearest sampling. The camera's orthoHeight is adjusted to fill the letterboxed area exactly."
+  }
+);
+const PixelPerfectPath = defineResource("render/PixelPerfectPath", {
+  description: "Present when pixel-perfect cameras (pixelPerfectPlugin) are installed."
+});
+const PixelTargets = defineResource("render/PixelTargets", {
+  description: "Low-resolution targets of PixelPerfect cameras.",
+  init: () => /* @__PURE__ */ new Map()
+});
+function pixelPerfectLayout(world, entity, shown, orthoHeight, pixelsPerUnit, snap) {
+  const texels = Math.max(1, Math.round(orthoHeight * pixelsPerUnit));
+  const scale = Math.max(1, Math.floor(shown.height / texels));
+  const width = Math.max(1, Math.floor(shown.width / scale));
+  const height = Math.max(1, Math.floor(shown.height / scale));
+  const targets = world.initResource(PixelTargets);
+  let layout = targets.get(entity);
+  if (!layout) {
+    layout = {
+      target: new OffscreenTarget(world.resource(Gpu), {
+        label: `pixel-perfect:${entity}`,
+        width,
+        height,
+        format: shown.format
+      }),
+      pixelsPerUnit,
+      snap,
+      scale,
+      width,
+      height,
+      offsetX: 0,
+      offsetY: 0
+    };
+    targets.set(entity, layout);
+  }
+  if (layout.target.width !== width || layout.target.height !== height) {
+    layout.target.resize(width, height);
+  }
+  layout.pixelsPerUnit = pixelsPerUnit;
+  layout.snap = snap;
+  layout.scale = scale;
+  layout.width = width;
+  layout.height = height;
+  layout.offsetX = Math.floor((shown.width - width * scale) / 2);
+  layout.offsetY = Math.floor((shown.height - height * scale) / 2);
+  return layout;
+}
+export {
+  PixelPerfect,
+  PixelPerfectPath,
+  PixelTargets,
+  pixelPerfectLayout
+};