@aethervtt/shard-render 0.0.1 → 0.2.0

package/dist/culling.js

@@ -7,8 +7,9 @@ import {
   SLOT_MASK
 } from "./instances.js";
 import { Shaders } from "./plugin.js";
+import { NO_HIDDEN } from "./view-visibility.js";
 const ARGS_WORDS = 5;
-const VIEW_FLOATS = 32;
+const VIEW_FLOATS = 36;
 const BATCH_WORDS = 8;
 const LOD_WORDS = 20;
 const VIEW_CASTERS = 1;
@@ -21,6 +22,8 @@ class GpuCuller {
   supported;
   /** Turn off to force CPU culling (tests, debugging). */
   enabled = true;
+  /** Views this frame with a hidden set (0070): the cull links its HIDDEN variant. */
+  hiddenViews = 0;
   views = [];
   viewCount = 0;
   cameraViews = 0;
@@ -59,7 +62,7 @@ class GpuCuller {
   pending = /* @__PURE__ */ new Set();
   constructor(gpu) {
     this.gpu = gpu;
-    this.supported = gpu.features.has("indirect-first-instance");
+    this.supported = gpu.tier === "full" && gpu.features.has("indirect-first-instance");
     const storage = GPUBufferUsage.STORAGE;
     this.viewBuffer = new GpuBuffer(gpu, { label: "cull/views", usage: storage, size: 4096 });
     this.batchBuffer = new GpuBuffer(gpu, { label: "cull/batches", usage: storage, size: 2048 });
@@ -82,6 +85,7 @@ class GpuCuller {
   beginFrame() {
     this.viewCount = 0;
     this.cameraViews = 0;
+    this.hiddenViews = 0;
   }
   /** The LOD state row of a camera (cameras choose; their shadow views reuse the choice). */
   lodCamera(entity) {
@@ -110,7 +114,9 @@ class GpuCuller {
         hasEye: false,
         lodScale: 1,
         flags: 0,
-        lodCamera: 0
+        lodCamera: 0,
+        layers: 4294967295,
+        hiddenBase: NO_HIDDEN
       };
       this.views.push(view);
     }
@@ -122,6 +128,9 @@ class GpuCuller {
     if (params.eye) view.eye.set(params.eye);
     view.lodScale = params.lodScale;
     view.lodCamera = lodCamera;
+    view.layers = params.layers ?? 4294967295;
+    view.hiddenBase = params.hiddenBase ?? NO_HIDDEN;
+    if (view.hiddenBase !== NO_HIDDEN) this.hiddenViews++;
     view.flags = (params.require & InstanceFlags.Caster ? VIEW_CASTERS : 0) | (params.updateLod ? VIEW_UPDATE_LOD : 0) | (params.orthographic ? VIEW_ORTHO : 0) | (params.planes ? 0 : VIEW_NO_PLANES);
     if (params.updateLod) this.cameraViews = v + 1;
     list.cullView = v;
@@ -136,7 +145,8 @@ class GpuCuller {
     let n = 0;
     let m = 0;
     for (const batch of store.sorted) {
-      if (batch.count === 0 || batch.transparent || !store.anyVisible(batch)) continue;
+      if (batch.count === 0 || batch.transparent || batch.ground || !store.anyVisible(batch))
+        continue;
       if (!batch.ready) {
         list.pending += batch.count;
         continue;
@@ -157,9 +167,22 @@ class GpuCuller {
     if (forwardOnly) forwardOnly.length = m;
     return v;
   }
-  /** Uploads the frame's view, batch, and LOD tables, and sizes the buffers. */
-  prepare(store) {
+  /**
+   * Uploads the frame's view, batch, and LOD tables, and sizes the buffers. Hidden sets (0070)
+   * ride in the LOD state buffer after its entries: the cull's storage bindings are at WebGPU's
+   * guaranteed 8 per stage.
+   */
+  prepare(store, hidden) {
     if (this.viewCount === 0) return;
+    const lodCams = Math.max(1, this.lodCameras.size);
+    const hiddenWords = hidden && hidden.sets.size > 0 ? hidden.data.length : 0;
+    if (this.lodStateCapacity !== store.capacity * lodCams || this.lodState.byteLength < (this.lodStateCapacity + hiddenWords) * 4) {
+      this.lodStateCapacity = store.capacity * lodCams;
+      this.lodState.ensureCapacity((this.lodStateCapacity + hiddenWords) * 4);
+      const fill = new Uint32Array(this.lodStateCapacity).fill(LOD_UNSET);
+      this.lodState.write(fill);
+    }
+    if (hiddenWords > 0) hidden.upload(this.lodState, this.lodStateCapacity * 4);
     const batches = store.batches;
     this.batchCount = batches.length;
     if (this.batchData.length < batches.length * BATCH_WORDS) {
@@ -182,7 +205,7 @@ class GpuCuller {
       this.batchData[o + 4] = batch.mesh.drawCount;
       this.batchData[o + 5] = batch.mesh.indexed ? 1 + batch.mesh.baseVertex : 0;
       this.batchData[o + 6] = batch.region;
-      this.batchData[o + 7] = (batch.transparent ? BATCH_TRANSPARENT : 0) | (batch.ready ? 0 : BATCH_NOT_READY);
+      this.batchData[o + 7] = (batch.transparent || batch.ground ? BATCH_TRANSPARENT : 0) | (batch.ready ? 0 : BATCH_NOT_READY);
     }
     this.regionSize = Math.max(1, region);
     this.batchBuffer.write(this.batchData, 0, 0, Math.max(1, batches.length) * BATCH_WORDS);
@@ -220,6 +243,8 @@ class GpuCuller {
       this.viewU32[o + 29] = view.lodCamera;
       this.viewU32[o + 30] = v * batches.length;
       this.viewU32[o + 31] = v * this.regionSize;
+      this.viewU32[o + 32] = view.layers;
+      this.viewU32[o + 33] = view.hiddenBase === NO_HIDDEN ? NO_HIDDEN : this.lodStateCapacity + view.hiddenBase;
       for (const list of [view.list, view.forwardOnly]) {
         if (!list) continue;
         for (let d = 0; d < list.length; d++) {
@@ -232,12 +257,6 @@ class GpuCuller {
     this.viewBuffer.write(this.viewData, 0, 0, this.viewCount * VIEW_FLOATS);
     this.args.ensureCapacity(Math.max(1, this.viewCount * batches.length) * ARGS_WORDS * 4);
     this.visible.ensureCapacity(this.viewCount * this.regionSize * 4);
-    const lodCams = Math.max(1, this.lodCameras.size);
-    if (this.lodStateCapacity !== store.capacity * lodCams) {
-      this.lodStateCapacity = store.capacity * lodCams;
-      const fill = new Uint32Array(this.lodStateCapacity).fill(LOD_UNSET);
-      this.lodState.write(fill);
-    }
     this.frameViews = this.views.slice(0, this.viewCount);
     this.slotCount = store.high;
     this.slotCapacity = store.capacity;
@@ -249,7 +268,8 @@ class GpuCuller {
     if (this.viewCount === 0) return;
     const gpu = ctx.gpu;
     const world = ctx.world;
-    const module = world.resource(Shaders).module(gpu, { root: "shard::cull" });
+    const hidden = this.hiddenViews > 0;
+    const module = world.resource(Shaders).module(gpu, hidden ? HIDDEN_REQUEST : CULL_REQUEST);
     if (!module) {
       gpu.pipelines.skipped++;
       return;
@@ -257,12 +277,12 @@ class GpuCuller {
     const layout = cullLayout(gpu);
     const pipelineLayout = gpu.layouts.pipelineLayout({ label: "cull", bindGroupLayouts: [layout] });
     const reset = gpu.pipelines.compute({
-      label: "cull/reset",
+      label: hidden ? "cull/reset/hidden" : "cull/reset",
       layout: pipelineLayout,
       compute: { module, entryPoint: "reset" }
     });
     const cull = gpu.pipelines.compute({
-      label: "cull/instances",
+      label: hidden ? "cull/instances/hidden" : "cull/instances",
       layout: pipelineLayout,
       compute: { module, entryPoint: "cull" }
     });
@@ -309,7 +329,7 @@ class GpuCuller {
             label: "cull",
             layout,
             entries: [
-              { binding: 0, resource: { buffer: store.instanceBuffer.buffer } },
+              { binding: 0, resource: { buffer: store.instanceBuffer.gpuBuffer } },
               { binding: 1, resource: { buffer: this.batchBuffer.buffer } },
               { binding: 2, resource: { buffer: this.lodBuffer.buffer } },
               { binding: 3, resource: { buffer: this.viewBuffer.buffer } },
@@ -317,7 +337,7 @@ class GpuCuller {
               { binding: 5, resource: { buffer: this.visible.buffer } },
               { binding: 6, resource: { buffer: this.lodState.buffer } },
               { binding: 7, resource: { buffer: params.buffer } },
-              { binding: 8, resource: { buffer: store.deform.recordBuffer.buffer } }
+              { binding: 8, resource: { buffer: store.deform.recordBuffer.gpuBuffer } }
             ]
           })
         )
@@ -434,6 +454,8 @@ class GpuCuller {
     while (this.pending.size > 0) await Promise.all(this.pending);
   }
 }
+const CULL_REQUEST = { root: "shard::cull" };
+const HIDDEN_REQUEST = { root: "shard::cull", defines: { HIDDEN: true } };
 function cullLayout(gpu) {
   const C = GPUShaderStage.COMPUTE;
   const read = (binding) => ({
@@ -467,6 +489,9 @@ const Culler = defineResource("render/Culler", {
 function cullTransparent(store, list, params, forward) {
   store.cullTransparentMembers(list, params, forward);
 }
+function cullGround(store, list, params, overlay) {
+  store.cullGroundMembers(list, params, overlay);
+}
 function visibleSlots(store, list, mask = SLOT_MASK) {
   const out = /* @__PURE__ */ new Set();
   for (let d = 0; d < list.length; d++) {
@@ -492,6 +517,7 @@ async function readVisibleSlots(gpu, culler, list, mask = SLOT_MASK) {
 export {
   Culler,
   GpuCuller,
+  cullGround,
   cullTransparent,
   readVisibleSlots,
   visibleSlots

package/dist/cutaway-plugin.d.ts

@@ -0,0 +1,48 @@
+import { type Entity, type World } from '@aethervtt/shard-core';
+import { GpuBuffer } from '@aethervtt/shard-gpu';
+export declare const CUTAWAY_SHADERS: Record<string, string>;
+/** A camera's reveal points as uploaded, and the bind group over them. */
+interface CutawayCamera {
+    data: Float32Array;
+    buffer: GpuBuffer | undefined;
+    bindGroup: GPUBindGroup | undefined;
+    /** The device generation and buffer version the bind group was made for. */
+    boundGeneration: number;
+    boundVersion: number;
+    /** Points in use (at most MAX_REVEAL_POINTS). */
+    count: number;
+    /** Points the component listed. */
+    listed: number;
+    frame: number;
+    /** Too many points was reported for this camera. */
+    warned: boolean;
+    /** The device generation its buffer was last written on (a new device loses the contents). */
+    written: number;
+    /** Per batch index: 1 when a point can cut one of its Cutaway instances this frame. */
+    cuts: Uint8Array;
+}
+export interface CutawayState {
+    cameras: Map<Entity, CutawayCamera>;
+    frame: number;
+    layout: {
+        layout: GPUBindGroupLayout;
+        generation: number;
+    } | undefined;
+}
+export declare const CutawayCameras: import("@aethervtt/shard-core").ResourceDef<CutawayState>;
+/**
+ * Packs each camera's CutawayView into its uniform, with each point's line of sight from the
+ * camera. Only a camera whose values changed uploads (a camera moving changes the lines); a still
+ * frame writes nothing and allocates nothing.
+ */
+export declare const extractCutaways: import("@aethervtt/shard-core").SystemDef<{
+    q: import("@aethervtt/shard-core").Query;
+}>;
+/** render.describe's cutaways section: per camera, its reveal points, radius, margin and edge. */
+export declare function describeCutaways(world: World): Record<string, unknown>;
+/**
+ * Cutaways (0070): Cutaway renderables open around a camera's CutawayView points, in every camera
+ * pass and no shadow pass. Cameras without reveal points draw the plain variants.
+ */
+export declare const cutawayPlugin: import("@aethervtt/shard-runtime").Plugin;
+export {};

package/dist/cutaway-plugin.js

@@ -0,0 +1,364 @@
+import { defineResource, defineSystem, Last } from "@aethervtt/shard-core";
+import { GpuBuffer } from "@aethervtt/shard-gpu";
+import { definePlugin, LogResource } from "@aethervtt/shard-runtime";
+import { Camera3d } from "./camera.js";
+import { CutawayPath, CutawayView, MAX_REVEAL_POINTS } from "./cutaway.js";
+import { addRenderFeatures } from "./features.js";
+import {
+  INSTANCE_FLOATS,
+  InstanceFlags,
+  Instances,
+  prepareInstances
+} from "./instances.js";
+import { Gpu, RenderDescribers, RenderSet, Shaders } from "./plugin.js";
+import { registerShaders } from "./shaders.js";
+import { Cameras } from "./view.js";
+const CUTAWAY_FLOATS = MAX_REVEAL_POINTS * 8 + 4;
+const DIRS = MAX_REVEAL_POINTS * 4;
+const PARAMS = MAX_REVEAL_POINTS * 8;
+const CUTAWAY_SHADERS = {
+  "shard::cutaway": `
+struct Cutaway {
+  /** Reveal points (xyz). */
+  points: array<vec4f, ${MAX_REVEAL_POINTS}>,
+  /**
+   * Each point's line of sight, unit (xyz): from the eye through it, or the view direction when
+   * orthographic. Made on the CPU once a frame, not per fragment.
+   */
+  dirs: array<vec4f, ${MAX_REVEAL_POINTS}>,
+  /** radius, margin, edge (m), and how many points. */
+  params: vec4f,
+}
+
+@group(3) @binding(0) var<uniform> cutaway: Cutaway;
+
+/** InstanceFlags.Cutaway in the record's flags word. */
+const CUTAWAY_FLAG: u32 = 0x10000000u;
+
+/** 0 to 1 across an edge band of width \`edge\` ending at 0 (a step when edge is 0). */
+fn cutaway_ramp(inside: f32, edge: f32) -> f32 {
+  if (edge <= 0.0) { return select(0.0, 1.0, inside > 0.0); }
+  return clamp(inside / edge, 0.0, 1.0);
+}
+
+/**
+ * How cut a world point is, 0 (whole) to 1: within radius of the line from the eye through a
+ * reveal point (along the view direction when orthographic), and nearer the camera than the point
+ * by more than margin. The edge band ramps both.
+ */
+fn cutaway_amount(world: vec3f) -> f32 {
+  let radius = cutaway.params.x;
+  let margin = cutaway.params.y;
+  let edge = cutaway.params.z;
+  let count = u32(cutaway.params.w);
+  var amount = 0.0;
+  for (var i = 0u; i < count; i++) {
+    let d = world - cutaway.points[i].xyz;
+    let along = dot(d, cutaway.dirs[i].xyz);
+    // Not in front of the point by the margin, or outside the radius: this point cuts nothing.
+    let ahead = -along - margin;
+    if (ahead <= 0.0) { continue; }
+    let across2 = max(dot(d, d) - along * along, 0.0);
+    if (across2 >= radius * radius) { continue; }
+    amount = max(amount, min(cutaway_ramp(radius - sqrt(across2), edge), cutaway_ramp(ahead, edge)));
+    if (amount >= 1.0) { break; }
+  }
+  return amount;
+}
+
+/** An ordered 4\xD74 dither threshold at a pixel, in (0, 1). */
+fn cutaway_threshold(frag: vec2f) -> f32 {
+  let x = u32(frag.x);
+  let y = u32(frag.y);
+  let low = (((x ^ y) & 1u) << 1u) | (y & 1u);
+  let high = ((((x ^ y) >> 1u) & 1u) << 1u) | ((y >> 1u) & 1u);
+  return (f32(low * 4u + high) + 0.5) / 16.0;
+}
+
+/** Removes the fragment of a Cutaway instance that stands in front of a reveal point. */
+fn cutaway_clip(world: vec3f, frag: vec2f, flags: u32) {
+  if ((flags & CUTAWAY_FLAG) == 0u) { return; }
+  if (cutaway_amount(world) > cutaway_threshold(frag)) { discard; }
+}`
+};
+const CutawayCameras = defineResource("render/CutawayCameras", {
+  description: "Each camera's reveal points as the cutaway variants read them (0070).",
+  init: () => ({ cameras: /* @__PURE__ */ new Map(), frame: 0, layout: void 0 })
+});
+function cameraOf(state, camera) {
+  let c = state.cameras.get(camera);
+  if (!c) {
+    c = {
+      data: new Float32Array(CUTAWAY_FLOATS),
+      buffer: void 0,
+      bindGroup: void 0,
+      boundGeneration: -1,
+      boundVersion: -1,
+      count: -1,
+      listed: 0,
+      frame: -1,
+      warned: false,
+      written: -1,
+      cuts: new Uint8Array(64)
+    };
+    state.cameras.set(camera, c);
+  }
+  return c;
+}
+function warnTooMany(world, camera, listed) {
+  world.tryResource(LogResource)?.log(
+    "warn",
+    `Camera ${camera} has ${listed} reveal points; only the first ${MAX_REVEAL_POINTS} cut`,
+    {
+      code: "render/too-many-reveal-points",
+      hint: `Give CutawayView at most ${MAX_REVEAL_POINTS} points: the party, or the selected tokens.`,
+      data: { camera, points: listed }
+    }
+  );
+}
+function put(d, o, v) {
+  if (d[o] === Math.fround(v)) return false;
+  d[o] = v;
+  return true;
+}
+const extractCutaways = defineSystem({
+  name: "render/extract-cutaways",
+  description: "Packs cameras' reveal points for the cutaway variants (0070).",
+  setup: (world) => ({ q: world.query({ with: [Camera3d, CutawayView] }) }),
+  run: ({ q }, world) => {
+    const state = world.resource(CutawayCameras);
+    const gpu = world.resource(Gpu);
+    const cameras = world.resource(Cameras);
+    const store = world.resource(Instances);
+    const frame = ++state.frame;
+    for (const table of q.tables) {
+      const points = table.column(CutawayView, "points");
+      const radius = table.column(CutawayView, "radius");
+      const margin = table.column(CutawayView, "margin");
+      const edge = table.column(CutawayView, "edge");
+      for (let i = 0; i < table.count; i++) {
+        const camera = table.entities[i];
+        const c = cameraOf(state, camera);
+        c.frame = frame;
+        const list = points[i] ?? EMPTY;
+        const listed = list.length;
+        const count = Math.min(listed, MAX_REVEAL_POINTS);
+        if (listed > MAX_REVEAL_POINTS && !c.warned) {
+          c.warned = true;
+          warnTooMany(world, camera, listed);
+        }
+        c.listed = listed;
+        const cam = cameras.get(camera);
+        const n = cam ? count : 0;
+        const d = c.data;
+        let changed = c.count !== n;
+        for (let k = 0; k < n; k++) {
+          const p = list[k];
+          const o = k * 4;
+          changed = put(d, o, p[0]) || changed;
+          changed = put(d, o + 1, p[1]) || changed;
+          changed = put(d, o + 2, p[2]) || changed;
+          const f = cam.forward;
+          let x = f[0];
+          let y = f[1];
+          let z = f[2];
+          if (!cam.orthographic) {
+            const e = cam.position;
+            const dx = p[0] - e[0];
+            const dy = p[1] - e[1];
+            const dz = p[2] - e[2];
+            const len = Math.sqrt(dx * dx + dy * dy + dz * dz);
+            if (len > 1e-5) {
+              x = dx / len;
+              y = dy / len;
+              z = dz / len;
+            }
+          }
+          changed = put(d, DIRS + o, x) || changed;
+          changed = put(d, DIRS + o + 1, y) || changed;
+          changed = put(d, DIRS + o + 2, z) || changed;
+        }
+        changed = put(d, PARAMS, radius[i]) || changed;
+        changed = put(d, PARAMS + 1, margin[i]) || changed;
+        changed = put(d, PARAMS + 2, edge[i]) || changed;
+        changed = put(d, PARAMS + 3, n) || changed;
+        c.count = n;
+        if (n > 0) markCuts(c, store);
+        if (n > 0 && (changed || c.written !== gpu.generation)) {
+          c.written = gpu.generation;
+          c.buffer ??= new GpuBuffer(gpu, {
+            label: `camera:${camera}/cutaway`,
+            usage: GPUBufferUsage.UNIFORM,
+            size: CUTAWAY_FLOATS * 4
+          });
+          c.buffer.write(d);
+        }
+      }
+    }
+    let live = 0;
+    for (const table of q.tables) live += table.count;
+    if (state.cameras.size > live) {
+      for (const [camera, c] of state.cameras) {
+        if (c.frame === frame) continue;
+        c.buffer?.destroy();
+        state.cameras.delete(camera);
+      }
+    }
+  }
+});
+const EMPTY = [];
+const box = new Float32Array(6);
+function slotBox(f, o, b) {
+  const cx = (b[0] + b[3]) * 0.5;
+  const cy = (b[1] + b[4]) * 0.5;
+  const cz = (b[2] + b[5]) * 0.5;
+  const ex = (b[3] - b[0]) * 0.5;
+  const ey = (b[4] - b[1]) * 0.5;
+  const ez = (b[5] - b[2]) * 0.5;
+  for (let r = 0; r < 3; r++) {
+    const m = o + r * 4;
+    box[r] = f[m] * cx + f[m + 1] * cy + f[m + 2] * cz + f[m + 3];
+    box[3 + r] = Math.abs(f[m]) * ex + Math.abs(f[m + 1]) * ey + Math.abs(f[m + 2]) * ez;
+  }
+}
+function reaches(d, k, radius, margin) {
+  const o = k * 4;
+  let t0 = 0;
+  let t1 = Number.POSITIVE_INFINITY;
+  for (let a = 0; a < 3; a++) {
+    const dir = -d[DIRS + o + a];
+    const start = d[o + a] + dir * margin;
+    const lo = box[a] - box[3 + a] - radius;
+    const hi = box[a] + box[3 + a] + radius;
+    if (Math.abs(dir) < 1e-9) {
+      if (start < lo || start > hi) return false;
+      continue;
+    }
+    let near = (lo - start) / dir;
+    let far = (hi - start) / dir;
+    if (near > far) {
+      const t = near;
+      near = far;
+      far = t;
+    }
+    if (near > t0) t0 = near;
+    if (far < t1) t1 = far;
+    if (t0 > t1) return false;
+  }
+  return true;
+}
+function markCuts(c, store) {
+  const batches = store.batches;
+  if (c.cuts.length < batches.length) c.cuts = new Uint8Array(batches.length * 2);
+  const cuts = c.cuts;
+  const d = c.data;
+  const n = d[PARAMS + 3];
+  const radius = d[PARAMS];
+  const margin = d[PARAMS + 1];
+  for (let b = 0; b < batches.length; b++) {
+    const batch = batches[b];
+    cuts[b] = 0;
+    if (batch.cutaway === 0) continue;
+    if (batch.memberCount < batch.count) {
+      cuts[b] = 1;
+      continue;
+    }
+    for (let m = 0; m < batch.memberCount && cuts[b] === 0; m++) {
+      const slot = batch.members[m];
+      const flags = store.flags[slot];
+      if ((flags & InstanceFlags.Cutaway) === 0) continue;
+      if (flags & InstanceFlags.Skinned) {
+        cuts[b] = 1;
+        break;
+      }
+      slotBox(store.f32, slot * INSTANCE_FLOATS, batch.mesh.bounds);
+      for (let k = 0; k < n; k++) {
+        if (reaches(d, k, radius, margin)) {
+          cuts[b] = 1;
+          break;
+        }
+      }
+    }
+  }
+}
+function support(world) {
+  const state = world.resource(CutawayCameras);
+  const layout = (gpu) => {
+    if (!state.layout || state.layout.generation !== gpu.generation) {
+      state.layout = {
+        layout: gpu.layouts.bindGroupLayout({
+          label: "cutaway",
+          entries: [
+            { binding: 0, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } }
+          ]
+        }),
+        generation: gpu.generation
+      };
+    }
+    return state.layout.layout;
+  };
+  return {
+    layout,
+    cuts(camera, batch) {
+      const c = state.cameras.get(camera);
+      return c !== void 0 && c.frame === state.frame && c.count > 0 && c.cuts[batch] === 1;
+    },
+    bindGroup(gpu, camera) {
+      const c = state.cameras.get(camera);
+      if (!c || c.frame !== state.frame || c.count <= 0 || !c.buffer) return void 0;
+      const buffer = c.buffer;
+      const gpuBuffer = buffer.buffer;
+      if (!c.bindGroup || c.boundGeneration !== gpu.generation || c.boundVersion !== buffer.version) {
+        c.bindGroup = gpu.device.createBindGroup({
+          label: "cutaway",
+          layout: layout(gpu),
+          entries: [{ binding: 0, resource: { buffer: gpuBuffer } }]
+        });
+        c.boundGeneration = gpu.generation;
+        c.boundVersion = buffer.version;
+      }
+      return c.bindGroup;
+    }
+  };
+}
+function describeCutaways(world) {
+  const out = {};
+  world.query({ with: [Camera3d, CutawayView] }).each((camera, row, table) => {
+    const points = table.column(CutawayView, "points")[row] ?? [];
+    out[`camera:${camera}`] = {
+      points: Array.from(points.slice(0, MAX_REVEAL_POINTS), (p) => [p[0], p[1], p[2]]),
+      ignored: Math.max(0, points.length - MAX_REVEAL_POINTS),
+      radius: table.column(CutawayView, "radius")[row],
+      margin: table.column(CutawayView, "margin")[row],
+      edge: table.column(CutawayView, "edge")[row]
+    };
+  });
+  return out;
+}
+const cutawayPlugin = definePlugin({
+  name: "render/cutaway",
+  dependencies: ["render/forward"],
+  provides: [CutawayCameras],
+  build(app) {
+    app.world.initResource(CutawayCameras);
+    app.insertResource(CutawayPath, support(app.world));
+    app.addSystems(Last, extractCutaways.inSet(RenderSet.Prepare).after(prepareInstances));
+  },
+  ready(app) {
+    registerShaders(app.world.resource(Shaders), CUTAWAY_SHADERS);
+    app.world.initResource(RenderDescribers).set("cutaways", describeCutaways);
+    addRenderFeatures(app.world, {
+      name: "render/cutaway",
+      description: "Cutaway surfaces opened around cameras' reveal points.",
+      nodes: [],
+      baseline: { strategy: "The same discard; points in a uniform block" }
+    });
+  }
+});
+export {
+  CUTAWAY_SHADERS,
+  CutawayCameras,
+  cutawayPlugin,
+  describeCutaways,
+  extractCutaways
+};

package/dist/cutaway.d.ts

@@ -0,0 +1,27 @@
+import { type Entity } from '@aethervtt/shard-core';
+import type { GpuContext } from '@aethervtt/shard-gpu';
+/** Reveal points a camera can have; more are ignored with `render/too-many-reveal-points`. */
+export declare const MAX_REVEAL_POINTS = 16;
+export declare const Cutaway: import("@aethervtt/shard-core").ComponentDef<{}>;
+export declare const CutawayView: import("@aethervtt/shard-core").ComponentDef<{
+    readonly points: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec3[], "object">;
+    readonly radius: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly margin: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly edge: import("@aethervtt/shard-core").FieldType<number, "f32">;
+}>;
+/**
+ * Set by `cutawayPlugin`: what the camera passes need to draw the cutaway variants of pipelines.
+ * Forward asks it per view, so core imports no cutaway code.
+ */
+export interface CutawaySupport {
+    /** The bind group layout cutaway pipelines take at group 3. */
+    layout(gpu: GpuContext): GPUBindGroupLayout;
+    /** The camera's reveal points, bound at group 3: undefined when it has none this frame. */
+    bindGroup(gpu: GpuContext, camera: Entity): GPUBindGroup | undefined;
+    /**
+     * Whether a point of the camera can cut an instance of the batch this frame: its bounds reach a
+     * reveal cylinder. The others draw the plain variant (no discard, so no per-fragment cost).
+     */
+    cuts(camera: Entity, batch: number): boolean;
+}
+export declare const CutawayPath: import("@aethervtt/shard-core").ResourceDef<CutawaySupport>;

package/dist/cutaway.js

@@ -0,0 +1,49 @@
+import { defineComponent, defineResource, t } from "@aethervtt/shard-core";
+import { Camera3d } from "./camera.js";
+const MAX_REVEAL_POINTS = 16;
+const Cutaway = defineComponent(
+  "render/Cutaway",
+  {},
+  {
+    description: "Tag on a renderable: it may be cut away around a camera's reveal points (CutawayView). Shadows never cut."
+  }
+);
+const CutawayView = defineComponent(
+  "render/CutawayView",
+  {
+    points: t.list(t.vec3, {
+      description: `World points to reveal, at most ${MAX_REVEAL_POINTS}: a token's position, the party.`
+    }),
+    radius: t.f32({
+      default: 2.5,
+      min: 0,
+      unit: "m",
+      description: "How far from each point's line of sight a Cutaway surface is cut."
+    }),
+    margin: t.f32({
+      default: 0.6,
+      min: 0,
+      unit: "m",
+      description: "How far in front of a point the cut starts, so the floor it stands on, and a stairwell rim, stay."
+    }),
+    edge: t.f32({
+      default: 0.3,
+      min: 0,
+      unit: "m",
+      description: "Width of the dithered rim; 0 is a hard cut."
+    })
+  },
+  {
+    description: "Cuts Cutaway surfaces away between this camera and its reveal points (0070): a disc in a roof from above, a hole in a wall at an angle. Every camera pass (picking too) sees the hole; shadows do not.",
+    requires: [Camera3d]
+  }
+);
+const CutawayPath = defineResource("render/CutawayPath", {
+  description: "Present when cutaways (cutawayPlugin) are installed."
+});
+export {
+  Cutaway,
+  CutawayPath,
+  CutawayView,
+  MAX_REVEAL_POINTS
+};