@aethervtt/shard-render 0.1.0 → 0.2.0

package/dist/foliage.js

@@ -0,0 +1,1027 @@
+import {
+  defineResource,
+  defineSystem,
+  PostUpdate,
+  ProfilerResource,
+  ShardError
+} from "@aethervtt/shard-core";
+import {
+  definePlugin,
+  PerfBudgets,
+  PerfScenario,
+  scenarioSliceMs
+} from "@aethervtt/shard-runtime";
+import { Materials, Meshes } from "./assets.js";
+import { addRenderFeatures } from "./features.js";
+import {
+  CoveredGpuTime,
+  FOLIAGE_SPAN_KEY,
+  FoliageBudget,
+  FoliageController
+} from "./foliage-budget.js";
+import { FoliagePath } from "./foliage-path.js";
+import {
+  CHUNK_FLOATS,
+  CULL_PARAMS_FLOATS,
+  FOLIAGE_SHADERS,
+  MAX_FOLIAGE_MESHES,
+  PATCH_FLOATS,
+  PLACE_PARAMS_BYTES
+} from "./foliage-shaders.js";
+import {
+  ForwardStateResource,
+  INTERIOR_DEFINES,
+  PASS_GBUFFER,
+  PASS_OPAQUE,
+  sceneColor,
+  VERTEX_BUFFERS,
+  viewBindGroup
+} from "./forward.js";
+import { GpuAssetsResource } from "./gpu-assets.js";
+import { RenderPhase } from "./graph.js";
+import { materialVariant, typeOrdinal, variantBlend, variantCull } from "./material-pipelines.js";
+import { Graph, Shaders } from "./plugin.js";
+import { registerShaders } from "./shaders.js";
+import { cameraOf } from "./view.js";
+const scratchParams = new ArrayBuffer(PLACE_PARAMS_BYTES);
+const paramsU32 = new Uint32Array(scratchParams);
+const paramsI32 = new Int32Array(scratchParams);
+const paramsF32 = new Float32Array(scratchParams);
+const cullData = new Float32Array(CULL_PARAMS_FLOATS);
+const cullU32 = new Uint32Array(cullData.buffer);
+const drawData = new Float32Array(8);
+class FoliageLayer {
+  options;
+  perChunk;
+  /** What draws: each mesh's levels in order (`meshes[m]` then `lods[m]`), and where each mesh's start. */
+  drawables = [];
+  levels;
+  /** Chunks in the layer: their inputs (kept to place again after growth or device loss). */
+  chunks = /* @__PURE__ */ new Map();
+  /** Per slot: chunk → origin-relative world rows (12), bounds (min xyz, size xyz), active. */
+  records = new Float32Array(CHUNK_FLOATS * 8);
+  slots = 0;
+  free = [];
+  pending = [];
+  /** Buffers, made in the place node. */
+  instances;
+  chunkBuffer;
+  meshInfo;
+  levelBuffer;
+  /** Slots the instance buffer holds, and its device generation. */
+  capacitySlots = 0;
+  generation = -1;
+  views = /* @__PURE__ */ new Map();
+  /** Largest mesh bounding radius (m, unscaled): culling's sphere. */
+  meshRadius = 1;
+  disposed = false;
+  constructor(options) {
+    if (options.meshes.length === 0 || options.meshes.length > MAX_FOLIAGE_MESHES) {
+      throw new ShardError(
+        "render/foliage-meshes",
+        `A foliage layer draws 1 to ${MAX_FOLIAGE_MESHES} meshes, not ${options.meshes.length}`,
+        { hint: "Fewer variants: 4\u20138 read as unique once scaled and rotated." }
+      );
+    }
+    this.options = options;
+    this.perChunk = Math.max(1, options.cells * options.cells);
+    this.levels = new Uint32Array(options.meshes.length * 2);
+    for (let m = 0; m < options.meshes.length; m++) {
+      const lods = options.lods?.[m] ?? [];
+      this.levels[m * 2] = this.drawables.length;
+      this.levels[m * 2 + 1] = 1 + lods.length;
+      this.drawables.push(options.meshes[m], ...lods);
+    }
+  }
+  /** A free chunk slot. */
+  allocate() {
+    const slot = this.free.length > 0 ? this.free.pop() : this.slots++;
+    const need = (slot + 1) * CHUNK_FLOATS;
+    if (this.records.length < need) {
+      const grown = new Float32Array(Math.max(need, this.records.length * 2));
+      grown.set(this.records);
+      this.records = grown;
+    }
+    return slot;
+  }
+  /** Places a chunk in a slot (on the GPU, in the next frame's place pass). */
+  setChunk(slot, chunk) {
+    const n = chunk.grid * chunk.grid;
+    if (chunk.positions.length < n * 3 || chunk.normals.length < n * 3 || chunk.density.length < n) {
+      throw new ShardError(
+        "render/foliage-patch",
+        `A foliage chunk's patch has fewer than ${n} vertices`,
+        {
+          hint: "positions and normals: 3 floats per grid point; density: 1."
+        }
+      );
+    }
+    this.chunks.set(slot, chunk);
+    let x0 = Infinity;
+    let y0 = Infinity;
+    let z0 = Infinity;
+    let x1 = -Infinity;
+    let y1 = -Infinity;
+    let z1 = -Infinity;
+    const p = chunk.positions;
+    for (let i = 0; i < n; i++) {
+      x0 = Math.min(x0, p[i * 3]);
+      y0 = Math.min(y0, p[i * 3 + 1]);
+      z0 = Math.min(z0, p[i * 3 + 2]);
+      x1 = Math.max(x1, p[i * 3]);
+      y1 = Math.max(y1, p[i * 3 + 1]);
+      z1 = Math.max(z1, p[i * 3 + 2]);
+    }
+    const r = this.records;
+    const o = slot * CHUNK_FLOATS;
+    r[o + 12] = x0 - 0.01;
+    r[o + 13] = y0 - 0.01;
+    r[o + 14] = z0 - 0.01;
+    r[o + 15] = 0;
+    r[o + 16] = x1 - x0 + 0.02;
+    r[o + 17] = y1 - y0 + 0.02;
+    r[o + 18] = z1 - z0 + 0.02;
+    this.queue(slot, chunk);
+  }
+  queue(slot, chunk) {
+    for (const p of this.pending) {
+      if (p.slot === slot) {
+        p.chunk = chunk;
+        return;
+      }
+    }
+    this.pending.push({ slot, chunk });
+  }
+  /** Frees a slot: its instances stop drawing at once. */
+  removeChunk(slot) {
+    if (!this.chunks.delete(slot)) return;
+    this.records[slot * CHUNK_FLOATS + 15] = 0;
+    for (let i = this.pending.length - 1; i >= 0; i--)
+      if (this.pending[i].slot === slot) this.pending.splice(i, 1);
+    this.free.push(slot);
+  }
+  /**
+   * The chunk's frame in the world, origin-relative, as an affine's three rows (12 floats,
+   * row-major: rotation and translation). Set it every frame the frame moves (an origin shift).
+   */
+  setTransform(slot, rows) {
+    const o = slot * CHUNK_FLOATS;
+    for (let i = 0; i < 12; i++) this.records[o + i] = rows[i];
+  }
+  /** Chunk slots in use. */
+  get chunkCount() {
+    return this.chunks.size;
+  }
+  /** Instances this layer can hold. */
+  get capacity() {
+    return this.capacitySlots * this.perChunk;
+  }
+  /** The last read-back instance counts for a camera: in view, and casting shadows. */
+  visible(view) {
+    const v = this.views.get(view);
+    if (!v) return { drawn: 0, shadows: 0 };
+    const m = this.drawables.length;
+    let drawn = 0;
+    let shadows = 0;
+    for (let i = 0; i < m; i++) {
+      drawn += v.read_[i] ?? 0;
+      shadows += v.read_[m + i] ?? 0;
+    }
+    return { drawn, shadows };
+  }
+  /**
+   * The last read-back counts per drawable for a camera (`drawables[d]`: a mesh or one of its
+   * LODs), in view and casting shadows.
+   */
+  visibleByDrawable(view) {
+    const v = this.views.get(view);
+    const m = this.drawables.length;
+    const drawn = [];
+    const shadows = [];
+    for (let i = 0; i < m; i++) {
+      drawn.push(v?.read_[i] ?? 0);
+      shadows.push(v?.read_[m + i] ?? 0);
+    }
+    return { drawn, shadows };
+  }
+  /** Slot records for the GPU this frame. */
+  get chunkRecords() {
+    return this.records;
+  }
+  get slotCount() {
+    return this.slots;
+  }
+  /** Releases its GPU buffers (the layer stops drawing). */
+  dispose() {
+    this.disposed = true;
+    this.instances?.destroy();
+    this.chunkBuffer?.destroy();
+    this.meshInfo?.destroy();
+    this.levelBuffer?.destroy();
+    for (const v of this.views.values()) {
+      v.visible.destroy();
+      v.args.destroy();
+      v.classes.destroy();
+      v.counts.destroy();
+      v.params.destroy();
+      v.draw.destroy();
+      v.readback?.destroy();
+    }
+    this.views.clear();
+  }
+}
+class FoliageLayerSet {
+  layers = /* @__PURE__ */ new Set();
+  /** Density and range under the budget (0075, `FoliageBudget`): full detail without a target. */
+  steer = new FoliageController();
+  /** Foliage's GPU time a frame: every `gpu:foliage/*` pass (0074's covers rule). */
+  gpuTime = new CoveredGpuTime(FOLIAGE_SPAN_KEY);
+  /** The scenario slice the target came from, kept until the scenario or budgets change. */
+  sliceFor = null;
+  sliceData;
+  sliceMs = 0;
+  /** The shared GPU objects (pipelines, staging buffers), made on first use. */
+  gpu;
+  add(layer) {
+    this.layers.add(layer);
+    return layer;
+  }
+  remove(layer) {
+    if (!this.layers.delete(layer)) return;
+    layer.dispose();
+  }
+  /** Releases every layer and the shared buffers (the app is going away). */
+  dispose() {
+    for (const layer of this.layers) layer.dispose();
+    this.layers.clear();
+    this.gpu?.params.destroy();
+    this.gpu?.patch.destroy();
+    this.gpu?.avoid.destroy();
+    this.gpu = void 0;
+  }
+}
+const FoliageLayers = defineResource("render/FoliageLayers", {
+  description: "GPU foliage layers (0045): instances placed, culled and drawn on the GPU.",
+  init: () => new FoliageLayerSet()
+});
+function foliageGpu(gpu, set) {
+  if (set.gpu && set.gpu.generation === gpu.generation) return set.gpu;
+  const d = gpu.device;
+  const storage = (binding, type, visibility) => ({
+    binding,
+    visibility,
+    buffer: { type }
+  });
+  const C = GPUShaderStage.COMPUTE;
+  const V = GPUShaderStage.VERTEX;
+  set.gpu = {
+    generation: gpu.generation,
+    placeLayout: gpu.layouts.bindGroupLayout({
+      label: "foliage/place",
+      entries: [
+        { binding: 0, visibility: C, buffer: { type: "uniform", hasDynamicOffset: true } },
+        storage(1, "read-only-storage", C),
+        storage(2, "read-only-storage", C),
+        storage(3, "storage", C)
+      ]
+    }),
+    cullLayout: gpu.layouts.bindGroupLayout({
+      label: "foliage/cull",
+      entries: [
+        { binding: 0, visibility: C, buffer: { type: "uniform" } },
+        storage(1, "read-only-storage", C),
+        storage(2, "read-only-storage", C),
+        storage(3, "storage", C),
+        storage(4, "storage", C),
+        storage(5, "read-only-storage", C),
+        storage(6, "storage", C),
+        storage(7, "storage", C),
+        storage(8, "read-only-storage", C)
+      ]
+    }),
+    drawLayout: gpu.layouts.bindGroupLayout({
+      label: "foliage/draw",
+      entries: [
+        storage(0, "read-only-storage", V),
+        storage(1, "read-only-storage", V),
+        storage(2, "read-only-storage", V),
+        { binding: 3, visibility: V, buffer: { type: "uniform" } }
+      ]
+    }),
+    place: void 0,
+    reset: void 0,
+    cull: void 0,
+    scan: void 0,
+    scatter: void 0,
+    params: d.createBuffer({
+      label: "foliage/place-params",
+      size: PLACE_PARAMS_BYTES * 16,
+      usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+    }),
+    paramsSize: PLACE_PARAMS_BYTES * 16,
+    patch: d.createBuffer({
+      label: "foliage/patch",
+      size: 4096,
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST
+    }),
+    patchSize: 4096,
+    avoid: d.createBuffer({
+      label: "foliage/avoid",
+      size: 256,
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST
+    }),
+    avoidSize: 256
+  };
+  return set.gpu;
+}
+function pipelines(ctx, f) {
+  if (f.place && f.reset && f.cull && f.scan && f.scatter) return true;
+  const shaders = ctx.world.resource(Shaders);
+  const gpu = ctx.gpu;
+  const place = shaders.module(gpu, { root: "shard::foliage::place", label: "foliage place" });
+  const cull = shaders.module(gpu, { root: "shard::foliage::cull", label: "foliage cull" });
+  if (!place || !cull) return false;
+  f.place = gpu.pipelines.compute({
+    label: "foliage/place",
+    layout: gpu.layouts.pipelineLayout({
+      label: "foliage/place",
+      bindGroupLayouts: [f.placeLayout]
+    }),
+    compute: { module: place, entryPoint: "place" }
+  });
+  const cullLayout = gpu.layouts.pipelineLayout({
+    label: "foliage/cull",
+    bindGroupLayouts: [f.cullLayout]
+  });
+  f.reset = gpu.pipelines.compute({
+    label: "foliage/reset",
+    layout: cullLayout,
+    compute: { module: cull, entryPoint: "reset" }
+  });
+  f.cull = gpu.pipelines.compute({
+    label: "foliage/classify",
+    layout: cullLayout,
+    compute: { module: cull, entryPoint: "classify" }
+  });
+  f.scan = gpu.pipelines.compute({
+    label: "foliage/scan",
+    layout: cullLayout,
+    compute: { module: cull, entryPoint: "scan" }
+  });
+  f.scatter = gpu.pipelines.compute({
+    label: "foliage/scatter",
+    layout: cullLayout,
+    compute: { module: cull, entryPoint: "scatter" }
+  });
+  return f.place !== void 0 && f.reset !== void 0 && f.cull !== void 0 && f.scan !== void 0 && f.scatter !== void 0;
+}
+function grow(gpu, buffer, size, need, label, usage) {
+  if (need <= size) return { buffer, size };
+  let s = size;
+  while (s < need) s *= 2;
+  buffer.destroy();
+  return { buffer: gpu.device.createBuffer({ label, size: s, usage }), size: s };
+}
+function ensureLayer(gpu, layer, world) {
+  const d = gpu.device;
+  const lost = layer.generation !== gpu.generation;
+  if (lost || layer.slotCount > layer.capacitySlots) {
+    let slots = Math.max(8, layer.capacitySlots);
+    while (slots < layer.slotCount) slots *= 2;
+    if (!lost) layer.instances?.destroy();
+    if (!lost) layer.chunkBuffer?.destroy();
+    layer.instances = d.createBuffer({
+      label: `foliage/${layer.options.label}/instances`,
+      size: slots * layer.perChunk * 16,
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST
+    });
+    layer.chunkBuffer = d.createBuffer({
+      label: `foliage/${layer.options.label}/chunks`,
+      size: slots * CHUNK_FLOATS * 4,
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST
+    });
+    layer.capacitySlots = slots;
+    layer.generation = gpu.generation;
+    layer.views.clear();
+    layer.meshInfo = void 0;
+    layer.levelBuffer = void 0;
+    for (const [slot, chunk] of layer.chunks) layer.pending.push({ slot, chunk });
+    dedupePending(layer);
+  }
+  if (!layer.meshInfo) {
+    layer.meshInfo = d.createBuffer({
+      label: `foliage/${layer.options.label}/meshes`,
+      size: Math.max(16, layer.drawables.length * 16),
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST
+    });
+    layer.levelBuffer = d.createBuffer({
+      label: `foliage/${layer.options.label}/levels`,
+      size: Math.max(16, layer.levels.byteLength),
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST
+    });
+    d.queue.writeBuffer(layer.levelBuffer, 0, layer.levels);
+  }
+  const meshes = world.resource(Meshes);
+  const assets = world.resource(GpuAssetsResource);
+  const info = new Uint32Array(layer.drawables.length * 4);
+  let radius = 0;
+  for (let m = 0; m < layer.drawables.length; m++) {
+    const mesh = meshes.get(layer.drawables[m]);
+    if (!mesh) continue;
+    const gm = assets.mesh(mesh);
+    info[m * 4] = gm.count;
+    info[m * 4 + 2] = 0;
+    info[m * 4 + 3] = gm.baseVertex;
+    const b = mesh.bounds;
+    radius = Math.max(radius, Math.hypot(b[3] - b[0], b[4] - b[1], b[5] - b[2]) / 2);
+  }
+  layer.meshRadius = radius || 1;
+  d.queue.writeBuffer(layer.meshInfo, 0, info);
+  d.queue.writeBuffer(
+    layer.chunkBuffer,
+    0,
+    layer.chunkRecords,
+    0,
+    layer.capacitySlots * CHUNK_FLOATS
+  );
+}
+function dedupePending(layer) {
+  const seen = /* @__PURE__ */ new Set();
+  for (let i = layer.pending.length - 1; i >= 0; i--) {
+    const slot = layer.pending[i].slot;
+    if (seen.has(slot)) layer.pending.splice(i, 1);
+    else seen.add(slot);
+  }
+}
+const PLACE_PER_FRAME = 16;
+function placeChunks(ctx, f, layers) {
+  const gpu = ctx.gpu;
+  const d = gpu.device;
+  const work = [];
+  for (const layer of layers) {
+    while (layer.pending.length > 0 && work.length < PLACE_PER_FRAME)
+      work.push({ layer, p: layer.pending.shift() });
+  }
+  if (work.length === 0) return;
+  let patchFloats = 0;
+  let avoidFloats = 0;
+  for (const w of work) {
+    patchFloats += w.p.chunk.grid * w.p.chunk.grid * PATCH_FLOATS;
+    avoidFloats += w.p.chunk.avoid?.length ?? 0;
+  }
+  const patch = new Float32Array(Math.max(4, patchFloats));
+  const avoid = new Float32Array(Math.max(4, avoidFloats));
+  const params = new Uint8Array(work.length * PLACE_PARAMS_BYTES);
+  let pb = 0;
+  let ab = 0;
+  for (const [k, { layer, p }] of work.entries()) {
+    const c = p.chunk;
+    const n = c.grid * c.grid;
+    for (let i = 0; i < n; i++) {
+      const o = pb + i * PATCH_FLOATS;
+      patch[o] = c.positions[i * 3];
+      patch[o + 1] = c.positions[i * 3 + 1];
+      patch[o + 2] = c.positions[i * 3 + 2];
+      patch[o + 3] = c.normals[i * 3];
+      patch[o + 4] = c.normals[i * 3 + 1];
+      patch[o + 5] = c.normals[i * 3 + 2];
+      patch[o + 6] = c.density[i];
+    }
+    const avoidCount = c.avoid ? c.avoid.length / 4 : 0;
+    if (c.avoid) avoid.set(c.avoid, ab);
+    const opts = layer.options;
+    paramsU32.fill(0);
+    paramsU32[0] = opts.cells;
+    paramsU32[1] = c.grid;
+    paramsU32[2] = p.slot;
+    paramsU32[3] = layer.perChunk;
+    paramsI32[4] = c.cell0[0];
+    paramsI32[5] = c.cell0[1];
+    paramsU32[6] = c.domain >>> 0;
+    paramsU32[7] = opts.seed >>> 0;
+    paramsF32[8] = c.accept;
+    paramsF32[9] = c.jitter;
+    paramsF32[10] = opts.scale[0];
+    paramsF32[11] = opts.scale[1];
+    paramsF32[12] = opts.align;
+    paramsU32[13] = opts.meshes.length;
+    paramsU32[14] = avoidCount;
+    paramsU32[15] = c.radial ? 1 : 0;
+    paramsU32[16] = pb;
+    paramsU32[17] = ab / 4;
+    if (c.radial) {
+      paramsF32[20] = c.radial[0];
+      paramsF32[21] = c.radial[1];
+      paramsF32[22] = c.radial[2];
+    }
+    const r = layer.chunkRecords;
+    const ro = p.slot * CHUNK_FLOATS;
+    paramsF32[24] = r[ro + 12];
+    paramsF32[25] = r[ro + 13];
+    paramsF32[26] = r[ro + 14];
+    paramsF32[28] = r[ro + 16];
+    paramsF32[29] = r[ro + 17];
+    paramsF32[30] = r[ro + 18];
+    for (let m = 0; m < opts.meshes.length; m++) paramsF32[32 + m] = opts.weights[m];
+    params.set(new Uint8Array(scratchParams), k * PLACE_PARAMS_BYTES);
+    pb += n * PATCH_FLOATS;
+    ab += avoidCount * 4;
+  }
+  const usage = GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST;
+  const pg = grow(gpu, f.patch, f.patchSize, patch.byteLength, "foliage/patch", usage);
+  f.patch = pg.buffer;
+  f.patchSize = pg.size;
+  const ag = grow(gpu, f.avoid, f.avoidSize, avoid.byteLength, "foliage/avoid", usage);
+  f.avoid = ag.buffer;
+  f.avoidSize = ag.size;
+  const prm = grow(
+    gpu,
+    f.params,
+    f.paramsSize,
+    params.byteLength,
+    "foliage/place-params",
+    GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+  );
+  f.params = prm.buffer;
+  f.paramsSize = prm.size;
+  d.queue.writeBuffer(f.patch, 0, patch);
+  d.queue.writeBuffer(f.avoid, 0, avoid);
+  d.queue.writeBuffer(f.params, 0, params);
+  const pass = ctx.encoder.beginComputePass({
+    label: "foliage/place",
+    timestampWrites: ctx.timestamps("foliage/place")
+  });
+  pass.setPipeline(f.place);
+  let bound;
+  let group;
+  for (const [k, { layer, p }] of work.entries()) {
+    if (layer !== bound) {
+      group = d.createBindGroup({
+        label: "foliage/place",
+        layout: f.placeLayout,
+        entries: [
+          { binding: 0, resource: { buffer: f.params, size: PLACE_PARAMS_BYTES } },
+          { binding: 1, resource: { buffer: f.patch } },
+          { binding: 2, resource: { buffer: f.avoid } },
+          { binding: 3, resource: { buffer: layer.instances } }
+        ]
+      });
+      bound = layer;
+    }
+    pass.setBindGroup(0, group, [k * PLACE_PARAMS_BYTES]);
+    pass.dispatchWorkgroups(Math.ceil(layer.options.cells * layer.options.cells / 64));
+    const records = layer.chunkRecords;
+    records[p.slot * CHUNK_FLOATS + 15] = 1;
+    d.queue.writeBuffer(
+      layer.chunkBuffer,
+      p.slot * CHUNK_FLOATS * 4,
+      records,
+      p.slot * CHUNK_FLOATS,
+      CHUNK_FLOATS
+    );
+  }
+  pass.end();
+}
+function viewBuffers(gpu, f, layer, name) {
+  const capacity = layer.capacity;
+  const drawables = layer.drawables.length;
+  let v = layer.views.get(name);
+  if (v && v.capacity === capacity && v.drawables === drawables && v.generation === gpu.generation)
+    return v;
+  if (v) {
+    v.visible.destroy();
+    v.args.destroy();
+    v.classes.destroy();
+    v.counts.destroy();
+    v.params.destroy();
+    v.draw.destroy();
+    v.readback?.destroy();
+  }
+  const d = gpu.device;
+  v = {
+    // The camera's list and its shadow list, each at most every instance.
+    visible: d.createBuffer({
+      label: `foliage/${layer.options.label}/visible/${name}`,
+      size: Math.max(16, 2 * capacity * 4),
+      usage: GPUBufferUsage.STORAGE
+    }),
+    args: d.createBuffer({
+      label: `foliage/${layer.options.label}/args/${name}`,
+      size: Math.max(16, 2 * drawables * 20),
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT | GPUBufferUsage.COPY_SRC
+    }),
+    classes: d.createBuffer({
+      label: `foliage/${layer.options.label}/classes/${name}`,
+      size: Math.max(16, capacity * 4),
+      usage: GPUBufferUsage.STORAGE
+    }),
+    counts: d.createBuffer({
+      label: `foliage/${layer.options.label}/counts/${name}`,
+      size: Math.max(16, 2 * drawables * 4),
+      usage: GPUBufferUsage.STORAGE
+    }),
+    params: d.createBuffer({
+      label: `foliage/${layer.options.label}/cull/${name}`,
+      size: CULL_PARAMS_FLOATS * 4,
+      usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+    }),
+    draw: d.createBuffer({
+      label: `foliage/${layer.options.label}/draw/${name}`,
+      size: 32,
+      usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+    }),
+    cullGroup: void 0,
+    drawGroup: void 0,
+    capacity,
+    drawables,
+    generation: gpu.generation,
+    culled: -1,
+    read_: new Uint32Array(2 * drawables),
+    reading: false,
+    readback: void 0,
+    read: -READBACK_EVERY
+  };
+  v.cullGroup = d.createBindGroup({
+    label: "foliage/cull",
+    layout: f.cullLayout,
+    entries: [
+      { binding: 0, resource: { buffer: v.params } },
+      { binding: 1, resource: { buffer: layer.instances } },
+      { binding: 2, resource: { buffer: layer.chunkBuffer } },
+      { binding: 3, resource: { buffer: v.visible } },
+      { binding: 4, resource: { buffer: v.args } },
+      { binding: 5, resource: { buffer: layer.meshInfo } },
+      { binding: 6, resource: { buffer: v.classes } },
+      { binding: 7, resource: { buffer: v.counts } },
+      { binding: 8, resource: { buffer: layer.levelBuffer } }
+    ]
+  });
+  v.drawGroup = d.createBindGroup({
+    label: "foliage/draw",
+    layout: f.drawLayout,
+    entries: [
+      { binding: 0, resource: { buffer: layer.instances } },
+      { binding: 1, resource: { buffer: v.visible } },
+      { binding: 2, resource: { buffer: layer.chunkBuffer } },
+      { binding: 3, resource: { buffer: v.draw } }
+    ]
+  });
+  layer.views.set(name, v);
+  return v;
+}
+const DEFAULT_LODS = [0.3, 0.6];
+const READBACK_EVERY = 30;
+function cullLayer(ctx, f, layer, cam, frame, steer) {
+  const gpu = ctx.gpu;
+  const v = viewBuffers(gpu, f, layer, ctx.view.name);
+  const o = layer.options;
+  const range = o.range * steer.rangeScale;
+  const cascades = ctx.world.resource(ForwardStateResource).views.get(ctx.view.name)?.cascades;
+  const shadowRange = cascades && cascades.count > 0 ? Math.min(o.shadowRange, cascades.splits[0], range) : 0;
+  const lods = o.lodDistances ?? DEFAULT_LODS;
+  cullData.fill(0);
+  cullData.set(cam.frustum, 0);
+  cullData[24] = cam.position[0];
+  cullData[25] = cam.position[1];
+  cullData[26] = cam.position[2];
+  cullData[27] = range;
+  cullData[28] = shadowRange;
+  cullData[29] = o.thinFrom ?? 0.5;
+  cullData[30] = layer.meshRadius;
+  cullData[31] = steer.density;
+  for (let l = 0; l < 4; l++) cullData[32 + l] = lods[l] ?? 2;
+  cullU32[36] = layer.perChunk;
+  cullU32[37] = layer.capacitySlots;
+  cullU32[38] = o.meshes.length;
+  cullU32[39] = layer.drawables.length;
+  cullData[40] = o.scale[0];
+  cullData[41] = o.scale[1];
+  gpu.device.queue.writeBuffer(v.params, 0, cullData);
+  drawData[0] = cam.position[0];
+  drawData[1] = cam.position[1];
+  drawData[2] = cam.position[2];
+  drawData[3] = range;
+  drawData[4] = o.thinFrom ?? 0.5;
+  drawData[5] = o.scale[0];
+  drawData[6] = o.scale[1];
+  drawData[7] = layer.perChunk;
+  gpu.device.queue.writeBuffer(v.draw, 0, drawData);
+  const pass = ctx.encoder.beginComputePass({
+    label: "foliage/cull",
+    timestampWrites: ctx.timestamps("foliage/cull")
+  });
+  pass.setBindGroup(0, v.cullGroup);
+  pass.setPipeline(f.reset);
+  pass.dispatchWorkgroups(Math.ceil(2 * layer.drawables.length / 64));
+  const total = layer.capacity;
+  const groups = Math.ceil(total / 64);
+  const gx = Math.min(groups, 65535);
+  const gy = Math.ceil(groups / 65535);
+  if (total > 0) {
+    pass.setPipeline(f.cull);
+    pass.dispatchWorkgroups(gx, gy);
+  }
+  pass.setPipeline(f.scan);
+  pass.dispatchWorkgroups(1);
+  if (total > 0) {
+    pass.setPipeline(f.scatter);
+    pass.dispatchWorkgroups(gx, gy);
+  }
+  pass.end();
+  v.culled = frame;
+  if (!v.reading && frame - v.read >= READBACK_EVERY) {
+    v.read = frame;
+    readCounts(ctx, v);
+  }
+}
+function readCounts(ctx, v) {
+  const size = v.drawables * 2 * 20;
+  v.readback ??= ctx.gpu.device.createBuffer({
+    label: "foliage/readback",
+    size,
+    usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST
+  });
+  ctx.encoder.copyBufferToBuffer(v.args, 0, v.readback, 0, size);
+  v.reading = true;
+  const buffer = v.readback;
+  ctx.afterSubmit(() => {
+    buffer.mapAsync(GPUMapMode.READ).then(
+      () => {
+        const words = new Uint32Array(buffer.getMappedRange());
+        for (let k = 0; k < v.read_.length; k++) v.read_[k] = words[k * 5 + 1];
+        buffer.unmap();
+        v.reading = false;
+      },
+      () => {
+        v.reading = false;
+      }
+    );
+  });
+}
+const FOLIAGE_KEY = 2 ** 45;
+const KIND_FORWARD = 0;
+const KIND_GBUFFER = 1;
+const KIND_SHADOW = 2;
+function foliagePipeline(ctx, f, material, kind, msaa) {
+  const world = ctx.world;
+  const gpu = ctx.gpu;
+  const state = world.resource(ForwardStateResource);
+  const assets = world.resource(GpuAssetsResource);
+  const type = material.type;
+  const variant = materialVariant(material);
+  const mask = variantBlend(variant) === "mask";
+  const mode = kind === KIND_FORWARD ? state.interiorMode : 0;
+  const key = FOLIAGE_KEY + (((kind * 1024 + typeOrdinal(type)) * 16 + variant) * 8 + msaa) + mode * 2 ** 42;
+  const cached = state.pipelines.cached(key);
+  if (cached) return cached;
+  const slot = kind === KIND_FORWARD ? 24 + (mask ? 1 : 0) + mode * 2 : (kind === KIND_GBUFFER ? 9 : 11) + (mask ? 1 : 0);
+  const root = kind === KIND_FORWARD ? "shard::foliage::forward" : kind === KIND_GBUFFER ? "shard::foliage::gbuffer" : "shard::foliage::shadow";
+  const defines = kind === KIND_FORWARD ? { PREMULTIPLY: false, MASK: mask, OPAQUE: true, ...INTERIOR_DEFINES[mode] ?? {} } : { MASK: mask };
+  const module = state.pipelines.module(world, gpu, type, slot, root, defines);
+  if (!module) return void 0;
+  const layouts = kind === KIND_SHADOW ? [state.layouts.shadowView, assets.layoutOf(type), f.drawLayout] : [state.layouts.view, assets.layoutOf(type), f.drawLayout];
+  return state.pipelines.create(
+    gpu,
+    key,
+    {
+      label: `foliage/${["forward", "gbuffer", "shadow"][kind]}/${type.name}/${mask ? "mask" : "opaque"}`,
+      layout: gpu.layouts.pipelineLayout({
+        label: `foliage/${type.name}/${kind}`,
+        bindGroupLayouts: layouts
+      }),
+      vertex: { module, entryPoint: "vs", buffers: VERTEX_BUFFERS },
+      fragment: kind === KIND_SHADOW ? mask ? { module, entryPoint: "fs_mask", targets: [] } : void 0 : {
+        module,
+        entryPoint: "fs",
+        targets: kind === KIND_GBUFFER ? state.gbufferTargets : [{ format: "rgba16float" }]
+      },
+      primitive: { topology: "triangle-list", cullMode: variantCull(variant), frontFace: "ccw" },
+      depthStencil: { format: "depth32float", depthWriteEnabled: true, depthCompare: "greater" },
+      multisample: { count: kind === KIND_FORWARD ? msaa : 1 }
+    },
+    type
+  );
+}
+function drawLayer(ctx, f, layer, v, kind, msaa, pass) {
+  const world = ctx.world;
+  const material = world.resource(Materials).get(layer.options.material);
+  if (!material?.type.standard) return;
+  const pipeline = foliagePipeline(ctx, f, material, kind, msaa);
+  if (!pipeline) {
+    ctx.gpu.pipelines.skipped++;
+    return;
+  }
+  const assets = world.resource(GpuAssetsResource);
+  const gm = assets.material(world, material);
+  if (!gm?.bindGroup) return;
+  pass.setPipeline(pipeline);
+  pass.setBindGroup(1, gm.bindGroup);
+  pass.setBindGroup(2, v.drawGroup);
+  const meshes = world.resource(Meshes);
+  const list = kind === KIND_SHADOW ? 1 : 0;
+  const count = layer.drawables.length;
+  for (let m = 0; m < count; m++) {
+    const mesh = meshes.get(layer.drawables[m]);
+    if (!mesh) continue;
+    const g = assets.mesh(mesh);
+    if (!g.indices) continue;
+    pass.setVertexBuffer(0, g.positions);
+    pass.setVertexBuffer(1, g.normals);
+    pass.setVertexBuffer(2, g.uvs);
+    pass.setVertexBuffer(3, g.uvs1);
+    pass.setVertexBuffer(4, g.tangents);
+    pass.setIndexBuffer(g.indices, g.indexFormat);
+    pass.drawIndexedIndirect(v.args, (list * count + m) * 5 * 4);
+  }
+}
+function supported(gpu) {
+  return gpu.tier === "full" && gpu.features.has("indirect-first-instance");
+}
+function support(world) {
+  const ready = (ctx, cam) => {
+    const layers = world.tryResource(FoliageLayers);
+    if (!layers || layers.layers.size === 0 || !supported(ctx.gpu) || !layers.gpu) return void 0;
+    void cam;
+    return layers;
+  };
+  return {
+    draw(ctx, cam, pass, renderPass) {
+      const layers = ready(ctx, cam);
+      if (!layers) return;
+      const kind = pass === PASS_GBUFFER ? KIND_GBUFFER : pass === PASS_OPAQUE ? KIND_FORWARD : -1;
+      if (kind < 0) return;
+      const state = world.resource(ForwardStateResource);
+      const pv = state.views.get(ctx.view.name);
+      if (!pv) return;
+      renderPass.setBindGroup(0, viewBindGroup(ctx.gpu, world, pv, cam));
+      for (const layer of layers.layers) {
+        const v = layer.views.get(ctx.view.name);
+        if (!v || v.culled !== state.frame || layer.chunkCount === 0) continue;
+        drawLayer(
+          ctx,
+          layers.gpu,
+          layer,
+          v,
+          kind,
+          kind === KIND_FORWARD ? cam.msaa : 1,
+          renderPass
+        );
+      }
+    },
+    drawShadow(ctx, cam, renderPass, offset, cascade) {
+      if (cascade !== 0) return;
+      const layers = ready(ctx, cam);
+      if (!layers) return;
+      void offset;
+      const frame = world.resource(ForwardStateResource).frame;
+      for (const layer of layers.layers) {
+        if (!(layer.options.shadowRange > 0)) continue;
+        const v = layer.views.get(ctx.view.name);
+        if (!v || v.culled !== frame || layer.chunkCount === 0) continue;
+        drawLayer(ctx, layers.gpu, layer, v, KIND_SHADOW, 1, renderPass);
+      }
+    },
+    animatedShadows(cam) {
+      const layers = world.tryResource(FoliageLayers);
+      if (!layers) return false;
+      void cam;
+      for (const layer of layers.layers)
+        if (layer.options.shadowRange > 0 && layer.chunkCount > 0) return true;
+      return false;
+    }
+  };
+}
+function foliageTarget(world, budget, set) {
+  if (budget.ms > 0) return budget.ms;
+  const scenario = world.tryResource(PerfScenario)?.name ?? null;
+  if (scenario === null) return 0;
+  const data = world.tryResource(PerfBudgets);
+  if (scenario !== set.sliceFor || data !== set.sliceData) {
+    set.sliceFor = scenario;
+    set.sliceData = data;
+    set.sliceMs = scenarioSliceMs(world, scenario, "gpu", FOLIAGE_SPAN_KEY) ?? 0;
+  }
+  return set.sliceMs;
+}
+const steerFoliage = defineSystem({
+  name: "render/foliage-budget",
+  description: "Thins GPU foliage's density and range to keep its GPU time (gpu:foliage) inside FoliageBudget's target, or its scenario slice (0075).",
+  run: (_, world) => {
+    const set = world.tryResource(FoliageLayers);
+    const budget = world.tryResource(FoliageBudget);
+    const profiler = world.tryResource(ProfilerResource);
+    if (!set || !budget || !profiler) return;
+    const target = foliageTarget(world, budget, set);
+    budget.target = target;
+    const landed = set.gpuTime.read(profiler);
+    if (!(target > 0)) {
+      if (set.steer.detail !== 1) set.steer.reset();
+      if (landed) budget.measuredMs = set.gpuTime.ms;
+      budget.detail = 1;
+      return;
+    }
+    if (landed) set.steer.sample(set.gpuTime.ms, target, budget.minDetail);
+    budget.measuredMs = set.steer.smoothed;
+    budget.detail = set.steer.detail;
+  }
+});
+const FORWARD_READS = [
+  "clusters",
+  "shadow-cascades",
+  "shadow-local",
+  "environment",
+  "culled",
+  "ssao"
+];
+const FORWARD_WRITES = ["scene-color", "scene-depth", "hdr"];
+const foliagePlugin = definePlugin({
+  name: "render/foliage",
+  dependencies: ["render/forward"],
+  provides: [FoliageLayers, FoliagePath, FoliageBudget],
+  build(app) {
+    app.world.initResource(FoliageLayers);
+    app.world.initResource(FoliageBudget);
+    app.insertResource(FoliagePath, support(app.world));
+    app.addSystems(PostUpdate, steerFoliage);
+  },
+  dispose(app) {
+    app.world.tryResource(FoliageLayers)?.dispose();
+  },
+  ready(app) {
+    const world = app.world;
+    const graph = world.tryResource(Graph);
+    if (!graph) return;
+    registerShaders(world.resource(Shaders), FOLIAGE_SHADERS);
+    addRenderFeatures(world, {
+      name: "render/foliage",
+      description: "GPU foliage: instances placed and culled by compute, drawn indirectly.",
+      nodes: ["foliage/place", "foliage/cull", "foliage/draw"],
+      baseline: "unsupported"
+    });
+    let placed = -1;
+    graph.addNode("foliage/place", {
+      kind: "raw",
+      phase: RenderPhase.Setup + 5,
+      sideEffects: true,
+      enabled: (view) => cameraOf(view) !== void 0,
+      run(ctx) {
+        const state = world.resource(ForwardStateResource);
+        if (placed === state.frame) return;
+        placed = state.frame;
+        const set = world.resource(FoliageLayers);
+        const layers = set.layers;
+        if (layers.size === 0 || !supported(ctx.gpu)) return;
+        const f = foliageGpu(ctx.gpu, set);
+        if (!pipelines(ctx, f)) {
+          ctx.gpu.pipelines.skipped++;
+          return;
+        }
+        const t0 = performance.now();
+        for (const layer of layers) ensureLayer(ctx.gpu, layer, world);
+        placeChunks(ctx, f, layers);
+        world.tryResource(ProfilerResource)?.record("foliage/place", performance.now() - t0);
+      }
+    });
+    graph.addNode("foliage/cull", {
+      kind: "raw",
+      phase: RenderPhase.Setup + 6,
+      sideEffects: true,
+      after: ["foliage/place"],
+      enabled: (view) => cameraOf(view) !== void 0,
+      run(ctx) {
+        const set = world.resource(FoliageLayers);
+        const f = set.gpu;
+        if (set.layers.size === 0 || !supported(ctx.gpu) || !f?.cull) return;
+        const cam = cameraOf(ctx.view);
+        const frame = world.resource(ForwardStateResource).frame;
+        for (const layer of set.layers) {
+          if (layer.chunkCount === 0 || !layer.instances) continue;
+          cullLayer(ctx, f, layer, cam, frame, set.steer);
+        }
+      }
+    });
+    graph.addNode("foliage/draw", {
+      kind: "render",
+      ownPass: true,
+      phase: RenderPhase.Opaque + 5,
+      after: ["forward-opaque"],
+      enabled: (view) => {
+        const cam = cameraOf(view);
+        return cam !== void 0 && !cam.deferred && world.resource(FoliageLayers).layers.size > 0;
+      },
+      reads: FORWARD_READS,
+      writes: FORWARD_WRITES,
+      color: (view) => sceneColor(view),
+      depth: { resource: "scene-depth" },
+      run(ctx) {
+        world.tryResource(FoliagePath)?.draw(ctx, cameraOf(ctx.view), PASS_OPAQUE, ctx.renderPass);
+      }
+    });
+  }
+});
+export {
+  FoliageLayer,
+  FoliageLayerSet,
+  FoliageLayers,
+  foliagePlugin
+};