@aethervtt/shard-render 0.1.0 → 0.2.0

package/dist/ribbons.js

@@ -0,0 +1,288 @@
+import { defineResource, defineSystem } from "@aethervtt/shard-core";
+import { FrameDemand, Time } from "@aethervtt/shard-runtime";
+import { GlobalTransform } from "@aethervtt/shard-transform";
+import { Beam, Trail } from "./vfx.js";
+import {
+  createRecord,
+  matrixChanged,
+  number,
+  point,
+  recordDescription,
+  refreshRecord,
+  VFX_STRIDE
+} from "./vfx-state.js";
+const Ribbons = defineResource("render/Ribbons", {
+  init: () => ({
+    records: [],
+    trails: /* @__PURE__ */ new Map(),
+    beams: /* @__PURE__ */ new Map(),
+    frame: 0,
+    rejected: 0
+  })
+});
+function create(world, entity, beam2) {
+  const capacity = beam2 ? 256 : world.get(entity, Trail).capacity;
+  return {
+    ...createRecord(
+      world,
+      entity,
+      beam2 ? Beam : Trail,
+      beam2 ? "beam" : "trail",
+      (capacity - 1) * 6
+    ),
+    points: new Float64Array(capacity * 5),
+    capacity,
+    head: 0,
+    pointsCount: 0,
+    distance: 0,
+    targetMatrix: new Float64Array(12),
+    scratch: new Float64Array(6)
+  };
+}
+function noise(seed, index) {
+  let x = (seed ^ Math.imul(index + 1, 2654435769)) >>> 0;
+  x = Math.imul(x ^ x >>> 16, 569420461);
+  x = Math.imul(x ^ x >>> 15, 1935289751);
+  return ((x ^ x >>> 15) >>> 0) / 4294967295 * 2 - 1;
+}
+function trail(r, playing, paused) {
+  const life = number(r, "lifetime"), p = r.points;
+  while (r.pointsCount && r.age - p[r.head * 5 + 3] >= life) {
+    r.head = (r.head + 1) % r.capacity;
+    r.pointsCount--;
+  }
+  if (!playing || paused) return;
+  const offset = r.columns.offset, o = r.row * 3;
+  point(r.scratch, 0, r.matrix, offset[o], offset[o + 1], offset[o + 2]);
+  let distance = 0;
+  if (r.pointsCount) {
+    const last = (r.head + r.pointsCount - 1) % r.capacity * 5;
+    const dx = r.scratch[0] - p[last], dy = r.scratch[1] - p[last + 1], dz = r.scratch[2] - p[last + 2];
+    distance = Math.sqrt(dx * dx + dy * dy + dz * dz);
+    if (distance < number(r, "minDistance")) return;
+    if (distance > number(r, "breakDistance")) {
+      r.head = 0;
+      r.pointsCount = 0;
+      r.distance = 0;
+      distance = 0;
+    }
+  }
+  if (r.pointsCount === r.capacity) {
+    r.head = (r.head + 1) % r.capacity;
+    r.pointsCount--;
+  }
+  const at = (r.head + r.pointsCount++) % r.capacity * 5;
+  p[at] = r.scratch[0];
+  p[at + 1] = r.scratch[1];
+  p[at + 2] = r.scratch[2];
+  p[at + 3] = r.age;
+  p[at + 4] = r.distance += distance;
+}
+function beam(world, r) {
+  const authored = r.columns.points[r.row];
+  if (authored.length > 256 || authored.length === 1) {
+    r.error = "render/beam-points";
+    r.pointsCount = 0;
+    return;
+  }
+  const p = r.points;
+  r.head = 0;
+  if (authored.length) {
+    r.pointsCount = authored.length;
+    for (let i = 0; i < authored.length; i++) {
+      const v = authored[i];
+      point(p, i * 5, r.matrix, v[0], v[1], v[2]);
+    }
+  } else {
+    const target = number(r, "target"), start = r.columns.start, end = r.columns.end, o = r.row * 3;
+    if (target >= 0 && (!world.isAlive(target) || !world.has(target, GlobalTransform))) {
+      r.error = "render/beam-target";
+      r.pointsCount = 0;
+      return;
+    }
+    const m = target >= 0 ? r.targetMatrix : r.matrix;
+    if (target >= 0) matrixChanged(world, target, m);
+    point(r.scratch, 0, r.matrix, start[o], start[o + 1], start[o + 2]);
+    point(r.scratch, 3, m, end[o], end[o + 1], end[o + 2]);
+    const segments = number(r, "segments"), strength = number(r, "noise"), seed = number(r, "seed");
+    r.pointsCount = segments + 1;
+    for (let i = 0; i <= segments; i++) {
+      const f = i / segments, amplitude = i === 0 || i === segments ? 0 : strength;
+      for (let k = 0; k < 3; k++)
+        p[i * 5 + k] = r.scratch[k] + (r.scratch[k + 3] - r.scratch[k]) * f + noise(seed, i * 3 + k) * amplitude;
+    }
+  }
+  let distance = 0;
+  for (let i = 0; i < r.pointsCount; i++) {
+    if (i) {
+      const dx = p[i * 5] - p[(i - 1) * 5], dy = p[i * 5 + 1] - p[(i - 1) * 5 + 1], dz = p[i * 5 + 2] - p[(i - 1) * 5 + 2];
+      distance += Math.sqrt(dx * dx + dy * dy + dz * dz);
+    }
+    p[i * 5 + 4] = distance;
+  }
+  r.distance = distance;
+}
+function ribbonGeometry(r) {
+  r.count = 0;
+  const curve = r.columns.widthCurve[r.row];
+  if (curve.length > 16) {
+    r.error = "render/ribbon-curve";
+    return;
+  }
+  for (let i = 0; i < curve.length; i++)
+    if (!Number.isFinite(curve[i].at) || !Number.isFinite(curve[i].value) || curve[i].at < 0 || curve[i].at > 1 || curve[i].value < 0 || curve[i].value > 16 || i > 0 && curve[i].at <= curve[i - 1].at) {
+      r.error = "render/ribbon-curve";
+      return;
+    }
+  const p = r.points, out = r.vertices, c = r.columns.color, e = r.columns.endColor;
+  const width = number(r, "width"), repeat = number(r, "repeat"), scroll = number(r, "scroll") * r.age;
+  const life = r.kind === "trail" ? number(r, "lifetime") : 1;
+  for (let segment = 0; segment < r.pointsCount - 1; segment++) {
+    const a = (r.head + segment) % r.capacity * 5, b = (r.head + segment + 1) % r.capacity * 5;
+    const dx = p[b] - p[a], dy = p[b + 1] - p[a + 1], dz = p[b + 2] - p[a + 2];
+    if (dx * dx + dy * dy + dz * dz < 1e-16) continue;
+    for (let v = 0; v < 6; v++) {
+      const next = v === 1 || v === 2 || v === 4, side = v === 2 || v === 4 || v === 5 ? 1 : -1;
+      const index = segment + (next ? 1 : 0), at = next ? b : a;
+      const prev = (r.head + Math.max(0, index - 1)) % r.capacity * 5, after = (r.head + Math.min(r.pointsCount - 1, index + 1)) % r.capacity * 5;
+      const f = Math.min(
+        1,
+        Math.max(
+          0,
+          r.kind === "trail" ? (r.age - p[at + 3]) / life : p[at + 4] / Math.max(r.distance, 1e-9)
+        )
+      );
+      let scale = 1;
+      if (curve.length) {
+        scale = curve[0].value;
+        for (let k = 1; k < curve.length; k++) {
+          const x = curve[k - 1], y = curve[k];
+          if (f >= y.at) scale = y.value;
+          else if (f > x.at) {
+            scale = x.value + (y.value - x.value) * (f - x.at) / (y.at - x.at);
+            break;
+          } else break;
+        }
+      }
+      const o = r.count++ * VFX_STRIDE;
+      out[o] = p[at];
+      out[o + 1] = p[at + 1];
+      out[o + 2] = p[at + 2];
+      out[o + 3] = p[after] - p[prev];
+      out[o + 4] = p[after + 1] - p[prev + 1];
+      out[o + 5] = p[after + 2] - p[prev + 2];
+      out[o + 6] = p[at + 4] / repeat + scroll;
+      out[o + 7] = (side + 1) * 0.5;
+      for (let k = 0; k < 4; k++)
+        out[o + 8 + k] = c[r.row * 4 + k] + (e[r.row * 4 + k] - c[r.row * 4 + k]) * f;
+      out[o + 12] = width * scale * 0.5;
+      out[o + 13] = side;
+    }
+  }
+  r.version++;
+}
+const updateRibbons = defineSystem({
+  name: "render/ribbons-update",
+  setup: (world) => ({
+    trails: world.query({ with: [Trail, GlobalTransform] }),
+    beams: world.query({ with: [Beam, GlobalTransform] })
+  }),
+  run({ trails, beams }, world) {
+    const state = world.resource(Ribbons), delta = world.resource(Time).delta;
+    state.frame++;
+    state.rejected = 0;
+    let demand = false;
+    for (let kind = 0; kind < 2; kind++) {
+      const q = kind ? beams : trails;
+      for (let t = 0; t < q.tables.length; t++) {
+        const table = q.tables[t];
+        for (let row = 0; row < table.count; row++) {
+          const entity = table.entities[row];
+          const limit = kind ? table.column(Beam, "segments")[row] : table.column(Trail, "capacity")[row];
+          if (limit < (kind ? 1 : 2) || limit > (kind ? 255 : 256)) {
+            state.rejected++;
+            continue;
+          }
+          const lookup = kind ? state.beams : state.trails;
+          let r = lookup.get(entity);
+          if (!r) {
+            if (state.records.length >= 256) {
+              state.rejected++;
+              continue;
+            }
+            r = create(world, entity, kind === 1);
+            state.records.push(r);
+            lookup.set(entity, r);
+          }
+          refreshRecord(world, r);
+          matrixChanged(world, entity, r.matrix);
+          r.seen = state.frame;
+          r.error = null;
+          const playing = !!number(r, "playing"), paused = !!number(r, "paused");
+          if (r.kind === "trail" && r.capacity !== number(r, "capacity")) {
+            r.capacity = number(r, "capacity");
+            r.points = new Float64Array(r.capacity * 5);
+            r.vertices = new Float32Array((r.capacity - 1) * 6 * VFX_STRIDE);
+            r.head = 0;
+            r.pointsCount = 0;
+          }
+          if (playing && !r.wasPlaying && r.kind === "beam") r.age = 0;
+          r.wasPlaying = playing;
+          if (!paused) r.age += delta;
+          if (kind) {
+            if (playing && (!paused || r.pointsCount === 0)) beam(world, r);
+            else if (!playing) r.pointsCount = 0;
+            else if (r.columns.points[r.row].length === 0) {
+              const target = number(r, "target");
+              if (target >= 0 && (!world.isAlive(target) || !world.has(target, GlobalTransform))) {
+                r.error = "render/beam-target";
+                r.pointsCount = 0;
+              }
+            }
+          } else trail(r, playing, paused);
+          ribbonGeometry(r);
+          if (!paused && (playing || r.pointsCount > 0)) demand = true;
+        }
+      }
+    }
+    for (let i = state.records.length - 1; i >= 0; i--)
+      if (state.records[i].seen !== state.frame) {
+        const r = state.records[i];
+        (r.kind === "beam" ? state.beams : state.trails).delete(r.entity);
+        state.records.splice(i, 1);
+      }
+    world.tryResource(FrameDemand)?.set("render/ribbons", demand);
+  }
+});
+function shiftRibbons(world, x, y, z) {
+  const records = world.resource(Ribbons).records;
+  for (let i = 0; i < records.length; i++) {
+    const r = records[i];
+    for (let j = 0; j < r.pointsCount; j++) {
+      const at = (r.head + j) % r.capacity * 5;
+      r.points[at] = r.points[at] + x;
+      r.points[at + 1] = r.points[at + 1] + y;
+      r.points[at + 2] = r.points[at + 2] + z;
+    }
+  }
+}
+function describeRibbons(world) {
+  const s = world.resource(Ribbons);
+  return {
+    rejected: s.rejected,
+    error: s.rejected ? "render/ribbon-limit" : null,
+    records: s.records.map((r) => ({
+      ...recordDescription(r),
+      cpuBytes: r.vertices.byteLength + r.points.byteLength + r.matrix.byteLength + r.targetMatrix.byteLength + r.scratch.byteLength,
+      points: r.pointsCount,
+      capacity: r.capacity
+    }))
+  };
+}
+export {
+  Ribbons,
+  describeRibbons,
+  ribbonGeometry,
+  shiftRibbons,
+  updateRibbons
+};

