reze-engine 0.54.7 → 0.54.8

package/dist/shaders/passes/cast-distance.js

@@ -0,0 +1,269 @@
+import { EFFECT_SUBJECTS } from "../cast-layout";
+// How far is this pixel from the cast? — the primitive behind every silhouette
+// look, computed once and read by anyone.
+//
+// AN EFFECT CANNOT ANSWER THIS ITSELF, and that is the whole reason this pass
+// exists. Distance to the nearest drawn pixel is not a function of the pixel;
+// it is a function of every pixel around it. A shader with one pass can only go
+// looking, and searching a disc costs O(radius^2) per pixel — measured on the
+// first sticker-outline effect, a 9 pixel border cost 64 id samples on every
+// background pixel and a 16 pixel one cost 96 to 128. The look everybody wants
+// next is a wide one, and that is the direction the cost runs away in.
+//
+// A JUMP FLOOD costs log2(resolution) passes and answers for ANY distance. It
+// is the same 37 million reads at 1080p whether the effect wants a 4 pixel
+// border or a 400 pixel aura, and it is shared: two effects reading it pay for
+// it once.
+//
+// NO CAP ON THE DISTANCE. A partial flood — stopping early to save a pass —
+// would silently limit how far an effect could reach, and the engine has no
+// business deciding that. The author writes the falloff and pays for the width
+// they asked for in their own arithmetic, not in ours.
+//
+// FULL RESOLUTION, after trying not to be.
+//
+// Half res was tried twice and rejected on sight both times, and the reason is
+// worth recording because the arithmetic looked fine. A half-res distance field
+// really does place the edge to within a pixel — measured against an exact
+// transform, 0.22 px mean and 0.68 px at the 99th percentile. What that average
+// hides is that the error is not noise: it VARIES along the silhouette, so the
+// border breathes in and out by a fraction of a pixel as the edge turns, and an
+// edge that wobbles reads as jagged no matter how smoothly it is feathered.
+// Seeding at the sub-texel centroid rather than the texel centre halved it
+// (0.83 to 0.28 px mean on a curve) and it was still visible.
+//
+// So the field is the size of the frame and the seeds are exact. What that costs
+// at 1080p is about 224 million texture reads a frame, against 47 million at
+// half — real, and the honest price of an edge that does not crawl. It is still
+// the same cost whatever width an effect asks for, which is the whole point: the
+// per-pixel search this replaced cost 64 reads a pixel for a 9 px border and
+// four times that for an 18 px one.
+/** Whether any of this effect's source reads the field, and so whether the
+ *  engine should spend the passes building it. Nothing else turns it on. */
+export function castDistanceUsed(wgsl) {
+    return /\brzCastDistance\s*\(/.test(wgsl);
+}
+/** Seed and ping-pong target: the nearest seed's texel coordinate, or (-1,-1).
+ *  32-bit because these are coordinates — a half would quantise them at 2048
+ *  and put the seam of that error straight through a 4K frame. */
+export const CAST_SEED_FORMAT = "rg32float";
+/** The resolved distance, in FIELD texels. Sampled bilinearly, so it is filtered
+ *  rather than loaded, and r32float is not filterable everywhere — r16float is,
+ *  and half a texel of precision on a distance is nothing. */
+export const CAST_DIST_FORMAT = "r16float";
+/** Per-pixel MSAA coverage of the cast, written beside the seeds and read by the
+ *  resolve to place the edge inside the seed pixel. */
+export const CAST_COVERAGE_FORMAT = "r8unorm";
+/** The field is the size of the frame. See the note above for what half cost. */
+export const CAST_FIELD_DIV = 1;
+const FULLSCREEN_VS = /* wgsl */ `
+struct VSOut { @builtin(position) pos: vec4f };
+
+@vertex
+fn vs(@builtin(vertex_index) i: u32) -> VSOut {
+  // One oversized triangle rather than two: no seam down the diagonal, and the
+  // rasteriser does not have to think about a shared edge.
+  var p = array<vec2f, 3>(vec2f(-1.0, -3.0), vec2f(-1.0, 1.0), vec2f(3.0, 1.0));
+  var o: VSOut;
+  o.pos = vec4f(p[i], 0.0, 1.0);
+  return o;
+}
+`;
+/**
+ * Pass 1 — plant a seed on every pixel the CAST drew.
+ *
+ * The ground, a stage and a media plane all write ids exactly as she does, so
+ * seeding "anything drawn" would grow a border around the floor: a rectangle
+ * round the frame rather than a sticker. Only the subject ids seed.
+ */
+export function buildCastSeedShader(samples) {
+    return (
+    /* wgsl */ `
+const RZ_SUBJECTS: i32 = ${EFFECT_SUBJECTS};
+
+const RZ_ID_SAMPLES: i32 = ${samples};
+
+@group(0) @binding(0) var _rzIdTex: texture_multisampled_2d<u32>;
+@group(0) @binding(1) var<storage, read> _rzCast: array<vec4f>;
+
+// The two cast accessors this pass needs, spelled out rather than pulled in.
+// CAST_API brings subjects, trails, anchors and their aliases with it, and a
+// seed pass wants none of that — it asks one question about one id.
+fn rzSubjectCount() -> i32 {
+  var n = 0;
+  for (var i = 0; i < RZ_SUBJECTS; i++) {
+    if (_rzCast[i * 3 + 2].w > 0.0) { n = i + 1; }
+  }
+  return n;
+}
+fn rzSubjectId(i: i32) -> u32 {
+  if (i < 0 || i >= rzSubjectCount()) { return 0u; }
+  return u32(_rzCast[i * 3 + 1].w);
+}
+
+${FULLSCREEN_VS}
+
+struct SeedOut {
+  /** Where the nearest cast pixel is, for the flood to carry. */
+  @location(0) seed: vec2f,
+  /** How much of this pixel she covers, 0..1, for the resolve to place the edge
+   *  inside it. */
+  @location(1) coverage: f32,
+}
+
+@fragment
+fn fs(@builtin(position) pos: vec4f) -> SeedOut {
+  // COVERAGE, NOT A YES OR NO — this is the whole reason the border used to sit
+  // badly against her.
+  //
+  // The scene draws at 4x MSAA and the frame you see is resolved, so her edge is
+  // smooth. The id attachment is deliberately NOT resolved (an averaged id
+  // belongs to nothing), so reading sample 0 gives a hard, binary, aliased
+  // silhouette — a different edge from the one she is drawn with. A border grown
+  // off that can never sit flush against her: it traces the staircase while she
+  // has none.
+  //
+  // Counting the samples recovers what MSAA already knew. Four samples give five
+  // levels of coverage, the resolve turns that into a sub-pixel zero crossing,
+  // and the border meets her where she actually ends.
+  let dim = vec2<i32>(textureDimensions(_rzIdTex));
+  let p = clamp(vec2<i32>(pos.xy), vec2<i32>(0), dim - vec2<i32>(1));
+  let n = rzSubjectCount();
+  var covered = 0.0;
+  for (var sample = 0; sample < RZ_ID_SAMPLES; sample++) {
+    let o = textureLoad(_rzIdTex, p, sample).y;
+    if (o == 0u) { continue; }
+    for (var i = 0; i < n; i++) {
+      if (o == rzSubjectId(i)) { covered += 1.0; break; }
+    }
+  }
+  var out: SeedOut;
+  out.coverage = covered / f32(RZ_ID_SAMPLES);
+  // Anything she touches at all seeds, including a pixel she barely clips: a
+  // sliver is where the sub-pixel edge lives, and dropping it would put the
+  // staircase straight back.
+  // -1 is the empty marker, and every step below tests for it before believing
+  // a candidate.
+  out.seed = select(vec2f(-1.0, -1.0), pos.xy, covered > 0.0);
+  return out;
+}
+`);
+}
+/**
+ * Pass 2 — one jump-flood step, run once per halving of the stride.
+ *
+ * Each texel asks its eight neighbours at the current stride what seed THEY
+ * know about, and keeps whichever is nearest to itself. Starting at half the
+ * field's width and halving to one, a seed reaches every texel that is nearer
+ * to it than to any other — which is the definition of the field.
+ */
+export function buildCastStepShader() {
+    return /* wgsl */ `
+@group(0) @binding(0) var _rzPrev: texture_2d<f32>;
+@group(0) @binding(1) var<uniform> _rzStep: vec4f;   // (stride, _, _, _)
+
+${FULLSCREEN_VS}
+
+@fragment
+fn fs(@builtin(position) pos: vec4f) -> @location(0) vec2f {
+  let me = pos.xy;
+  let dim = vec2<i32>(textureDimensions(_rzPrev));
+  let stride = i32(_rzStep.x);
+  var best = textureLoad(_rzPrev, vec2<i32>(me), 0).xy;
+  // Squared throughout: the comparison is the only thing that matters and a
+  // square root per candidate is nine of them per texel per pass.
+  var bestD = select(1.0e30, dot(best - me, best - me), best.x >= 0.0);
+  for (var dy = -1; dy <= 1; dy++) {
+    for (var dx = -1; dx <= 1; dx++) {
+      let p = clamp(vec2<i32>(me) + vec2<i32>(dx, dy) * stride, vec2<i32>(0), dim - vec2<i32>(1));
+      let c = textureLoad(_rzPrev, p, 0).xy;
+      if (c.x < 0.0) { continue; }
+      let d = dot(c - me, c - me);
+      if (d < bestD) { bestD = d; best = c; }
+    }
+  }
+  return best;
+}
+`;
+}
+/**
+ * Pass 3 — turn the seed coordinates into a distance.
+ *
+ * Its own pass because the READ is bilinear. Interpolating coordinates across
+ * the boundary between two seeds averages two unrelated points and lands the
+ * result on neither; interpolating the DISTANCE is the smooth, honest thing,
+ * and it is what makes a half-res field cut a full-res edge.
+ */
+export function buildCastResolveShader() {
+    return /* wgsl */ `
+@group(0) @binding(0) var _rzSeed: texture_2d<f32>;
+@group(0) @binding(1) var _rzCoverage: texture_2d<f32>;
+
+${FULLSCREEN_VS}
+
+@fragment
+fn fs(@builtin(position) pos: vec4f) -> @location(0) f32 {
+  let s = textureLoad(_rzSeed, vec2<i32>(pos.xy), 0).xy;
+  // No cast on screen at all: everything is unreachably far from her, which is
+  // the answer that makes an effect draw nothing rather than everything.
+  if (s.x < 0.0) { return 1.0e30; }
+  let c = textureLoad(_rzCoverage, vec2<i32>(s), 0).x;
+  // SIGNED, WITH THE ZERO CROSSING INSIDE THE SEED PIXEL.
+  //
+  // A fully covered seed means her true edge runs about half a pixel outside its
+  // centre, so the distance to the EDGE is half a pixel less than the distance to
+  // the centre. A half-covered seed has the edge through its centre and wants no
+  // correction. A barely covered one has the edge nearly a half-pixel further in.
+  // All three are (c - 0.5).
+  //
+  // It also makes the field NEGATIVE inside her, and that is what lets an effect
+  // fade where it meets her rather than stopping dead on a texel boundary — the
+  // difference between a border that is attached and one that is merely nearby.
+  return length(s - pos.xy) - (c - 0.5);
+}
+`;
+}
+/**
+ * `rzCastDistance(uv)`, for the effects that read it.
+ *
+ * ALWAYS COMPILED IN, even when the pass is not running — it then samples a 1x1
+ * holding a very large number, so an effect keyed on it draws nothing instead of
+ * failing to compile. Same rule the grid's accessor follows, and the id
+ * accessors before it: an author should never have to guard a name.
+ */
+export function castDistanceApi(group, tex, samp, scale) {
+    return /* wgsl */ `
+@group(${group}) @binding(${tex}) var _rzCastDistTex: texture_2d<f32>;
+@group(${group}) @binding(${samp}) var _rzCastDistSamp: sampler;
+
+/**
+ * Distance from this point to the nearest pixel the CAST drew, in SCREEN pixels.
+ *
+ * ZERO ON HER, positive outside, and the crossing is sub-pixel — it comes from
+ * MSAA coverage, so it lands on the same edge she is drawn with rather than on
+ * the staircase a single sample sees. Fade an effect across zero and it attaches
+ * to her cleanly.
+ *
+ * IT IS NOT AN INTERIOR DEPTH. Every pixel she covers is a seed, so the nearest
+ * seed to a pixel deep inside her is itself: the answer there is 0, not "far
+ * in". What the coverage buys is half a pixel of sub-pixel placement at the
+ * boundary, which is exactly enough to anti-alias against her and no more — so
+ * the value inside her runs to -0.5 and no further. An effect that wants to
+ * reach INTO her wants a second flood seeded on the background, which this pass
+ * does not build. Guard on d >= 0 and fade across it.
+ *
+ * There is no ceiling. A pixel on the far side of the frame gets the real
+ * number. The ground, a stage and a media plane are not the cast and do not
+ * seed it.
+ *
+ * Screen pixels whatever the field's own resolution is, so an author writes the
+ * width they mean and never has to know how this is built. uv is the effect's
+ * own convention, origin bottom-left; the flip to texture rows happens here.
+ */
+fn rzCastDistance(uv: vec2f) -> f32 {
+  let flipped = vec2f(clamp(uv.x, 0.0, 1.0), 1.0 - clamp(uv.y, 0.0, 1.0));
+  let d = textureSampleLevel(_rzCastDistTex, _rzCastDistSamp, flipped, 0.0).x;
+  return d * ${scale > 0 ? scale : 1}.0;
+}
+`;
+}

package/dist/shaders/passes/composite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/composite.ts"],"names":[],"mappings":"AAyBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+BAgC+B;AAC/B;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,EAAE,CAIhG;AAID,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AAEzG,KAAK,qBAAqB,GAAG;IAC3B,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAA;IACZ,kFAAkF;IAClF,UAAU,EAAE,MAAM,CAAA;IAClB,4DAA4D;IAC5D,aAAa,EAAE,OAAO,CAAA;IACtB,oEAAoE;IACpE,aAAa,EAAE,OAAO,CAAA;IACtB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAA;IAChB;mFAC+E;IAC/E,GAAG,CAAC,EAAE,OAAO,CAAA;IACb;;;yEAGqE;IACrE,UAAU,EAAE,MAAM,CAAA;IAClB;;8EAE0E;IAC1E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CACjB,CAAA;AA6LD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,yqaA+H5B,CAAA;AA4LD,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,qBAAqB,GAAG,IAAI,GAAG,MAAM,CAQlF;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,CA4EtE;AAED,iFAAiF;AACjF,eAAO,MAAM,qBAAqB,QAA6B,CAAA"}
+{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/composite.ts"],"names":[],"mappings":"AA0BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+BAgC+B;AAC/B;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,EAAE,CAIhG;AAID,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AAEzG,KAAK,qBAAqB,GAAG;IAC3B,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAA;IACZ,kFAAkF;IAClF,UAAU,EAAE,MAAM,CAAA;IAClB,4DAA4D;IAC5D,aAAa,EAAE,OAAO,CAAA;IACtB,oEAAoE;IACpE,aAAa,EAAE,OAAO,CAAA;IACtB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAA;IAChB;mFAC+E;IAC/E,GAAG,CAAC,EAAE,OAAO,CAAA;IACb;;;yEAGqE;IACrE,UAAU,EAAE,MAAM,CAAA;IAClB;;8EAE0E;IAC1E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CACjB,CAAA;AA6LD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,yqaA+H5B,CAAA;AA4LD,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,qBAAqB,GAAG,IAAI,GAAG,MAAM,CAQlF;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,CAgFtE;AAED,iFAAiF;AACjF,eAAO,MAAM,qBAAqB,QAA6B,CAAA"}

package/dist/shaders/passes/composite.js

@@ -4,6 +4,7 @@ import { CAST_API } from "../cast-api";
 import { clockApi, EFFECT_MATH_API, PARTICLE_STRUCT_WGSL, trailSlotsApi, viewportApi } from "./hosted-api";
 import { audioApi } from "../audio-api";
 import { idApi } from "../id-api";
+import { castDistanceApi, CAST_FIELD_DIV } from "./cast-distance";
 import { lyricsApi, lyricsTextApi } from "../lyrics-api";
 import { midiApi } from "../midi-api";
 import { gridReadApi } from "./grid";
@@ -633,6 +634,10 @@ export function buildFieldShader(effect) {
         viewportApi("viewU[6].w") +
         trailSlotsApi(effect.trailCount) +
         idApi(effect.ids === true, 0, 23) +
+        // Distance to the cast, in SCREEN pixels: the field is half-res, so a field
+        // texel is CAST_FIELD_DIV of them and the accessor scales on the way out.
+        // An author writes the width they mean and never learns how it is built.
+        castDistanceApi(0, 26, 18, CAST_FIELD_DIV) +
         "\n// ── user effect (setEffect) ──\n" +
         effect.paramsDecl +
         "\n" +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reze-engine",
-  "version": "0.54.7",
+  "version": "0.54.8",
   "description": "A lightweight WebGPU engine for real-time 3D MMD/PMX model rendering",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/engine.ts

@@ -83,6 +83,16 @@ import {
   buildSimShader,
   gridEntryPoint,
 } from "./shaders/passes/grid"
+import {
+  buildCastResolveShader,
+  buildCastSeedShader,
+  buildCastStepShader,
+  castDistanceUsed,
+  CAST_COVERAGE_FORMAT,
+  CAST_DIST_FORMAT,
+  CAST_FIELD_DIV,
+  CAST_SEED_FORMAT,
+} from "./shaders/passes/cast-distance"
 import { buildTrailShader, trailEntryPoints, TRAIL_SUBDIVISIONS } from "./shaders/passes/trails"
 import { PICK_SHADER_WGSL } from "./shaders/passes/pick"
 import { MIPMAP_BLIT_SHADER_WGSL } from "./shaders/passes/mipmap"
@@ -1337,6 +1347,9 @@ interface EffectInstance {
    *  change while an effect is installed, and the frame path should not be
    *  running regexes. */
   readsIds: boolean
+  /** Does this source read the distance-to-cast field? Parsed at install for the
+   *  same reason readsIds is, and it turns the whole flood on by itself. */
+  readsCastDistance: boolean
   /** Bones this source asked for, in ITS OWN declaration order. The scene table
    *  maps these onto shared addresses; this list is what it is rebuilt from. */
   anchors: { bone: string; trail: boolean }[]
@@ -1686,6 +1699,34 @@ export class Engine {
     string,
     { modelName: string; groupId: string; paramId: string; keys: ParamKey[]; last: ParamValue | null }
   >()
+  /**
+   * The distance-to-cast field: seeds ping-ponged by a jump flood, then resolved.
+   *
+   * All null until some installed effect names rzCastDistance. Nothing is
+   * allocated and no pass is encoded for a scene that never asks — the same
+   * bargain the grid and the id buffer strike.
+   */
+  private castSeedTextures: (GPUTexture | null)[] = [null, null]
+  private castSeedViews: (GPUTextureView | null)[] = [null, null]
+  private castCoverageTexture: GPUTexture | null = null
+  private castCoverageView: GPUTextureView | null = null
+  private castDistTexture: GPUTexture | null = null
+  private castDistView: GPUTextureView | null = null
+  /** 1x1 holding half-float 65504, bound whenever the pass is not running: an
+   *  effect keyed on distance then finds the cast unreachably far and draws
+   *  nothing, rather than the accessor being a name that does not exist. */
+  private castDistFallback: GPUTexture | null = null
+  private castDistFallbackView: GPUTextureView | null = null
+  private castSeedPipeline: GPURenderPipeline | null = null
+  private castStepPipeline: GPURenderPipeline | null = null
+  private castResolvePipeline: GPURenderPipeline | null = null
+  private castSeedBindGroup: GPUBindGroup | null = null
+  private castStepBindGroups: GPUBindGroup[] = []
+  private castResolveBindGroup: GPUBindGroup | null = null
+  private castStepStrideBuffers: GPUBuffer[] = []
+  /** Does anything installed actually read the field? Set from the effect list. */
+  private castDistanceWanted = false
+
   private fieldBgTextures: (GPUTexture | null)[] = [null, null]
   private fieldBgViews: (GPUTextureView | null)[] = [null, null]
   private fieldFgTextures: (GPUTexture | null)[] = [null, null]
@@ -2795,8 +2836,149 @@ export class Engine {
     return this.fieldPairUsed(layer) && view ? view : this.trailFallbackView
   }
 
+  /**
+   * The distance field's textures, and the bind groups that walk the flood.
+   *
+   * Rebuilt with the field targets, because it is sized off the same swap chain
+   * and a resize invalidates every view. Torn down entirely when nothing reads
+   * it: the memory is two coordinate targets and a distance one at half res,
+   * which is real, and a scene with no such effect should not hold it.
+   */
+  private createCastDistanceTargets(): void {
+    for (const t of this.castSeedTextures) t?.destroy()
+    this.castCoverageTexture?.destroy()
+    this.castDistTexture?.destroy()
+    for (const b of this.castStepStrideBuffers) b.destroy()
+    this.castSeedTextures = [null, null]
+    this.castSeedViews = [null, null]
+    this.castCoverageTexture = null
+    this.castCoverageView = null
+    this.castDistTexture = null
+    this.castDistView = null
+    this.castStepStrideBuffers = []
+    this.castStepBindGroups = []
+    this.castSeedBindGroup = null
+    this.castResolveBindGroup = null
+    if (!this.device || !this.castDistanceWanted || this.fieldFullW === 0) return
+    if (!this.castSeedPipeline || !this.castStepPipeline || !this.castResolvePipeline) return
+
+    const w = Math.max(1, Math.ceil(this.fieldFullW / CAST_FIELD_DIV))
+    const h = Math.max(1, Math.ceil(this.fieldFullH / CAST_FIELD_DIV))
+    for (let i = 0; i < 2; i++) {
+      this.castSeedTextures[i] = this.device.createTexture({
+        label: `cast distance seeds ${i}`,
+        size: [w, h],
+        format: CAST_SEED_FORMAT,
+        usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
+      })
+      this.castSeedViews[i] = this.castSeedTextures[i]!.createView()
+    }
+    this.castCoverageTexture = this.device.createTexture({
+      label: "cast coverage",
+      size: [w, h],
+      format: CAST_COVERAGE_FORMAT,
+      usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
+    })
+    this.castCoverageView = this.castCoverageTexture.createView()
+    this.castDistTexture = this.device.createTexture({
+      label: "cast distance",
+      size: [w, h],
+      format: CAST_DIST_FORMAT,
+      usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
+    })
+    this.castDistView = this.castDistTexture.createView()
+
+    // The flood starts at half the longest side and halves to one. That is what
+    // makes it exact everywhere rather than out to some radius: every seed gets
+    // the chance to reach every texel it is nearest to.
+    const strides: number[] = []
+    for (let k = 1 << Math.ceil(Math.log2(Math.max(w, h))); k >= 1; k >>= 1) strides.push(k)
+
+    this.castSeedBindGroup = this.device.createBindGroup({
+      label: "cast distance seed",
+      layout: this.castSeedPipeline.getBindGroupLayout(0),
+      entries: [
+        { binding: 0, resource: this.idView! },
+        { binding: 1, resource: { buffer: this.castBuffer } },
+      ],
+    })
+    strides.forEach((stride, i) => {
+      const buf = this.device!.createBuffer({
+        label: `cast distance stride ${stride}`,
+        size: 16,
+        usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+      })
+      this.device!.queue.writeBuffer(buf, 0, new Float32Array([stride, 0, 0, 0]))
+      this.castStepStrideBuffers.push(buf)
+      // Pass i reads the texture pass i-1 wrote. The seed lands in 0, so an even
+      // pass reads 0 and writes 1.
+      this.castStepBindGroups.push(
+        this.device!.createBindGroup({
+          label: `cast distance step ${stride}`,
+          layout: this.castStepPipeline!.getBindGroupLayout(0),
+          entries: [
+            { binding: 0, resource: this.castSeedViews[i % 2]! },
+            { binding: 1, resource: { buffer: buf } },
+          ],
+        }),
+      )
+    })
+    this.castResolveBindGroup = this.device.createBindGroup({
+      label: "cast distance resolve",
+      layout: this.castResolvePipeline.getBindGroupLayout(0),
+      entries: [
+        { binding: 0, resource: this.castSeedViews[strides.length % 2]! },
+        { binding: 1, resource: this.castCoverageView! },
+      ],
+    })
+  }
+
+  /**
+   * The flood, encoded once a frame before the field pass reads it.
+   *
+   * Seed, then one pass per halving of the stride, then resolve to a distance.
+   * Nothing here depends on how far any effect intends to look — that is the
+   * whole point of paying for it in passes rather than in per-pixel search.
+   */
+  private encodeCastDistance(encoder: GPUCommandEncoder): void {
+    if (!this.castDistanceWanted || !this.castSeedBindGroup || !this.castResolveBindGroup) return
+    const seed = encoder.beginRenderPass({
+      label: "cast distance (seed)",
+      colorAttachments: [
+        { view: this.castSeedViews[0]!, loadOp: "clear", clearValue: { r: -1, g: -1, b: 0, a: 0 }, storeOp: "store" },
+        { view: this.castCoverageView!, loadOp: "clear", clearValue: { r: 0, g: 0, b: 0, a: 0 }, storeOp: "store" },
+      ],
+    })
+    seed.setPipeline(this.castSeedPipeline!)
+    seed.setBindGroup(0, this.castSeedBindGroup)
+    seed.draw(3)
+    seed.end()
+
+    this.castStepBindGroups.forEach((group, i) => {
+      const pass = encoder.beginRenderPass({
+        label: "cast distance (flood)",
+        colorAttachments: [{ view: this.castSeedViews[(i + 1) % 2]!, loadOp: "clear", clearValue: { r: -1, g: -1, b: 0, a: 0 }, storeOp: "store" }],
+      })
+      pass.setPipeline(this.castStepPipeline!)
+      pass.setBindGroup(0, group)
+      pass.draw(3)
+      pass.end()
+    })
+
+    const resolve = encoder.beginRenderPass({
+      label: "cast distance (resolve)",
+      colorAttachments: [{ view: this.castDistView!, loadOp: "clear", clearValue: { r: 0, g: 0, b: 0, a: 0 }, storeOp: "store" }],
+    })
+    resolve.setPipeline(this.castResolvePipeline!)
+    resolve.setBindGroup(0, this.castResolveBindGroup)
+    resolve.draw(3)
+    resolve.end()
+  }
+
   private createFieldTargets(): void {
     if (!this.device || this.fieldFullW === 0) return
+    // Same swap chain, same invalidation.
+    this.createCastDistanceTargets()
     for (let i = 0; i < Engine.FIELD_SCALES.length; i++) {
       const scale = Engine.FIELD_SCALES[i]
       const w = Math.max(1, Math.ceil(this.fieldFullW / scale))
@@ -2857,6 +3039,7 @@ export class Engine {
           ...(this.idView ? [{ binding: 23, resource: this.idView }] : []),
           { binding: 17, resource: grid },
           { binding: 18, resource: this.simSampler },
+          { binding: 26, resource: this.castDistView ?? this.castDistFallbackView! },
         ],
       })
     // Per effect: the params buffer and the grid are both its own, so two
@@ -3422,6 +3605,7 @@ export class Engine {
         // so matching against it would report every effect as a reader and the
         // attachment would be stored exactly as often as before.
         readsIds: /\brz(?:ObjectAt|MaterialAt)\s*\(/.test(wgsl),
+        readsCastDistance: castDistanceUsed(wgsl),
         anchors,
         // The effect's own clock starts now. Per effect so that one installed
         // later still gets a frame where rzGridFrame() is 0 and can seed.
@@ -3571,6 +3755,17 @@ export class Engine {
     this.releaseTrails()
     this.releaseGrid()
     this.effects = instances
+    // Turn the distance field on or off with the list that asked for it. Only
+    // rebuilds when the answer CHANGES: the targets are half-res render
+    // attachments and reallocating them per install would churn them for every
+    // unrelated effect a scene adds.
+    const wantsCastDistance = instances.some((e) => e.readsCastDistance)
+    if (wantsCastDistance !== this.castDistanceWanted) {
+      this.castDistanceWanted = wantsCastDistance
+      this.createCastDistanceTargets()
+      // The field bind groups name the distance texture, and it has just been
+      // created or destroyed — they are rebuilt below with the new list anyway.
+    }
     // The new list's emitters need their slots before the next frame reads them.
     this.allocateLightSlots()
     // A rig the cap refused is worth saying out loud on the effect that asked
@@ -4207,6 +4402,10 @@ export class Engine {
     // two 16MB writes a frame to produce the transparent black the fallback
     // already is. Most scenes leave the full-res pair empty, since an effect only
     // lands there by declaring #fullres.
+    // The distance field, before anything reads it. Returns immediately when no
+    // installed effect names rzCastDistance, which is the common case.
+    this.encodeCastDistance(encoder)
+
     let stamped = false
     for (let i = 0; i < Engine.FIELD_SCALES.length; i++) {
       const bg = this.fieldBgViews[i]
@@ -5202,12 +5401,68 @@ export class Engine {
           : []),
         { binding: 17, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float", viewDimension: "2d" } },
         { binding: 18, visibility: GPUShaderStage.FRAGMENT, sampler: { type: "filtering" } },
+        // Distance to the cast. Always in the layout — the accessor is always
+        // compiled, and a 1x1 stands in when the flood is not running, so an
+        // author never has to guard the name.
+        { binding: 26, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float", viewDimension: "2d" } },
       ],
     })
     this.fieldPipelineLayout = this.device.createPipelineLayout({
       bindGroupLayouts: [this.fieldBindGroupLayout],
     })
 
+    // ── The distance-to-cast field's three pipelines ──
+    //
+    // Built once, whether or not anything reads the field: they cost a shader
+    // module each and nothing per frame, and building them lazily would put a
+    // pipeline compile in the frame where an author first types the name.
+    {
+      const seedModule = this.device.createShaderModule({ label: "cast distance seed", code: buildCastSeedShader(Engine.MULTISAMPLE_COUNT) })
+      const stepModule = this.device.createShaderModule({ label: "cast distance step", code: buildCastStepShader() })
+      const resolveModule = this.device.createShaderModule({ label: "cast distance resolve", code: buildCastResolveShader() })
+      this.castSeedPipeline = this.device.createRenderPipeline({
+        label: "cast distance seed",
+        layout: "auto",
+        vertex: { module: seedModule, entryPoint: "vs" },
+        fragment: {
+          module: seedModule,
+          entryPoint: "fs",
+          targets: [{ format: CAST_SEED_FORMAT }, { format: CAST_COVERAGE_FORMAT }],
+        },
+        primitive: { topology: "triangle-list" },
+      })
+      this.castStepPipeline = this.device.createRenderPipeline({
+        label: "cast distance step",
+        layout: "auto",
+        vertex: { module: stepModule, entryPoint: "vs" },
+        fragment: { module: stepModule, entryPoint: "fs", targets: [{ format: CAST_SEED_FORMAT }] },
+        primitive: { topology: "triangle-list" },
+      })
+      this.castResolvePipeline = this.device.createRenderPipeline({
+        label: "cast distance resolve",
+        layout: "auto",
+        vertex: { module: resolveModule, entryPoint: "vs" },
+        fragment: { module: resolveModule, entryPoint: "fs", targets: [{ format: CAST_DIST_FORMAT }] },
+        primitive: { topology: "triangle-list" },
+      })
+      // 65504 is the largest half float. Bound wherever the field is not
+      // running, so rzCastDistance answers "unreachably far" and an effect keyed
+      // on it draws nothing at all.
+      this.castDistFallback = this.device.createTexture({
+        label: "cast distance fallback (1x1, far)",
+        size: [1, 1],
+        format: CAST_DIST_FORMAT,
+        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+      })
+      this.device.queue.writeTexture(
+        { texture: this.castDistFallback },
+        new Uint16Array([0x7bff]),
+        { bytesPerRow: 2 },
+        { width: 1, height: 1 },
+      )
+      this.castDistFallbackView = this.castDistFallback.createView()
+    }
+
     this.fallbackMaterialTexture = this.device.createTexture({
       label: "fallback material texture (1x1 white)",
       size: [1, 1],
@@ -10884,7 +11139,9 @@ export class Engine {
     // whose result no one is going to read.
     const idAtt = (this.renderPassDescriptor.colorAttachments as GPURenderPassColorAttachment[])[2]
     if (idAtt) {
-      const idsRead = this.idDebug || this.effects.some((e) => e.readsIds)
+      // The flood seeds from the id attachment, so an effect that reads only the
+      // DISTANCE still needs the ids kept — it just never names them itself.
+      const idsRead = this.idDebug || this.effects.some((e) => e.readsIds || e.readsCastDistance)
       idAtt.storeOp = idsRead ? "store" : "discard"
     }