@aethervtt/shard-render 0.0.1 → 0.1.0

package/dist/instances.js

@@ -1,3 +1,4 @@
+import { AssetServerResource } from "@aethervtt/shard-assets";
 import {
   defineComponent,
   defineResource,
@@ -5,13 +6,16 @@ import {
   onRemove,
   t
 } from "@aethervtt/shard-core";
-import { GpuBuffer } from "@aethervtt/shard-gpu";
-import { LogResource } from "@aethervtt/shard-runtime";
+import { DevMode } from "@aethervtt/shard-runtime";
 import { toHalf } from "@aethervtt/shard-texture";
 import { GlobalTransform, Transform } from "@aethervtt/shard-transform";
 import { MaterialAsset, Materials, Meshes } from "./assets.js";
+import { Cutaway, CutawayPath } from "./cutaway.js";
+import { DataStore } from "./data-store.js";
 import { DEFORM_WORDS, DeformStore } from "./deform.js";
+import { warnFeatureMissing } from "./features.js";
 import { GpuAssetsResource } from "./gpu-assets.js";
+import { GroundLayer, OVERLAY_BAND, RenderLayers } from "./layers.js";
 import { isTransparent } from "./materials.js";
 import { ComputedVisibility, Visibility } from "./visibility.js";
 const InstanceSlot = defineComponent(
@@ -32,6 +36,11 @@ const NotShadowCaster = defineComponent(
   {},
   { description: "Tag: this mesh casts no shadows." }
 );
+const ShadowWhenHidden = defineComponent(
+  "render/ShadowWhenHidden",
+  {},
+  { description: "Tag: while hidden, this mesh still casts shadows (camera views skip it)." }
+);
 const NotShadowReceiver = defineComponent(
   "render/NotShadowReceiver",
   {},
@@ -153,8 +162,21 @@ const InstanceFlags = {
   /** Skinned: the vertex stage reads joint matrices; culling reads the slot's own sphere. */
   Skinned: 32,
   /** Morphed: the vertex stage adds morph target deltas. */
-  Morph: 64
+  Morph: 64,
+  /** Hidden, but drawn in shadow views (ShadowWhenHidden); Visible is off. */
+  ShadowOnly: 128,
+  /**
+   * May be cut away around a camera's reveal points (Cutaway, 0070). In the record's flags word
+   * it rides in bit 28 (`CUTAWAY_BIT`), above the layers and the LOD.
+   */
+  Cutaway: 256
 };
+const CUTAWAY_BIT = 1 << 28;
+function recordFlags(flags, layers) {
+  return (flags & 255 | layers << LAYER_SHIFT | (flags & InstanceFlags.Cutaway ? CUTAWAY_BIT : 0)) >>> 0;
+}
+const LAYER_SHIFT = 8;
+const LAYER_BITS = 65535 << LAYER_SHIFT;
 const NO_BATCH = 4294967295;
 const LOD_BIT = 2147483648;
 const SLOT_MASK = 268435455;
@@ -237,7 +259,7 @@ class InstanceStore {
    * Each slot's InstanceFlags, mirrored from its record: prepare compares against these every
    * frame, and reading them from the 64-byte records would touch a cache line per instance.
    */
-  flags = new Uint8Array(0);
+  flags = new Uint16Array(0);
   /** Hidden instances per ECS table id, from the last time prepare visited the table. */
   tableHidden = [];
   /** Batch index (>= 0), LOD set (-2 - index), or -1 (none), per slot. */
@@ -275,9 +297,24 @@ class InstanceStore {
   /** Batches in draw order (sorted by pipeline, then material, then mesh). */
   sorted = [];
   byMesh = /* @__PURE__ */ new Map();
+  byMeshGround = /* @__PURE__ */ new Map();
+  /**
+   * Render layer mask per slot (0057); 1 for slots without RenderLayers. It also rides in bits
+   * 8–23 of the record's flags word, where the GPU culler reads it.
+   */
+  layers = new Uint16Array(0);
+  /** Ground key per slot, (level, band, order) packed; NaN off the ground (0057, 0067). */
+  groundKeys = new Float64Array(0);
   lodSets = [];
   lodByKey = /* @__PURE__ */ new Map();
   defaultMaterial = new MaterialAsset();
+  /**
+   * What stand-ins for failed meshes are drawn with (0061): matte gray, or magenta in a dev build
+   * (`DevMode`, read by prepareInstances).
+   */
+  missingMaterial = new MaterialAsset({ baseColor: [0.5, 0.5, 0.5, 1], roughness: 1 });
+  /** A development build: the missing material turns magenta. */
+  dev = false;
   /** Bytes of instance data uploaded this frame. */
   uploadedBytes = 0;
   /** Slots with a batch and not hidden, and hidden ones: stats for GPU-culled views. */
@@ -285,6 +322,13 @@ class InstanceStore {
   hiddenCount = 0;
   /** Bumps when batches or LOD sets change shape (the GPU tables re-upload). */
   structureVersion = 0;
+  /** Bumps when a slot is allocated or freed (hidden sets resolve again, 0070). */
+  slotEpoch = 0;
+  /**
+   * Bumps when what casts shadows changes other than by moving: a slot's batch, its caster or
+   * visible flag, or a batch's mesh data. Cached shadow maps (0055) redraw when it moves.
+   */
+  shadowEpoch = 0;
   /** Visible slot lists of every CPU-culled view this frame, concatenated. */
   visible = new Uint32Array(1024);
   visibleCount = 0;
@@ -305,23 +349,11 @@ class InstanceStore {
   constructor(gpu) {
     this.gpu = gpu;
     this.generation = gpu.generation;
-    this.instanceBuffer = new GpuBuffer(gpu, {
-      label: "instances",
-      usage: GPUBufferUsage.STORAGE,
-      size: INSTANCE_BYTES * 256
-    });
-    this.prevBuffer = new GpuBuffer(gpu, {
-      label: "instances/previous",
-      usage: GPUBufferUsage.STORAGE,
-      size: PREV_BYTES * 256
-    });
-    this.visibleBuffer = new GpuBuffer(gpu, {
-      label: "instances/visible",
-      usage: GPUBufferUsage.STORAGE,
-      size: 4 * 1024
-    });
-    this.layout = createInstanceLayout(gpu);
+    this.instanceBuffer = new DataStore(gpu, { label: "instances", size: INSTANCE_BYTES * 256 });
+    this.prevBuffer = new DataStore(gpu, { label: "instances/previous", size: PREV_BYTES * 256 });
+    this.visibleBuffer = new DataStore(gpu, { label: "instances/visible", size: 4 * 1024 });
     this.deform = new DeformStore(gpu);
+    this.layout = createInstanceLayout(gpu, this);
     this.grow(256);
   }
   get live() {
@@ -344,7 +376,7 @@ class InstanceStore {
     const dirty = new Uint8Array(capacity);
     dirty.set(this.dirty);
     this.dirty = dirty;
-    const flags = new Uint8Array(capacity);
+    const flags = new Uint16Array(capacity);
     flags.set(this.flags);
     this.flags = flags;
     const prev = new Float32Array(capacity * 12);
@@ -356,6 +388,12 @@ class InstanceStore {
     const movedFrame = new Uint32Array(capacity);
     movedFrame.set(this.movedFrame);
     this.movedFrame = movedFrame;
+    const layers = new Uint16Array(capacity).fill(1);
+    layers.set(this.layers);
+    this.layers = layers;
+    const groundKeys = new Float64Array(capacity).fill(Number.NaN);
+    groundKeys.set(this.groundKeys);
+    this.groundKeys = groundKeys;
     this.capacity = capacity;
     this.deform.ensureSlots(capacity);
   }
@@ -366,16 +404,39 @@ class InstanceStore {
       slot = this.high++;
     }
     this.u32[slot * INSTANCE_FLOATS + 12] = NO_BATCH;
-    this.u32[slot * INSTANCE_FLOATS + 13] = 0;
+    this.u32[slot * INSTANCE_FLOATS + 13] = 1 << LAYER_SHIFT;
     this.flags[slot] = 0;
     this.u32[slot * INSTANCE_FLOATS + 14] = 0;
     this.u32[slot * INSTANCE_FLOATS + 15] = entity % 4294967296;
     this.batchOf[slot] = -1;
     this.memberIndex[slot] = -1;
     this.lods[slot] = null;
+    this.groundKeys[slot] = Number.NaN;
+    this.layers[slot] = 1;
     this.markDirty(slot);
+    this.slotEpoch++;
     return slot;
   }
+  /** A slot's render layer mask (0057). What casts shadows in a view may change: cached maps redraw. */
+  setLayers(slot, mask) {
+    const m = mask & 65535;
+    if (this.layers[slot] === m) return;
+    this.layers[slot] = m;
+    const o = slot * INSTANCE_FLOATS + 13;
+    this.u32[o] = (this.u32[o] & ~LAYER_BITS | m << LAYER_SHIFT) >>> 0;
+    this.markDirty(slot);
+    this.shadowEpoch++;
+  }
+  /**
+   * A slot's ground key (0057): `groundKey(band, order, level)`, or NaN off the ground. Returns whether
+   * it moved on or off the ground (its batch must be resolved again).
+   */
+  setGround(slot, key) {
+    const old = this.groundKeys[slot];
+    if (Object.is(old, key)) return false;
+    this.groundKeys[slot] = key;
+    return Number.isNaN(old) !== Number.isNaN(key);
+  }
   release(slot) {
     this.assign(slot, -1);
     this.u32[slot * INSTANCE_FLOATS + 13] = 0;
@@ -387,6 +448,7 @@ class InstanceStore {
     this.deform.clear(slot);
     this.markDirty(slot);
     this.free.push(slot);
+    this.slotEpoch++;
   }
   boundsDirty = true;
   cachedBounds = new Float32Array(6);
@@ -401,12 +463,11 @@ class InstanceStore {
       b[0] = b[1] = b[2] = Number.POSITIVE_INFINITY;
       b[3] = b[4] = b[5] = Number.NEGATIVE_INFINITY;
       const sphere = scratchSphere;
-      const need = InstanceFlags.Visible | InstanceFlags.Caster;
       for (let s = 0; s < this.high; s++) {
         const a = this.batchOf[s];
-        if (a === -1 || (this.u32[s * INSTANCE_FLOATS + 13] & need) !== need) continue;
+        if (a === -1 || !casts(this.u32[s * INSTANCE_FLOATS + 13])) continue;
         const batch = this.batches[a >= 0 ? a : this.lodSets[-2 - a].batches[0]];
-        if (batch.transparent) continue;
+        if (batch.transparent || batch.ground) continue;
         sphereOfSlot(sphere, this, s, this.u32[s * INSTANCE_FLOATS + 13], batch.mesh.bounds);
         for (let k = 0; k < 3; k++) {
           if (sphere[k] - sphere[3] < b[k]) b[k] = sphere[k] - sphere[3];
@@ -505,6 +566,9 @@ class InstanceStore {
   assign(slot, assignment) {
     const old = this.batchOf[slot];
     if (old === assignment) return;
+    this.shadowEpoch++;
+    const cut = this.flags[slot] & InstanceFlags.Cutaway;
+    if (cut) this.countCutaway(slot, -1);
     if (old >= 0) {
       this.batches[old].count--;
       this.removeMember(slot, this.batches[old]);
@@ -523,8 +587,55 @@ class InstanceStore {
     }
     this.batchOf[slot] = assignment;
     this.u32[slot * INSTANCE_FLOATS + 12] = assignment >= 0 ? assignment : assignment <= -2 ? (LOD_BIT | -2 - assignment) >>> 0 : NO_BATCH;
+    if (cut) this.countCutaway(slot, 1);
     this.markDirty(slot);
   }
+  /** Adds `delta` to the cutaway count of every batch the slot can land in (0070). */
+  countCutaway(slot, delta) {
+    const a = this.batchOf[slot];
+    if (a >= 0) this.batches[a].cutaway += delta;
+    else if (a <= -2)
+      for (const b of this.lodSets[-2 - a].batches) this.batches[b].cutaway += delta;
+  }
+  /**
+   * Bumps `shadowEpoch` if any batch's mesh data changed since the last call (a structure chunk
+   * rebuilt in place). One compare per batch.
+   */
+  checkMeshVersions() {
+    const batches = this.batches;
+    for (let i = 0; i < batches.length; i++) {
+      const b = batches[i];
+      if (b.meshVersion !== b.mesh.version) {
+        b.meshVersion = b.mesh.version;
+        this.shadowEpoch++;
+      }
+    }
+  }
+  /**
+   * Whether a visible caster that moved this frame touches the half-spaces `planes`, where it
+   * was or where it is now. Call after prepare. Skinned and morphed poses aren't moves; see
+   * `deforming`.
+   */
+  movedCasterIn(planes) {
+    const sphere = scratchSphere;
+    for (let i = 0; i < this.lastMovedCount; i++) {
+      const slot = this.lastMoved[i];
+      if (slot >= this.high || !casts(this.flags[slot])) continue;
+      const a = this.batchOf[slot];
+      if (a === -1) continue;
+      const batch = this.batches[a >= 0 ? a : this.lodSets[-2 - a].batches[0]];
+      if (batch.transparent || batch.ground) continue;
+      sphereOfSlot(sphere, this, slot, this.flags[slot], batch.mesh.bounds);
+      if (sphereInFrustum(planes, sphere)) return true;
+      slotSphere(sphere, this.prev, slot * 12, batch.mesh.bounds);
+      if (sphereInFrustum(planes, sphere)) return true;
+    }
+    return false;
+  }
+  /** Whether skinned or morphed poses are being written this frame (their shadows move). */
+  get deforming() {
+    return this.deform.poseCount > 0;
+  }
   /** A plain batch assignment. */
   setBatch(slot, index) {
     this.assign(slot, index);
@@ -546,11 +657,12 @@ class InstanceStore {
     this.memberIndex[last] = i;
     this.memberIndex[slot] = -1;
   }
-  batchFor(mesh, material, meshGuid, materialGuid) {
-    let byMaterial = this.byMesh.get(mesh);
+  batchFor(mesh, material, meshGuid, materialGuid, ground = false) {
+    const byMesh = ground ? this.byMeshGround : this.byMesh;
+    let byMaterial = byMesh.get(mesh);
     if (!byMaterial) {
       byMaterial = /* @__PURE__ */ new Map();
-      this.byMesh.set(mesh, byMaterial);
+      byMesh.set(mesh, byMaterial);
     }
     let batch = byMaterial.get(material);
     if (!batch) {
@@ -570,7 +682,10 @@ class InstanceStore {
         scratch: new Uint32Array(64),
         scratchCount: 0,
         forwardScratch: new Uint32Array(16),
-        forwardCount: 0
+        forwardCount: 0,
+        meshVersion: mesh.version,
+        cutaway: 0,
+        ground
       };
       byMaterial.set(material, batch);
       this.batches.push(batch);
@@ -648,7 +763,7 @@ class InstanceStore {
   upload() {
     if (this.generation !== this.gpu.generation) {
       this.generation = this.gpu.generation;
-      this.layout = createInstanceLayout(this.gpu);
+      this.layout = createInstanceLayout(this.gpu, this);
       this.bindGroup = void 0;
       this.gpuBindGroup = void 0;
       this.dirtyLo = 0;
@@ -716,13 +831,19 @@ class InstanceStore {
   tBatches = new Int32Array(64);
   tDepths = new Float32Array(64);
   tOrder = [];
+  // Ground instances this cull: slot, batch, and (band, order) key.
+  groundCount = 0;
+  gSlots = new Uint32Array(64);
+  gBatches = new Int32Array(64);
+  gKeys = new Float64Array(64);
+  gOrder = [];
   /**
    * CPU culling of every slot into `list` (and, for camera views, `transparent` back to front and
    * deferred `forwardOnly`). Same tests as the GPU culler: bounding sphere against the frustum,
    * visibility range, LOD level. `bounds` gets the union of what passed (cascade fitting). With
    * `transparentOnly`, only blended batches are culled (the GPU culls the rest).
    */
-  cullCpu(list, params, bounds, transparent, forward, forwardOnly, transparentOnly = false) {
+  cullCpu(list, params, bounds, transparent, forward, forwardOnly, transparentOnly = false, ground, overlay) {
     if (bounds) {
       bounds[0] = bounds[1] = bounds[2] = Number.POSITIVE_INFINITY;
       bounds[3] = bounds[4] = bounds[5] = Number.NEGATIVE_INFINITY;
@@ -735,6 +856,10 @@ class InstanceStore {
     list.cullView = -1;
     this.transparentCount = 0;
     this.forwardOnlyCount = 0;
+    this.groundCount = 0;
+    const layers = this.layers;
+    const viewLayers = params.layers ?? 4294967295;
+    const hiddenBits = params.hidden;
     const batches = this.batches;
     for (let b = 0; b < batches.length; b++) {
       batches[b].scratchCount = 0;
@@ -743,16 +868,25 @@ class InstanceStore {
     const f = this.f32;
     const u32 = this.u32;
     const mask = InstanceFlags.Visible | params.require;
+    const shadowOnly = (params.require & InstanceFlags.Caster) !== 0 ? InstanceFlags.ShadowOnly : 0;
     const eye = params.eye;
     const sphere = scratchSphere;
     for (let s = 0; s < this.high; s++) {
       const assignment = this.batchOf[s];
       if (assignment === -1) continue;
       const flags = u32[s * INSTANCE_FLOATS + 13];
-      if ((flags & mask) !== mask) {
+      if (((flags & shadowOnly ? flags | InstanceFlags.Visible : flags) & mask) !== mask) {
         if ((flags & InstanceFlags.Visible) === 0) list.hidden++;
         continue;
       }
+      if ((layers[s] & viewLayers) === 0) {
+        list.culled++;
+        continue;
+      }
+      if (hiddenBits !== void 0 && (hiddenBits[s >>> 5] & 1 << (s & 31)) !== 0) {
+        list.hidden++;
+        continue;
+      }
       let set;
       let b = assignment;
       if (assignment <= -2) {
@@ -765,6 +899,7 @@ class InstanceStore {
         list.pending++;
         continue;
       }
+      if (batch.ground && (params.require !== 0 || !ground)) continue;
       if (batch.transparent && (params.require !== 0 || !transparent)) continue;
       if (flags & InstanceFlags.Skinned) sphereOfSlot(sphere, this, s, flags, batch.mesh.bounds);
       else slotSphere(sphere, f, s * INSTANCE_FLOATS, batch.mesh.bounds);
@@ -814,6 +949,10 @@ class InstanceStore {
           if (sphere[k] + sphere[3] > bounds[k + 3]) bounds[k + 3] = sphere[k] + sphere[3];
         }
       }
+      if (batch.ground) {
+        this.pushGround(entry, b);
+        continue;
+      }
       if (batch.transparent) {
         this.pushTransparent(entry, b, eye, forward);
         list.visible++;
@@ -839,6 +978,7 @@ class InstanceStore {
     }
     this.pack(list);
     if (transparent) this.packTransparent(transparent);
+    if (ground) this.packGround(ground, overlay);
     if (forwardOnly) {
       for (const batch of this.batches) {
         const n = batch.forwardCount;
@@ -859,12 +999,16 @@ class InstanceStore {
     const u32 = this.u32;
     const eye = params.eye;
     const sphere = scratchSphere;
+    const viewLayers = params.layers ?? 4294967295;
+    const hiddenBits = params.hidden;
     for (const batch of this.batches) {
-      if (!batch.transparent || !batch.ready || batch.memberCount === 0) continue;
+      if (!batch.transparent || batch.ground || !batch.ready || batch.memberCount === 0) continue;
       for (let m = 0; m < batch.memberCount; m++) {
         const s = batch.members[m];
         const flags = u32[s * INSTANCE_FLOATS + 13];
         if ((flags & InstanceFlags.Visible) === 0) continue;
+        if ((this.layers[s] & viewLayers) === 0) continue;
+        if (hiddenBits !== void 0 && (hiddenBits[s >>> 5] & 1 << (s & 31)) !== 0) continue;
         sphereOfSlot(sphere, this, s, flags, batch.mesh.bounds);
         if (params.planes && !sphereInFrustum(params.planes, sphere)) continue;
         if (flags & InstanceFlags.Range && eye) {
@@ -879,6 +1023,125 @@ class InstanceStore {
     }
     this.packTransparent(list);
   }
+  /**
+   * Ground-only CPU cull over ground batches' members (0057), for views the GPU culls: the ground
+   * list is always built on the CPU, in (band, order) order.
+   */
+  cullGroundMembers(list, params, overlay) {
+    this.groundCount = 0;
+    const u32 = this.u32;
+    const sphere = scratchSphere;
+    const viewLayers = params.layers ?? 4294967295;
+    const hiddenBits = params.hidden;
+    for (const batch of this.batches) {
+      if (!batch.ground || !batch.ready || batch.memberCount === 0) continue;
+      for (let m = 0; m < batch.memberCount; m++) {
+        const s = batch.members[m];
+        const flags = u32[s * INSTANCE_FLOATS + 13];
+        if ((flags & InstanceFlags.Visible) === 0) continue;
+        if ((this.layers[s] & viewLayers) === 0) continue;
+        if (hiddenBits !== void 0 && (hiddenBits[s >>> 5] & 1 << (s & 31)) !== 0) continue;
+        slotSphere(sphere, this.f32, s * INSTANCE_FLOATS, batch.mesh.bounds);
+        if (params.planes && !sphereInFrustum(params.planes, sphere)) continue;
+        this.pushGround(s, batch.index);
+      }
+    }
+    this.packGround(list, overlay);
+  }
+  pushGround(entry, batch) {
+    const n = this.groundCount;
+    if (n >= this.gSlots.length) {
+      const size = this.gSlots.length * 2;
+      const s = new Uint32Array(size);
+      s.set(this.gSlots);
+      this.gSlots = s;
+      const b = new Int32Array(size);
+      b.set(this.gBatches);
+      this.gBatches = b;
+      const k = new Float64Array(size);
+      k.set(this.gKeys);
+      this.gKeys = k;
+    }
+    this.gSlots[n] = entry;
+    this.gBatches[n] = batch;
+    this.gKeys[n] = this.groundKeys[entry & SLOT_MASK];
+    this.groundCount = n + 1;
+  }
+  /**
+   * Packs visible-list entries (a slot in the low 28 bits, 4 spare bits a pass may use, like an
+   * outline style) into `list`, one draw per batch: for passes that draw chosen slots (0057's
+   * outline mask). `batches` holds each entry's batch index. Skips entries whose batch isn't ready.
+   */
+  packEntries(list, entries, batches, count) {
+    list.length = 0;
+    list.cullView = -1;
+    list.visible = 0;
+    if (count === 0) return;
+    const order = this.gOrder;
+    order.length = count;
+    for (let i = 0; i < count; i++) order[i] = i;
+    order.sort((a, b) => batches[a] - batches[b] || entries[a] - entries[b]);
+    this.reserve(count);
+    let item;
+    for (let k = 0; k < count; k++) {
+      const i = order[k];
+      const batch = this.batches[batches[i]];
+      if (!batch?.ready) continue;
+      if (!item || item.batch !== batch) {
+        item = this.item(list, batch);
+        item.first = this.visibleCount;
+        item.count = 0;
+      }
+      this.visible[this.visibleCount++] = entries[i];
+      item.count++;
+      list.visible++;
+    }
+  }
+  /**
+   * Sorts this cull's ground instances by (level, band, order), then batch; runs of a batch share a
+   * draw. With `overlay`, bands from OVERLAY_BAND up go there instead (0058).
+   */
+  packGround(list, overlay) {
+    list.length = 0;
+    list.cullView = -1;
+    if (overlay) {
+      overlay.length = 0;
+      overlay.cullView = -1;
+      overlay.visible = 0;
+    }
+    const n = this.groundCount;
+    list.visible = n;
+    if (n === 0) return;
+    const order = this.gOrder;
+    order.length = n;
+    for (let i = 0; i < n; i++) order[i] = i;
+    const keys = this.gKeys;
+    const batches = this.gBatches;
+    const slots = this.gSlots;
+    order.sort((a, b) => keys[a] - keys[b] || batches[a] - batches[b] || slots[a] - slots[b]);
+    this.reserve(n);
+    let item;
+    let into = list;
+    for (let k = 0; k < n; k++) {
+      const i = order[k];
+      const batch = this.batches[batches[i]];
+      if (overlay && into === list && bandOfKey(keys[i]) >= OVERLAY_BAND) {
+        into = overlay;
+        item = void 0;
+      }
+      if (!item || item.batch !== batch) {
+        item = this.item(into, batch);
+        item.first = this.visibleCount;
+        item.count = 0;
+      }
+      this.visible[this.visibleCount++] = slots[i];
+      item.count++;
+      if (into === overlay) {
+        overlay.visible++;
+        list.visible--;
+      }
+    }
+  }
   /**
    * CPU culling with positional arguments: planes, flag mask, bounds, transparent list, eye, view
    * direction, and the deferred forward-only list. LOD selects fresh (no hysteresis state).
@@ -970,7 +1233,8 @@ class InstanceStore {
     const n = batch.memberCount;
     if (n === 0 || n !== batch.count || n > 8) return true;
     for (let i = 0; i < n; i++) {
-      if (this.u32[batch.members[i] * INSTANCE_FLOATS + 13] & InstanceFlags.Visible) return true;
+      const flags = this.u32[batch.members[i] * INSTANCE_FLOATS + 13];
+      if (flags & (InstanceFlags.Visible | InstanceFlags.ShadowOnly)) return true;
     }
     return false;
   }
@@ -1040,12 +1304,12 @@ class InstanceStore {
       label,
       layout: this.layout,
       entries: [
-        { binding: 0, resource: { buffer: this.instanceBuffer.buffer } },
-        { binding: 1, resource: { buffer: visible } },
-        { binding: 2, resource: { buffer: this.prevBuffer.buffer } },
-        { binding: 3, resource: { buffer: this.deform.recordBuffer.buffer } },
-        { binding: 4, resource: { buffer: this.deform.poseBuffer.buffer } },
-        { binding: 5, resource: { buffer: this.deform.vertexBuffer.buffer } }
+        { binding: 0, resource: this.instanceBuffer.resource() },
+        { binding: 1, resource: visible },
+        { binding: 2, resource: this.prevBuffer.resource() },
+        { binding: 3, resource: this.deform.recordBuffer.resource() },
+        { binding: 4, resource: this.deform.poseBuffer.resource() },
+        { binding: 5, resource: this.deform.vertexBuffer.resource() }
       ]
     });
   }
@@ -1058,14 +1322,14 @@ class InstanceStore {
     const deformKey = `${d.recordBuffer.version}/${d.poseBuffer.version}/${d.vertexBuffer.version}`;
     const key = `${this.instanceBuffer.version}/${this.visibleBuffer.version}/${this.prevBuffer.version}/${deformKey}/${this.gpu.generation}`;
     if (!this.bindGroup || this.bound !== key) {
-      this.bindGroup = this.createBindGroup("instances", this.visibleBuffer.buffer);
+      this.bindGroup = this.createBindGroup("instances", this.visibleBuffer.resource());
       this.bound = key;
     }
     const g = this.gpuVisible;
     if (g) {
       const gkey = `${this.instanceBuffer.version}/${g.version}/${this.prevBuffer.version}/${deformKey}/${this.gpu.generation}`;
       if (!this.gpuBindGroup || this.gpuBound !== gkey) {
-        this.gpuBindGroup = this.createBindGroup("instances/gpu-culled", g.buffer);
+        this.gpuBindGroup = this.createBindGroup("instances/gpu-culled", { buffer: g.buffer });
         this.gpuBound = gkey;
       }
     }
@@ -1094,25 +1358,19 @@ function idOf(o) {
   }
   return id;
 }
-function createInstanceLayout(gpu) {
+function createInstanceLayout(gpu, store) {
+  const VF = GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT;
+  const V = GPUShaderStage.VERTEX;
   return gpu.layouts.bindGroupLayout({
     label: "instances",
     entries: [
-      {
-        binding: 0,
-        visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
-        buffer: { type: "read-only-storage" }
-      },
-      {
-        binding: 1,
-        visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
-        buffer: { type: "read-only-storage" }
-      },
-      { binding: 2, visibility: GPUShaderStage.VERTEX, buffer: { type: "read-only-storage" } },
+      store.instanceBuffer.layoutEntry(0, VF),
+      store.visibleBuffer.layoutEntry(1, VF),
+      store.prevBuffer.layoutEntry(2, V),
       // Deform records, poses (joint matrices, morph weights), and per-vertex deform data.
-      { binding: 3, visibility: GPUShaderStage.VERTEX, buffer: { type: "read-only-storage" } },
-      { binding: 4, visibility: GPUShaderStage.VERTEX, buffer: { type: "read-only-storage" } },
-      { binding: 5, visibility: GPUShaderStage.VERTEX, buffer: { type: "read-only-storage" } }
+      store.deform.recordBuffer.layoutEntry(3, V),
+      store.deform.poseBuffer.layoutEntry(4, V),
+      store.deform.vertexBuffer.layoutEntry(5, V)
     ]
   });
 }
@@ -1120,7 +1378,16 @@ const Instances = defineResource("render/Instances", {
   description: "The persistent GPU instance buffer: one slot per Mesh3d entity."
 });
 function tableChanged(table, since) {
-  return table.lastStructural > since || table.lastChanged(GlobalTransform) > since || table.lastChanged(Mesh3d) > since || table.lastChanged(ComputedVisibility) > since || table.lastChanged(InstanceSlot) > since || table.has(MeshMaterial) && table.lastChanged(MeshMaterial) > since || table.has(Lod) && table.lastChanged(Lod) > since || table.has(VisibilityRange) && table.lastChanged(VisibilityRange) > since || table.has(InstanceData) && table.lastChanged(InstanceData) > since;
+  return table.lastStructural > since || table.lastChanged(GlobalTransform) > since || table.lastChanged(Mesh3d) > since || table.lastChanged(ComputedVisibility) > since || table.lastChanged(InstanceSlot) > since || table.has(MeshMaterial) && table.lastChanged(MeshMaterial) > since || table.has(Lod) && table.lastChanged(Lod) > since || table.has(VisibilityRange) && table.lastChanged(VisibilityRange) > since || table.has(InstanceData) && table.lastChanged(InstanceData) > since || table.has(RenderLayers) && table.lastChanged(RenderLayers) > since || table.has(GroundLayer) && table.lastChanged(GroundLayer) > since;
+}
+function casts(flags) {
+  return (flags & InstanceFlags.Caster) !== 0 && (flags & (InstanceFlags.Visible | InstanceFlags.ShadowOnly)) !== 0;
+}
+function groundKey(band, order, level = 0) {
+  return (level + 16) * 281474976710656 + (band + 32768) * 4294967296 + (order + 2147483648);
+}
+function bandOfKey(key) {
+  return Math.floor(key / 4294967296) % 65536 - 32768;
 }
 let zeros = new Uint32Array(1024);
 function zeroTicks(n) {
@@ -1130,19 +1397,6 @@ function zeroTicks(n) {
 const DeformPath = defineResource("render/DeformPath", {
   description: "Present when skinning and morph targets (skinningPlugin) are installed."
 });
-const warnedDeforms = /* @__PURE__ */ new WeakSet();
-function warnNoDeforms(world) {
-  if (warnedDeforms.has(world)) return;
-  warnedDeforms.add(world);
-  world.tryResource(LogResource)?.log(
-    "warn",
-    "An entity has SkinnedMesh or MorphWeights, but skinningPlugin isn't installed; it draws in its rest pose",
-    {
-      code: "render/feature-missing",
-      hint: "Add skinningPlugin from '@aethervtt/shard-render' (forwardPlugin includes it)."
-    }
-  );
-}
 const prepareInstances = defineSystem({
   name: "render/prepare-instances",
   description: "Assigns instance slots, writes changed transforms and batches, and uploads dirty slots.",
@@ -1156,7 +1410,13 @@ const prepareInstances = defineSystem({
     const assets = world.resource(GpuAssetsResource);
     assets.beginFrame();
     store.beginFrame();
+    const dev = world.tryResource(DevMode)?.enabled ?? false;
+    if (dev !== store.dev) {
+      store.dev = dev;
+      store.missingMaterial.set({ baseColor: dev ? [1, 0, 1, 1] : [0.5, 0.5, 0.5, 1] });
+    }
     const deforms = world.hasResource(DeformPath);
+    const cutaways = world.hasResource(CutawayPath);
     const since = ctx.lastRunTick;
     let hidden = 0;
     let rows = 0;
@@ -1191,9 +1451,24 @@ const prepareInstances = defineSystem({
       const dataY = hasData ? table.column(InstanceData, "y") : void 0;
       const dataChanged = hasData ? table.changedTicks(InstanceData) : zeroTicks(n);
       const vis = table.column(ComputedVisibility, "visible");
+      const hiddenFlag = table.has(ShadowWhenHidden) ? InstanceFlags.ShadowOnly : 0;
+      const layerMasks = table.has(RenderLayers) ? table.column(RenderLayers, "mask") : void 0;
+      const hasGround = table.has(GroundLayer);
+      const bands = hasGround ? table.column(GroundLayer, "band") : void 0;
+      const orders = hasGround ? table.column(GroundLayer, "order") : void 0;
+      const levels = hasGround ? table.column(GroundLayer, "level") : void 0;
       const deformed = table.has(SkinnedMesh) || table.has(MorphWeights);
-      if (deformed && !deforms) warnNoDeforms(world);
-      const tableFlags = (deforms && table.has(SkinnedMesh) ? InstanceFlags.Skinned : 0) | (deforms && table.has(MorphWeights) ? InstanceFlags.Morph : 0) | (table.has(NotShadowCaster) ? 0 : InstanceFlags.Caster) | (table.has(NotShadowReceiver) ? 0 : InstanceFlags.Receiver) | (hasRange ? InstanceFlags.Range : 0) | (hasLod ? InstanceFlags.Lod : 0);
+      if (deformed && !deforms)
+        warnFeatureMissing(
+          world,
+          "An entity has SkinnedMesh or MorphWeights",
+          "skinningPlugin",
+          "it draws in its rest pose"
+        );
+      const cut = table.has(Cutaway);
+      if (cut && !cutaways)
+        warnFeatureMissing(world, "An entity has Cutaway", "cutawayPlugin", "it draws whole");
+      const tableFlags = (cut && cutaways ? InstanceFlags.Cutaway : 0) | (deforms && table.has(SkinnedMesh) ? InstanceFlags.Skinned : 0) | (deforms && table.has(MorphWeights) ? InstanceFlags.Morph : 0) | (table.has(NotShadowCaster) ? 0 : InstanceFlags.Caster) | (table.has(NotShadowReceiver) ? 0 : InstanceFlags.Receiver) | (hasRange ? InstanceFlags.Range : 0) | (hasLod ? InstanceFlags.Lod : 0);
       let u32 = store.u32;
       let slotFlags = store.flags;
       for (let i = 0; i < n; i++) {
@@ -1209,10 +1484,15 @@ const prepareInstances = defineSystem({
         const o = slot * INSTANCE_FLOATS;
         const visible = vis[i] !== 0;
         if (!visible) hidden++;
-        const flags = tableFlags | (visible ? InstanceFlags.Visible : 0);
+        const flags = tableFlags | (visible ? InstanceFlags.Visible : hiddenFlag);
         const oldFlags = slotFlags[slot];
         if (fresh || gChanged[i] > since) store.moveSlot(slot, g, i * 12, fresh);
-        if (fresh || ((oldFlags ^ flags) & InstanceFlags.Lod) !== 0 || meshChanged[i] > since || materialChanged[i] > since || lodChanged[i] > since) {
+        store.setLayers(slot, layerMasks ? layerMasks[i] : 1);
+        const onOffGround = store.setGround(
+          slot,
+          hasGround ? groundKey(bands[i], orders[i], levels[i]) : Number.NaN
+        );
+        if (fresh || onOffGround || ((oldFlags ^ flags) & InstanceFlags.Lod) !== 0 || meshChanged[i] > since || materialChanged[i] > since || lodChanged[i] > since) {
           store.meshRefs[slot] = meshRefs[i] ?? null;
           store.materialRefs[slot] = materialRefs?.[i] ?? null;
           store.lods[slot] = hasLod ? {
@@ -1223,9 +1503,13 @@ const prepareInstances = defineSystem({
           resolveSlot(store, slot, meshes, materials);
         }
         if (oldFlags !== flags) {
-          u32[o + 13] = flags;
+          u32[o + 13] = recordFlags(flags, store.layers[slot]);
           slotFlags[slot] = flags;
+          if ((oldFlags ^ flags) & InstanceFlags.Cutaway)
+            store.countCutaway(slot, flags & InstanceFlags.Cutaway ? 1 : -1);
           store.markDirty(slot);
+          if ((oldFlags ^ flags) & (InstanceFlags.Visible | InstanceFlags.Caster | InstanceFlags.ShadowOnly))
+            store.shadowEpoch++;
         }
         if (fresh || rangeChanged[i] > since) {
           if (hasRange) store.setRange(slot, rangeStart[i], rangeEnd[i]);
@@ -1240,7 +1524,18 @@ const prepareInstances = defineSystem({
     store.hiddenCount = hidden;
     store.drawableCount = rows - store.pending.size;
     if (store.pending.size > 0) {
-      for (const slot of store.pending) resolveSlot(store, slot, meshes, materials);
+      const server = world.tryResource(AssetServerResource);
+      for (const slot of store.pending) {
+        if (server) {
+          const meshRef = store.meshRefs[slot];
+          if (meshRef?.guid !== void 0 && !meshes.has(meshRef.guid))
+            server.missing(meshRef, "Mesh");
+          const materialRef = store.materialRefs[slot];
+          if (materialRef?.guid !== void 0 && !materials.has(materialRef.guid))
+            server.missing(materialRef, "Material");
+        }
+        resolveSlot(store, slot, meshes, materials);
+      }
     }
     for (const batch of store.batches) {
       if (batch.count === 0) continue;
@@ -1287,9 +1582,17 @@ function resolveSlot(store, slot, meshes, materials) {
     return;
   }
   store.pending.delete(slot);
+  const ground = !Number.isNaN(store.groundKeys[slot]);
+  const drawn = mesh.missing ? store.missingMaterial : material;
   store.assign(
     slot,
-    store.batchFor(mesh, material, meshRef?.guid, materialRef?.guid ?? void 0).index
+    store.batchFor(
+      mesh,
+      drawn,
+      meshRef?.guid,
+      mesh.missing ? void 0 : materialRef?.guid ?? void 0,
+      ground
+    ).index
   );
 }
 function observeInstanceRemovals(world) {
@@ -1303,6 +1606,7 @@ function observeInstanceRemovals(world) {
   });
 }
 export {
+  CUTAWAY_BIT,
   DeformPath,
   INSTANCE_BYTES,
   INSTANCE_FLOATS,
@@ -1311,6 +1615,8 @@ export {
   InstanceSlot,
   InstanceStore,
   Instances,
+  LAYER_BITS,
+  LAYER_SHIFT,
   LOD_BIT,
   LOD_UNSET,
   Lod,
@@ -1322,13 +1628,16 @@ export {
   NotShadowCaster,
   NotShadowReceiver,
   SLOT_MASK,
+  ShadowWhenHidden,
   SkinnedMesh,
   VisibilityRange,
   createDrawList,
   createInstanceLayout,
+  groundKey,
   lodSize,
   observeInstanceRemovals,
   prepareInstances,
+  recordFlags,
   selectLod,
   slotSphere,
   sphereInFrustum