package/dist/scenario.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Scenario tests (0075), a test helper exported from `@aethervtt/shard-render/testing`: a fixture's
+ * camera path runs through a 0074 capture, and each slice of the scenario (`bench/perf/budgets.json`)
+ * is read from it with the covers rule (`Capture.spanTime`), so tests, `shard profile` and the
+ * `perf` overlay measure the same thing. On a machine whose GPU passes overlap (machines.json's
+ * `passTiming: "ablation"`), GPU slices are measured by ablation under `pnpm bench` instead.
+ */
+import { type World } from '@aethervtt/shard-core';
+import type { Capture, CaptureSummary } from '@aethervtt/shard-core/capture';
+import { type Track } from '@aethervtt/shard-core/test-env';
+import type { expect as vitestExpect } from 'vitest';
+export interface ScenarioSlice {
+    key: string;
+    track: Track;
+    /** Spans that ran in the capture and that the key covers. */
+    covers: string[];
+    /** Time the key covered in each captured frame (ms). */
+    perFrame: Float64Array;
+    /** The p95 of it: frames whose GPU timings landed, for a GPU slice. Ablation's cost instead. */
+    p95: number;
+    measuredBy: 'capture' | 'ablation';
+    /**
+     * Ablation only: half the range of the cost over rounds, in ms. A pass's cost is the difference
+     * of two frame times that vary by milliseconds, so a sub-millisecond pass can't be resolved
+     * below this; the budget check allows it.
+     */
+    noise?: number;
+}
+export interface ScenarioRun {
+    name: string;
+    summary: CaptureSummary;
+    capture: Capture;
+    /** Every span that ran during the capture, by name. */
+    spans: string[];
+    /** Each frame's CPU time (`frame`) and GPU time (`gpu:frame`; 0 where none landed). */
+    frame: {
+        cpu: Float64Array;
+        gpu: Float64Array;
+        cpuP95: number;
+        gpuP95: number;
+    };
+    /** Whether GPU passes were timed (the device has `timestamp-query`). */
+    gpuTimed: boolean;
+    slices: ScenarioSlice[];
+}
+export interface ScenarioOptions {
+    /** Frames along the camera path, each run through the capture. */
+    frames: number;
+    /** Puts the camera at path frame `i`, runs one app frame, and waits for the GPU. */
+    step: (i: number) => void | Promise<void>;
+    /** Ablation under `pnpm bench` on a machine that needs it: frames per measurement, rounds. */
+    ablation?: {
+        frames?: number;
+        rounds?: number; /** Ablate whatever the machine (tests of this helper). */
+        force?: boolean;
+    };
+}
+/**
+ * Runs a scenario's camera path through a capture and measures its frame and slices (0075). The
+ * slices are the scenario's keys in budgets.json, `headroom` aside.
+ */
+export declare function measureScenario(world: World, name: string, options: ScenarioOptions): Promise<ScenarioRun>;
+/**
+ * The checks of a scenario test. In `pnpm test`: the capture ran every frame, and every slice key
+ * covers at least one span that ran (GPU ones where the device times passes). Under `pnpm bench`:
+ * p95 of the frame and of each slice against the scenario's budgets, soft, so every one is
+ * recorded for `bench/perf/report.json`. A slice measured by ablation fails only when it's over by
+ * more than its noise: what's checked (and reported) is its cost minus the noise.
+ */
+export declare function expectScenario(run: ScenarioRun, expect: typeof vitestExpect): void;

package/dist/scenario.js

@@ -0,0 +1,125 @@
+import { spanCovers, spanName } from "@aethervtt/shard-core";
+import {
+  budget,
+  passTiming,
+  scenarioSlices,
+  timingMode
+} from "@aethervtt/shard-core/test-env";
+import { capturePerf } from "@aethervtt/shard-runtime";
+import { ablatePasses } from "./ablation.js";
+import { Graph } from "./plugin.js";
+function p95Of(values) {
+  const sorted = Array.from(values).sort((a, b) => a - b);
+  if (sorted.length === 0) return 0;
+  return sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * 0.95))];
+}
+async function measureScenario(world, name, options) {
+  const keys = scenarioSlices(name);
+  let i = 0;
+  const { summary, capture } = await capturePerf(world, {
+    frames: options.frames,
+    write: false,
+    trace: false,
+    keep: true,
+    step: async () => {
+      await options.step(Math.min(i, options.frames - 1));
+      i++;
+    }
+  });
+  if (!capture) throw new Error("capturePerf kept no capture");
+  const seen = /* @__PURE__ */ new Set();
+  for (let e = 0; e < capture.eventCount; e++) seen.add(capture.events.ids[e]);
+  const spans = [...seen].map(spanName).sort();
+  const gpuFrame = capture.spanTime("gpu:frame");
+  const timedFrames = [];
+  for (let f = 0; f < gpuFrame.length; f++) if (gpuFrame[f] > 0) timedFrames.push(f);
+  const gpuTimed = timedFrames.length > 0;
+  const slices = [];
+  for (const track of ["gpu", "cpu"]) {
+    for (const key of keys[track]) {
+      const perFrame = capture.spanTime(key);
+      const values = track === "gpu" ? timedFrames.map((f) => perFrame[f]) : perFrame;
+      slices.push({
+        key,
+        track,
+        covers: spans.filter((s) => spanCovers(key, s)),
+        perFrame,
+        p95: p95Of(values),
+        measuredBy: "capture"
+      });
+    }
+  }
+  if ((options.ablation?.force || passTiming() === "ablation") && gpuTimed) {
+    const graph = world.resource(Graph);
+    const nodes = graph.nodeNames();
+    const groups = {};
+    for (const s of slices) {
+      if (s.track !== "gpu") continue;
+      const covered = nodes.filter((n) => spanCovers(s.key, `gpu:${n}`));
+      if (covered.length > 0) groups[s.key] = covered;
+    }
+    const passes = Object.keys(groups);
+    if (passes.length > 0) {
+      const result = await ablatePasses(
+        world,
+        {
+          passes,
+          groups,
+          frames: options.ablation?.frames ?? 60,
+          rounds: options.ablation?.rounds ?? 3
+        },
+        () => options.step(options.frames - 1)
+      );
+      for (const cost of result.passes) {
+        const s = slices.find((x) => x.track === "gpu" && x.key === cost.pass);
+        s.p95 = Math.max(0, cost.ms);
+        s.measuredBy = "ablation";
+        s.noise = (Math.max(...cost.rounds) - Math.min(...cost.rounds)) / 2;
+      }
+    }
+  }
+  return {
+    name,
+    summary,
+    capture,
+    spans,
+    frame: {
+      cpu: capture.frames.cpu,
+      gpu: gpuFrame,
+      cpuP95: p95Of(capture.frames.cpu),
+      gpuP95: p95Of(timedFrames.map((f) => gpuFrame[f]))
+    },
+    gpuTimed,
+    slices
+  };
+}
+function expectScenario(run, expect) {
+  expect(run.summary.frames.count).toBe(run.capture.frameCount);
+  expect(run.capture.frameCount).toBeGreaterThan(0);
+  for (const s of run.slices) {
+    if (s.track === "gpu" && !run.gpuTimed) continue;
+    expect(s.covers, `${run.name}: slice "${s.key}" covers no span that ran`).not.toEqual([]);
+  }
+  if (timingMode !== "bench") return;
+  const soft = expect.soft;
+  soft(run.frame.cpuP95, `${run.name}: CPU frame p95`).toBeLessThan(
+    budget(`${run.name}`, { track: "cpu" })
+  );
+  if (run.gpuTimed) {
+    soft(run.frame.gpuP95, `${run.name}: GPU frame p95`).toBeLessThan(
+      budget(`${run.name}`, { track: "gpu" })
+    );
+  }
+  for (const s of run.slices) {
+    if (s.track === "gpu" && !run.gpuTimed) continue;
+    const measured = s.noise === void 0 ? s.p95 : Math.max(0, s.p95 - s.noise);
+    const how = s.noise === void 0 ? s.measuredBy : `ablation, ${s.p95.toFixed(3)} \xB1 ${s.noise.toFixed(3)} ms`;
+    soft(measured, `${run.name}: ${s.track} slice ${s.key} p95 (${how})`).toBeLessThan(
+      budget(`${run.name}`, { slice: s.key, track: s.track })
+    );
+  }
+}
+export {
+  expectScenario,
+  measureScenario
+};

package/dist/shaders.js

@@ -664,6 +664,26 @@ fn heat(count: u32) -> vec3f {
  * Lighting stage: the only place lights are evaluated. Returns scene-referred radiance.
  * Directional lights (with cascaded shadows), then clustered point and spot lights, then ambient.
  */
+/**
+ * SSAO at a full-resolution pixel, from the half-resolution AO and view depth (rg): the four
+ * nearest texels, weighted by how well their depth matches this pixel's. Without SSAO a white
+ * 1\xD71 texture is bound, which gives 1.
+ */
+fn ssao_at(frag: vec2f, z: f32) -> f32 {
+  let half_size = vec2i(textureDimensions(ao_texture));
+  let base = vec2i(floor((frag - 1.0) * 0.5));
+  var sum = 0.0;
+  var weight = 0.0;
+  for (var k = 0; k < 4; k++) {
+    let q = clamp(base + vec2i(k & 1, k >> 1), vec2i(0), half_size - 1);
+    let s = textureLoad(ao_texture, q, 0);
+    let w = 1.0 / (1e-3 + abs(s.y - z) / max(z, 1e-3));
+    sum += s.x * w;
+    weight += w;
+  }
+  return sum / max(weight, 1e-6);
+}
+
 fn apply_lighting(p: PbrInput, world_position: vec3f, frag_coord: vec4f, flags: u32) -> vec3f {
   let n = p.normal;
   let v = normalize(view.cameraPosition - world_position);
@@ -754,10 +774,7 @@ fn apply_lighting(p: PbrInput, world_position: vec3f, frag_coord: vec4f, flags:
   // Ambient: image-based lighting from the environment, or the uniform AmbientLight (cd/m\xB2).
   // SSAO darkens it on opaque surfaces (it measures the depth buffer, which blended ones aren't in).
   var surface = p;
-  if (p.alpha >= 0.999) {
-    let dims = vec2i(textureDimensions(ao_texture));
-    surface.occlusion *= textureLoad(ao_texture, min(vec2i(frag_coord.xy), dims - 1), 0).r;
-  }
+  if (p.alpha >= 0.999) { surface.occlusion *= ssao_at(frag_coord.xy, view_depth); }
   if (view.envParams.w > 0.5) {
     @if(!SKY_VISIBILITY) color += environment_light(surface, n, v);
     @if(SKY_VISIBILITY) color += interior_ambient(environment_light(surface, n, v), diffuse_color * surface.occlusion, world_position, n);
@@ -1083,10 +1100,21 @@ fn environment_light(p: PbrInput, n: vec3f, v: vec3f) -> vec3f {
 /** The environment's own radiance toward d (the background), in cd/m\xB2. */
 fn environment_background(d: vec3f) -> vec3f {
   return textureSampleLevel(env_source, env_sampler, env_rotate(d), 0.0).rgb * view.envParams.x;
+}`,
+  "shard::post::glow": `
+/**
+ * Bloom's first level over the image: mixed, conserving energy, without a threshold; added with
+ * one. \`glow\`: intensity, the chain's level count, mix (1) or add (0), 0. The tonemap applies it
+ * as it reads the image, and auto exposure meters the same mix.
+ */
+fn add_glow(c: vec3f, level0: vec3f, glow: vec4f) -> vec3f {
+  let g = level0 / glow.y;
+  return select(c + g * glow.x, mix(c, g, glow.x), glow.z > 0.5);
 }`,
   "shard::post::tonemap": `
 import shard::color::{ linear_to_srgb, srgb_to_linear, ign, luminance };
 import shard::tonemap::tonemap;
+@if(BLOOM) import shard::post::glow::add_glow;
 
 struct TonemapParams {
   /** curve, dither, flags (1 grading, 2 vignette, 4 LUT, 8 sRGB LUT), 0. */
@@ -1102,12 +1130,16 @@ struct TonemapParams {
   vignette: vec4f,
   /** 1 / width, 1 / height of the view. */
   texel: vec4f,
+  /** Bloom: intensity, level count, mix (1) or add (0), 0. */
+  glow: vec4f,
 }
 
 @group(0) @binding(0) var hdr: texture_2d<f32>;
 @group(0) @binding(1) var<uniform> params: TonemapParams;
 @group(0) @binding(2) var lut: texture_2d<f32>;
 @group(0) @binding(3) var lut_sampler: sampler;
+/** Bloom's first level, composited here instead of in a pass of its own. */
+@if(BLOOM) @group(0) @binding(4) var bloom: texture_2d<f32>;
 
 const LIN_TO_LMS = mat3x3f(
   vec3f(3.90405e-1, 7.08416e-2, 2.31082e-2),
@@ -1145,7 +1177,11 @@ fn apply_lut(c: vec3f) -> vec3f {
 }
 
 @fragment fn fs(@builtin(position) p: vec4f) -> @location(0) vec4f {
-  let texel = textureLoad(hdr, vec2i(p.xy), 0);
+  var texel = textureLoad(hdr, vec2i(p.xy), 0);
+  @if(BLOOM) {
+    let level0 = textureSampleLevel(bloom, lut_sampler, p.xy * params.texel.xy, 0.0).rgb;
+    texel = vec4f(add_glow(texel.rgb, level0, params.glow), texel.a);
+  }
   var hdr_color = max(texel.rgb, vec3f(0.0));
   @if(TRANSPARENT) var alpha = 1.0;
   @if(TRANSPARENT) {
@@ -1234,6 +1270,23 @@ fn world_at(uv: vec2f, depth: f32) -> vec3f {
   return w.xyz / w.w;
 }
 
+/**
+ * Rounds to nearest on a device that truncates when it stores rg11b10ufloat (Metal does): half a
+ * step of each channel's own exponent (6 mantissa bits in red and green, 5 in blue) added before
+ * the store. Without it every pass through the format loses half a step on average, blue twice
+ * as much, and the image drifts warm.
+ */
+fn rg11_round(c: vec3f) -> vec3f {
+  let e = exp2(floor(log2(max(c, vec3f(6.2e-5)))));
+  return c + e * vec3f(1.0 / 128.0, 1.0 / 128.0, 1.0 / 64.0);
+}
+
+/** A post pass's output into the chain: rounded where it's rg11b10ufloat on a truncating device. */
+fn post_out(c: vec4f) -> vec4f {
+  @if(RG11_ROUND) return vec4f(rg11_round(c.rgb), c.a);
+  @if(!RG11_ROUND) return c;
+}
+
 /** Distance along the view axis, in meters. */
 fn view_depth(world: vec3f) -> f32 {
   return -(view.view * vec4f(world, 1.0)).z;

package/dist/shadows.d.ts

@@ -1,5 +1,6 @@
 import { type World } from '@aethervtt/shard-core';
 import { GpuBuffer, type GpuContext } from '@aethervtt/shard-gpu';
+import type { FoliageSupport } from './foliage-path.js';
 import type { NodeContext } from './graph.js';
 import { type DrawList, type InstanceStore } from './instances.js';
 import { type LightRecord, type LightStore } from './lights.js';
@@ -134,7 +135,7 @@ export declare function shadowViewLayout(gpu: GpuContext): GPUBindGroupLayout;
  * `vertex_position` displacement moves shadows too). Opaque materials are vertex-only; masked
  * standard materials run the surface stage to discard.
  */
-export declare function drawShadowCasters(ctx: NodeContext, target: GPUTextureView, view: ShadowViewDraw, offset: number, uniforms: ShadowPassUniforms, pipelines: MaterialPipelines, shadowView: GPUBindGroupLayout, label: string): void;
+export declare function drawShadowCasters(ctx: NodeContext, target: GPUTextureView, view: ShadowViewDraw, offset: number, uniforms: ShadowPassUniforms, pipelines: MaterialPipelines, shadowView: GPUBindGroupLayout, label: string, foliage?: FoliageSupport, cam?: CameraData, cascade?: number): void;
 /** Culls instances that cast shadows into a shadow view, and unions their world bounds. */
 export declare function cullCasters(world: World, view: ShadowViewDraw, planes: Float32Array, box?: Float32Array): boolean;
 export declare const ShadowsResource: import("@aethervtt/shard-core").ResourceDef<{

package/dist/shadows.js

@@ -497,7 +497,7 @@ const SHADOW_BUFFERS = [
   { arrayStride: 8, attributes: [{ shaderLocation: 3, offset: 0, format: "float32x2" }] },
   { arrayStride: 16, attributes: [{ shaderLocation: 4, offset: 0, format: "float32x4" }] }
 ];
-function drawShadowCasters(ctx, target, view, offset, uniforms, pipelines, shadowView2, label) {
+function drawShadowCasters(ctx, target, view, offset, uniforms, pipelines, shadowView2, label, foliage, cam, cascade = 0) {
   const world = ctx.world;
   const gpu = ctx.gpu;
   const store = world.resource(Instances);
@@ -516,6 +516,7 @@ function drawShadowCasters(ctx, target, view, offset, uniforms, pipelines, shado
   const draws0 = view.draws;
   const instances = draws0.cullView >= 0 ? store.gpuBindGroup : store.bindGroup;
   if (!instances || !uniforms.bindGroup) {
+    if (foliage && cam && uniforms.bindGroup) foliage.drawShadow(ctx, cam, pass, offset, cascade);
     pass.end();
     return;
   }
@@ -607,6 +608,7 @@ function drawShadowCasters(ctx, target, view, offset, uniforms, pipelines, shado
       pass.draw(gm.count, item.count, 0, item.first);
     }
   }
+  if (foliage && cam) foliage.drawShadow(ctx, cam, pass, offset, cascade);
   pass.end();
 }
 const PASS_SHADOW = 2;

package/dist/standard.js

@@ -1,10 +1,12 @@
 import { definePlugin } from "@aethervtt/shard-runtime";
 import { atmospherePlugin } from "./atmosphere-plugin.js";
 import { cutawayPlugin } from "./cutaway-plugin.js";
+import { decalsPlugin } from "./decals-plugin.js";
 import { deferredPlugin } from "./deferred-plugin.js";
 import { renderDescribePlugin } from "./describe-plugin.js";
 import { dynamicResolutionPlugin } from "./dynamic-resolution.js";
 import { environmentPlugin } from "./environment-plugin.js";
+import { foliagePlugin } from "./foliage.js";
 import { forwardCorePlugin } from "./forward.js";
 import { fxaaPlugin } from "./fxaa.js";
 import { gizmosPlugin } from "./gizmos-plugin.js";
@@ -14,6 +16,7 @@ import { outlinePlugin } from "./outline-plugin.js";
 import { pickingPlugin } from "./picking-plugin.js";
 import { pixelPerfectPlugin } from "./pixel-perfect-plugin.js";
 import { postPlugin } from "./post-plugin.js";
+import { ribbonsPlugin } from "./ribbons-plugin.js";
 import { shadowCatcherPlugin } from "./shadow-catcher.js";
 import { skinningPlugin } from "./skinning-plugin.js";
 import { viewVisibilityPlugin } from "./view-visibility-plugin.js";
@@ -38,7 +41,10 @@ function forwardPlugin(options = {}) {
         viewVisibilityPlugin,
         interiorPlugin,
         shadowCatcherPlugin,
+        foliagePlugin,
         dynamicResolutionPlugin,
+        ribbonsPlugin,
+        decalsPlugin,
         renderDescribePlugin
       );
     }

package/dist/testing.d.ts

@@ -1,5 +1,6 @@
 import type { App } from '@aethervtt/shard-runtime';
 import type { CapturedImage } from './graph.js';
+export { expectScenario, measureScenario, type ScenarioOptions, type ScenarioRun, type ScenarioSlice, } from './scenario.js';
 /** Renders frames until shaders and pipelines are compiled and nothing is skipped. */
 export declare function settle(app: App, frames?: number): Promise<void>;
 /** Settles, then captures a view. */