@woosh/meep-engine 3.59.0 → 3.60.0

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_project.js

@@ -9,15 +9,19 @@ import { f32, u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
 import {
     chunk_probe_clipmap,
+    chunk_probe_clipmap_guide,
+    PROBE_GUIDE_READ_RESOURCE,
     PROBE_MAPS_READ_RESOURCE,
     PROBE_PROJECTION_READ_RESOURCE,
     PROBE_PROJECTION_ROW_STRUCT,
     PROBE_PROJECTION_WRITE_RESOURCE,
     PROBE_RECORDS_STORE_RESOURCE,
+    PROBE_REQUEST_STRUCT,
+    PROBE_REQUESTS_WRITE_RESOURCE,
     PROBE_STATES_STORE_RESOURCE,
     PROBE_TRACE_READ_RESOURCE
 } from "./chunk_probe_clipmap.js";
-import { PROBE_DEAD_BACK_FACE_SHARE, PROBE_THREAD_WORKGROUP_SIZE } from "./PROBE_CLIPMAP.js";
+import { PROBE_CHANGE_SIGNIFICANCE, PROBE_DEAD_BACK_FACE_SHARE, PROBE_RADIANCE_SAMPLES_LIMIT, PROBE_THREAD_WORKGROUP_SIZE } from "./PROBE_CLIPMAP.js";
 
 /**
  * @type {WebGPUStruct}
@@ -25,12 +29,22 @@ import { PROBE_DEAD_BACK_FACE_SHARE, PROBE_THREAD_WORKGROUP_SIZE } from "./PROBE
 export const PROBE_PROJECT_SETTINGS = WebGPUStruct.from({
     /** probes a frame updates at most: the trace list's bound */
     trace_capacity: u32,
+    /** rays a uniform update casts, R */
+    rays_per_probe: u32,
     /** octahedral radiance texels a side, n_r */
     radiance_resolution: u32,
     /** octahedral depth texels a side, n_d */
     depth_resolution: u32,
-    /** the frame's time on the records' clock, seconds */
-    time: f32,
+    /** the frame, of the frames the clipmap has recorded */
+    frame: u32,
+    /** updates between a probe's uniform ones, `PROBE_UNIFORM_PERIOD` */
+    uniform_period: u32,
+    /** the fewest rays an update casts, `PROBE_RAYS_PER_TEXEL_MIN` of the texels */
+    rays_min: u32,
+    /** the most rays an update casts, `PROBE_RAYS_PER_TEXEL_MAX` of the texels */
+    rays_max: u32,
+    /** the radiance's short mean's response, τ, in frames: the change score's statistics follow it */
+    response_frames: f32,
 }, "ProbeProjectSettings");
 
 const row_resources = new ShaderResourceSetDescriptor();
@@ -46,8 +60,9 @@ row_resources.createGroup()
  * Projection, rows (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.8): a thread a row of each listed probe's
  * radiance map, dispatched through `PROBE_DISPATCH_ROWS`. It sums the row's texels, new and kept, as
  * irradiance SH, `convert_to_irradiance_sh(L, ω)·dω/(2π)` over each texel's solid angle, so that the
- * resolve gives E/π; and the row's rays this update, resolved and back faces. One row of the probe's
- * projection each, which the probe's pass sums.
+ * resolve gives E/π; the row's rays this update, resolved and back faces; and how far the update's
+ * samples fell from their means, with that sum's variance. One row of the probe's projection each, which
+ * the probe's pass sums.
  *
  * @type {ComputeShader}
  */
@@ -84,11 +99,14 @@ fn main(
         let weight = octahedral_solid_angle(uv, inverse) * ${(0.5 / Math.PI).toPrecision(17)};
         let sh = convert_to_irradiance_sh(light, uv_octahedral_unit_decode(uv));
         let rays = probe_maps[maps + 2u * texels + i];
+        let change = unpack2x16float(probe_maps[maps + 3u * texels + settings.depth_resolution * settings.depth_resolution + i]);
 
         row_sum.sh.CoCg += sh.CoCg * weight;
         row_sum.sh.Y += sh.Y * weight;
         row_sum.resolved += rays & 0xFFFFu;
         row_sum.back_faces += rays >> 16u;
+        row_sum.change += change.x;
+        row_sum.blended += change.y;
     }
 
     probe_projection[thread] = row_sum;
@@ -110,8 +128,10 @@ probe_resources.setImmediate("settings", PROBE_PROJECT_SETTINGS);
 probe_resources.createGroup()
     .add(PROBE_TRACE_READ_RESOURCE)
     .add(PROBE_PROJECTION_READ_RESOURCE)
+    .add(PROBE_GUIDE_READ_RESOURCE)
     .add(PROBE_STATES_STORE_RESOURCE)
-    .add(PROBE_RECORDS_STORE_RESOURCE);
+    .add(PROBE_RECORDS_STORE_RESOURCE)
+    .add(PROBE_REQUESTS_WRITE_RESOURCE);
 
 /**
  * Projection, probes (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.4, §8.8): a thread a listed probe,
@@ -119,6 +139,27 @@ probe_resources.createGroup()
  * by the update's resolved rays: dead past a quarter of back faces, else alive, its update counted and
  * its time the frame's. An update with no resolved ray keeps the probe's kind.
  *
+ * Only uniform rays classify. Those are a uniform update's, and a guided update's whose guide weighs
+ * nothing (a dark history), which spreads its rays evenly. A guided update's rays shun back faces, whose
+ * radiance is nothing, so their share would read a probe inside a solid as alive. Such an update keeps
+ * the probe's kind and its back-face share.
+ *
+ * **The probe's ray request** (§8.6): the rays its next guided update asks for, in `probe_requests`.
+ * - After a probe's first update, the most: Enshrouded's new probe that asks for all it can have.
+ * - When its light has moved, the most again. The update's change score sums its blended texels' falls
+ *   from their means, luminance, each in its own deviation and held to `PROBE_CHANGE_SIGNIFICANCE` by
+ *   accumulation, over the root of their count. A test texel by texel sees no change under a one-ray
+ *   texel's own noise (measured: the estimator's inconsistency barely moves on a doubling); a sum of the
+ *   falls unbounded is one bright sample's.
+ * - The score is held to the probe's own: moved means past `PROBE_CHANGE_SIGNIFICANCE` of its running
+ *   deviation, at least one, from its running mean, both over the estimator's variance window (2τ). A
+ *   probe whose means sit off its samples (the estimator's own bias on texels lit by few rays) scores
+ *   steadily off zero.
+ * - Measured, Sponza on the 4090, the camera and the light still, 3,600 frames settled: of the probes
+ *   past 64 updates, 4.2% asked for the most against a sum of the raw falls held to zero, 3.2% with each
+ *   texel's fall bounded, and 1.1–1.3% held to their own statistics.
+ * - Otherwise half what it asked for last, down to the fewest: a converged probe sips.
+ *
  * @type {ComputeShader}
  */
 export const shader_probe_clipmap_project = ComputeShader.from({
@@ -150,6 +191,8 @@ fn main(
         sum.sh.Y += part.sh.Y;
         sum.resolved += part.resolved;
         sum.back_faces += part.back_faces;
+        sum.change += part.change;
+        sum.blended += part.blended;
     }
 
     let state = probe_states[slot].x;
@@ -157,21 +200,58 @@ fn main(
 
     var kind = probe_state_kind(state);
 
-    if (sum.resolved > 0u) {
+    // the guide's total, less the even shares, is the weight its luminance gave
+    let header = k * probe_clipmap_guide_words(n) + 2u * n * n + 2u * n;
+    let weighed = probe_guide[header] != probe_guide[header + 1u] * n * n;
+    let uniform = !probe_clipmap_guided(state, settings.uniform_period, settings.rays_per_probe, n * n) || !weighed;
+
+    if (sum.resolved > 0u && uniform) {
         let share = f32(sum.back_faces) / f32(sum.resolved);
 
         kind = select(PROBE_STATE_ALIVE, PROBE_STATE_DEAD, share > ${PROBE_DEAD_BACK_FACE_SHARE});
 
-        probe_records[slot].back_face = share;
+        probe_records[slot].flags = (probe_records[slot].flags & 0xFFFF0000u) | probe_record_flags(share, false, 0u);
     }
 
+    let elapsed = f32(settings.frame - probe_records[slot].traced_frame);
+
     probe_states[slot].x = probe_state(kind, updates + 1u);
-    probe_records[slot].sh = sum.sh;
-    probe_records[slot].traced_time = settings.time;
+    probe_records[slot].sh = probe_record_sh_encode(sum.sh);
+    probe_records[slot].traced_frame = settings.frame;
+
+    // the next guided update's rays: the most after the first update and whenever the light moved, else half
+    var request = probe_requests[slot];
+
+    if (updates == 0u) {
+        // its slot's last owner's statistics are not its own
+        request = ${PROBE_REQUEST_STRUCT.make({ rays: "settings.rays_max", change_mean: "0.0", change_variance: "0.0", changes: "0u" })};
+    } else if (sum.blended > 0.0) {
+        let score = sum.change / sqrt(sum.blended);
+        let reach = ${PROBE_CHANGE_SIGNIFICANCE} * max(sqrt(request.change_variance), 1.0);
+        let moved = abs(score - request.change_mean) > reach;
+
+        // the score's running statistics, a running mean while young, then over the estimator's variance
+        // window; a score past their reach counts at it, so a change in the light does not become the probe's
+        // own spread, while a lasting shift of its own still does within a few windows
+        let held = clamp(score, request.change_mean - reach, request.change_mean + reach);
+        let blend = max(1.0 / f32(request.changes + 1u), 1.0 - exp(-0.5 * elapsed / settings.response_frames));
+        let mean = mix(request.change_mean, held, blend);
+
+        request.change_variance = mix(request.change_variance, (held - request.change_mean) * (held - mean), blend);
+        request.change_mean = mean;
+        request.changes = min(request.changes + 1u, ${PROBE_RADIANCE_SAMPLES_LIMIT}u);
+        request.rays = select(max(settings.rays_min, request.rays >> 1u), settings.rays_max, moved);
+    } else {
+        request.rays = max(settings.rays_min, request.rays >> 1u);
+    }
+
+    probe_requests[slot] = request;
 }
 `, [
             chunk_probe_clipmap,
+            chunk_probe_clipmap_guide,
             chunk_folded_workgroup_index,
             PROBE_PROJECTION_ROW_STRUCT.declaration_chunk,
+            PROBE_REQUEST_STRUCT.declaration_chunk,
         ]),
 });

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_ray_layout.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_RAY_COUNTS_SETTINGS: WebGPUStruct;
+/**
+ * The ray counts (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.6): a thread a listed probe, dispatched through
+ * `PROBE_DISPATCH_TRACED`, writes the rays its update casts, as two parts whose counts the trace command
+ * wrote:
+ * - `probe_ray_counts`, what the budget does not scale: a uniform update's R, a NEW probe's among them,
+ *   and a DEAD probe's fewest, whose updates are all uniform. A uniform update's map of rays to texels
+ *   takes a power of two, and U = ⌊budget / R⌋ makes room for a frame of them.
+ * - `probe_ray_requests`, what it does: a guided update's request, the rays the probe asked for after its
+ *   last update (`probe_requests`), at least the fewest.
+ *
+ * Their scans, and the ray layout pass after them, lay the frame's rays out (`probe_ray_sums`).
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_ray_counts: ComputeShader;
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_RAY_LAYOUT_SETTINGS: WebGPUStruct;
+/**
+ * The ray layout (§8.6): a thread a listed probe, dispatched through `PROBE_DISPATCH_TRACED`, once the
+ * counts and the requests are scanned. The requests share what the budget leaves past the counts, all of
+ * them when they fit, in proportion when they do not (Enshrouded's requests scaled to the budget), and
+ * the k-th probe's rays end at its counts' sum and its requests' sum so scaled, rounded down. The rounded
+ * sums never fall as k rises and their last is under the budget, so the probes' rays partition the
+ * frame's without a second scan. The trace command wrote the sums' count.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_ray_layout: ComputeShader;
+/**
+ * The rays' command (§8.6): one thread, once the rays are laid out, writes a thread a ray of the frame's,
+ * its count the last sum, at `PROBE_DISPATCH_RAYS`: trace, shade, light, and the next frame's hits'
+ * wants. The last workgroup's threads past the last ray are trace's to mark (`PROBE_RAY_NONE`).
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_ray_command: ComputeShader;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_probe_clipmap_ray_layout.d.ts.map

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_ray_layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_probe_clipmap_ray_layout.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_ray_layout.js"],"names":[],"mappings":"AAuBA;;GAEG;AACH,wCAFU,YAAY,CAaO;AAa7B;;;;;;;;;;;;;GAaG;AACH,8CAFU,aAAa,CAyCpB;AAEH;;GAEG;AACH,wCAFU,YAAY,CAOO;AAW7B;;;;;;;;;GASG;AACH,8CAFU,aAAa,CA+BpB;AAQH;;;;;;GAMG;AACH,+CAFU,aAAa,CA4BpB;6BAtM0B,sCAAsC;8BAHrC,kCAAkC"}

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_ray_layout.js

@@ -0,0 +1,205 @@
+import { chunk_folded_dispatch } from "../../../gpu_primitive/indirect/chunk_folded_dispatch.js";
+import { chunk_folded_workgroup_index } from "../../../shader/chunk/grid/chunk_folded_workgroup_index.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import {
+    chunk_probe_clipmap,
+    chunk_probe_clipmap_guide,
+    PROBE_DISPATCH_RESOURCE,
+    PROBE_RAY_COUNT_SUMS_READ_RESOURCE,
+    PROBE_RAY_COUNTS_WRITE_RESOURCE,
+    PROBE_RAY_REQUEST_SUMS_READ_RESOURCE,
+    PROBE_RAY_REQUESTS_WRITE_RESOURCE,
+    PROBE_RAY_SUMS_READ_RESOURCE,
+    PROBE_RAY_SUMS_WRITE_RESOURCE,
+    PROBE_REQUESTS_READ_RESOURCE,
+    PROBE_STATES_READ_RESOURCE,
+    PROBE_TRACE_READ_RESOURCE
+} from "./chunk_probe_clipmap.js";
+import { PROBE_THREAD_WORKGROUP_SIZE } from "./PROBE_CLIPMAP.js";
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_RAY_COUNTS_SETTINGS = WebGPUStruct.from({
+    /** probes a frame updates at most: the trace list's bound */
+    trace_capacity: u32,
+    /** rays a uniform update casts, R */
+    rays_per_probe: u32,
+    /** the fewest rays an update casts, a DEAD probe's, `PROBE_RAYS_PER_TEXEL_MIN` of the texels */
+    rays_min: u32,
+    /** octahedral radiance texels a side, n_r */
+    radiance_resolution: u32,
+    /** updates between a probe's uniform ones, `PROBE_UNIFORM_PERIOD` */
+    uniform_period: u32,
+}, "ProbeRayCountsSettings");
+
+const counts_resources = new ShaderResourceSetDescriptor();
+
+counts_resources.setImmediate("settings", PROBE_RAY_COUNTS_SETTINGS);
+
+counts_resources.createGroup()
+    .add(PROBE_TRACE_READ_RESOURCE)
+    .add(PROBE_STATES_READ_RESOURCE)
+    .add(PROBE_REQUESTS_READ_RESOURCE)
+    .add(PROBE_RAY_COUNTS_WRITE_RESOURCE)
+    .add(PROBE_RAY_REQUESTS_WRITE_RESOURCE);
+
+/**
+ * The ray counts (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.6): a thread a listed probe, dispatched through
+ * `PROBE_DISPATCH_TRACED`, writes the rays its update casts, as two parts whose counts the trace command
+ * wrote:
+ * - `probe_ray_counts`, what the budget does not scale: a uniform update's R, a NEW probe's among them,
+ *   and a DEAD probe's fewest, whose updates are all uniform. A uniform update's map of rays to texels
+ *   takes a power of two, and U = ⌊budget / R⌋ makes room for a frame of them.
+ * - `probe_ray_requests`, what it does: a guided update's request, the rays the probe asked for after its
+ *   last update (`probe_requests`), at least the fewest.
+ *
+ * Their scans, and the ray layout pass after them, lay the frame's rays out (`probe_ray_sums`).
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_ray_counts = ComputeShader.from({
+    label: "Probe Clipmap Ray Counts",
+    resources: counts_resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(${PROBE_THREAD_WORKGROUP_SIZE})
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) lane: u32,
+) {
+    let k = folded_workgroup_index(workgroup_id) * PROBE_THREAD_WORKGROUP_SIZE + lane;
+
+    if (k >= min(probe_trace.count, settings.trace_capacity)) {
+        return;
+    }
+
+    let slot = probe_trace.elements[k];
+    let state = probe_states[slot].x;
+    let n = settings.radiance_resolution;
+
+    var fixed = settings.rays_per_probe;
+    var request = 0u;
+
+    if (probe_state_kind(state) == PROBE_STATE_DEAD) {
+        fixed = settings.rays_min;
+    } else if (probe_clipmap_guided(state, settings.uniform_period, settings.rays_per_probe, n * n)) {
+        fixed = 0u;
+        request = max(probe_requests[slot].rays, settings.rays_min);
+    }
+
+    probe_ray_counts.elements[k] = fixed;
+    probe_ray_requests.elements[k] = request;
+}
+`, [
+            chunk_probe_clipmap,
+            chunk_probe_clipmap_guide,
+            chunk_folded_workgroup_index,
+        ]),
+});
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_RAY_LAYOUT_SETTINGS = WebGPUStruct.from({
+    /** probes a frame updates at most: the trace list's bound */
+    trace_capacity: u32,
+    /** rays a frame casts at most */
+    ray_budget: u32,
+}, "ProbeRayLayoutSettings");
+
+const layout_resources = new ShaderResourceSetDescriptor();
+
+layout_resources.setImmediate("settings", PROBE_RAY_LAYOUT_SETTINGS);
+
+layout_resources.createGroup()
+    .add(PROBE_RAY_COUNT_SUMS_READ_RESOURCE)
+    .add(PROBE_RAY_REQUEST_SUMS_READ_RESOURCE)
+    .add(PROBE_RAY_SUMS_WRITE_RESOURCE);
+
+/**
+ * The ray layout (§8.6): a thread a listed probe, dispatched through `PROBE_DISPATCH_TRACED`, once the
+ * counts and the requests are scanned. The requests share what the budget leaves past the counts, all of
+ * them when they fit, in proportion when they do not (Enshrouded's requests scaled to the budget), and
+ * the k-th probe's rays end at its counts' sum and its requests' sum so scaled, rounded down. The rounded
+ * sums never fall as k rises and their last is under the budget, so the probes' rays partition the
+ * frame's without a second scan. The trace command wrote the sums' count.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_ray_layout = ComputeShader.from({
+    label: "Probe Clipmap Ray Layout",
+    resources: layout_resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(${PROBE_THREAD_WORKGROUP_SIZE})
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) lane: u32,
+) {
+    let k = folded_workgroup_index(workgroup_id) * PROBE_THREAD_WORKGROUP_SIZE + lane;
+    let listed = probe_ray_count_sums.count;
+
+    if (k >= listed) {
+        return;
+    }
+
+    let counted = probe_ray_count_sums.elements[listed - 1u];
+    let requested = probe_ray_request_sums.elements[listed - 1u];
+    let room = select(0u, settings.ray_budget - counted, settings.ray_budget > counted);
+    let scale = select(1.0, f32(room) / f32(requested), requested > room);
+
+    probe_ray_sums.elements[k] = probe_ray_count_sums.elements[k] + u32(floor(scale * f32(probe_ray_request_sums.elements[k])));
+}
+`, [
+            chunk_probe_clipmap,
+            chunk_folded_workgroup_index,
+        ]),
+});
+
+const command_resources = new ShaderResourceSetDescriptor();
+
+command_resources.createGroup()
+    .add(PROBE_RAY_SUMS_READ_RESOURCE)
+    .add(PROBE_DISPATCH_RESOURCE);
+
+/**
+ * The rays' command (§8.6): one thread, once the rays are laid out, writes a thread a ray of the frame's,
+ * its count the last sum, at `PROBE_DISPATCH_RAYS`: trace, shade, light, and the next frame's hits'
+ * wants. The last workgroup's threads past the last ray are trace's to mark (`PROBE_RAY_NONE`).
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_ray_command = ComputeShader.from({
+    label: "Probe Clipmap Ray Command",
+    resources: command_resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(1)
+fn main() {
+    let listed = probe_ray_sums.count;
+
+    var total = 0u;
+
+    if (listed > 0u) {
+        total = probe_ray_sums.elements[listed - 1u];
+    }
+
+    let rays = folded_dispatch((total + PROBE_THREAD_WORKGROUP_SIZE - 1u) / PROBE_THREAD_WORKGROUP_SIZE);
+
+    probe_dispatch[PROBE_DISPATCH_RAYS] = rays.x;
+    probe_dispatch[PROBE_DISPATCH_RAYS + 1u] = rays.y;
+    probe_dispatch[PROBE_DISPATCH_RAYS + 2u] = rays.z;
+}
+`, [
+            chunk_probe_clipmap,
+            chunk_folded_dispatch,
+        ]),
+});

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_relocate.js

@@ -87,7 +87,7 @@ fn main(
     }
 
     let slot = probe_trace.elements[index];
-    let spacing = probe_levels[probe_records[slot].cascade].cell_size;
+    let spacing = probe_levels[probe_record_cascade(probe_records[slot].flags)].cell_size;
     let lattice = vec3<f32>(probe_records[slot].cell) * spacing;
     let clearance = ${PROBE_RELOCATION_CLEARANCE} * spacing;
 

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_retire.d.ts

@@ -6,9 +6,22 @@ export const PROBE_RETIRE_SETTINGS: WebGPUStruct;
  * Retire (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3): a thread a live probe, the first of the frame's
  * lifetime passes, dispatched through `PROBE_DISPATCH_ACTIVE` over the list the frame before wrote.
  *
- * A probe is freed when its lattice point has left its cascade's window, or when nothing, pixel or hit,
- * has wanted it for longer than the retention time: its slot goes back on the free list, its state to
- * FREE, and its indirection entry, if it still names the slot, to none. The rest go on the frame's list.
+ * A probe is freed when its lattice point has left its cascade's window, or when the last frame's
+ * schedule asked for its slot: its slot goes back on the free list, its state to FREE, and its
+ * indirection entry, if it still names the slot, to none. The rest go on the frame's list.
+ *
+ * Eviction follows the pressure on the slots, not a time (Enshrouded's cache): schedule asks for as many
+ * slots as the free ones are short of the frame's wanted points and `PROBE_FREE_SLACK` of the capacity,
+ * least recently wanted first, so with room to spare a probe keeps its history however long nothing
+ * wants it. It asks by the probes' age buckets (`probe_clipmap_age_bucket` of the frames since the probe
+ * was last wanted), `PROBE_EVICTION_STRUCT`: the oldest buckets whole, and a number of the bucket below
+ * them, which the frame's threads take while `PROBE_COUNTER_EVICTED` is under it. A probe in use is
+ * never evicted: one a want waits on, NEW or wanted since its last update, and one wanted the last
+ * frame. Where those fill the slots, an admission starves and the capacity grows (§7.10).
+ *
+ * Every probe it keeps that it could have evicted is counted into its age's bucket, from
+ * `PROBE_COUNTER_AGES`, for the frame's schedule to choose the next eviction by; and every one it keeps
+ * that waits for an update into `PROBE_COUNTER_WAITING`, for the period.
  *
  * Running before want means a window's move needs no pass of its own: the storage cells it vacated
  * are emptied before any point it exposed can claim them.

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_retire.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_probe_clipmap_retire.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_retire.js"],"names":[],"mappings":"AAuBA;;GAEG;AACH,oCAFU,YAAY,CAWI;AAgB1B;;;;;;;;;;;;GAYG;AACH,0CAFU,aAAa,CAuDpB;6BA5G0B,sCAAsC;8BAHrC,kCAAkC"}
+{"version":3,"file":"shader_probe_clipmap_retire.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_retire.js"],"names":[],"mappings":"AAyBA;;GAEG;AACH,oCAFU,YAAY,CASI;AAiB1B;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,0CAFU,aAAa,CAsFpB;6BAxJ0B,sCAAsC;8BAHrC,kCAAkC"}

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_retire.js

@@ -3,16 +3,18 @@ import { chunk_slot_stack } from "../../../gpu_primitive/slot_stack/chunk_slot_s
 import { chunk_clipmap_contains } from "../../../shader/chunk/clipmap/chunk_clipmap_contains.js";
 import { chunk_clipmap_storage_coord } from "../../../shader/chunk/clipmap/chunk_clipmap_storage_coord.js";
 import { chunk_folded_workgroup_index } from "../../../shader/chunk/grid/chunk_folded_workgroup_index.js";
+import { chunk_subgroup_atomic_add } from "../../../shader/chunk/subgroup/chunk_subgroup_atomic_add.js";
 import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
 import { ComputeShader } from "../../../shader/ComputeShader.js";
 import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
-import { f32, u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
 import {
     chunk_probe_clipmap,
     PROBE_ACTIVE_READ_RESOURCE,
     PROBE_ACTIVE_WRITE_RESOURCE,
     PROBE_COUNTERS_RESOURCE,
+    PROBE_EVICTION_READ_RESOURCE,
     PROBE_FREE_RESOURCE,
     PROBE_INDIRECTION_STORE_RESOURCE,
     PROBE_LEVELS_RESOURCE,
@@ -29,10 +31,8 @@ export const PROBE_RETIRE_SETTINGS = WebGPUStruct.from({
     capacity: u32,
     /** lattice points a cascade's window has a side */
     resolution: u32,
-    /** the frame's time, seconds since the clipmap was made */
-    time: f32,
-    /** seconds an unwanted probe keeps its slot, `retention_time` */
-    retention_time: f32,
+    /** the frame, of the frames the clipmap has recorded: a probe wanted the frame before it or since is not evicted */
+    frame: u32,
 }, "ProbeRetireSettings");
 
 const resources = new ShaderResourceSetDescriptor();
@@ -45,6 +45,7 @@ resources.createGroup()
     .add(PROBE_STATES_STORE_RESOURCE)
     .add(PROBE_RECORDS_STORE_RESOURCE)
     .add(PROBE_COUNTERS_RESOURCE)
+    .add(PROBE_EVICTION_READ_RESOURCE)
     .add(PROBE_FREE_RESOURCE)
     .add(PROBE_ACTIVE_READ_RESOURCE)
     .add(PROBE_ACTIVE_WRITE_RESOURCE);
@@ -53,9 +54,22 @@ resources.createGroup()
  * Retire (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3): a thread a live probe, the first of the frame's
  * lifetime passes, dispatched through `PROBE_DISPATCH_ACTIVE` over the list the frame before wrote.
  *
- * A probe is freed when its lattice point has left its cascade's window, or when nothing, pixel or hit,
- * has wanted it for longer than the retention time: its slot goes back on the free list, its state to
- * FREE, and its indirection entry, if it still names the slot, to none. The rest go on the frame's list.
+ * A probe is freed when its lattice point has left its cascade's window, or when the last frame's
+ * schedule asked for its slot: its slot goes back on the free list, its state to FREE, and its
+ * indirection entry, if it still names the slot, to none. The rest go on the frame's list.
+ *
+ * Eviction follows the pressure on the slots, not a time (Enshrouded's cache): schedule asks for as many
+ * slots as the free ones are short of the frame's wanted points and `PROBE_FREE_SLACK` of the capacity,
+ * least recently wanted first, so with room to spare a probe keeps its history however long nothing
+ * wants it. It asks by the probes' age buckets (`probe_clipmap_age_bucket` of the frames since the probe
+ * was last wanted), `PROBE_EVICTION_STRUCT`: the oldest buckets whole, and a number of the bucket below
+ * them, which the frame's threads take while `PROBE_COUNTER_EVICTED` is under it. A probe in use is
+ * never evicted: one a want waits on, NEW or wanted since its last update, and one wanted the last
+ * frame. Where those fill the slots, an admission starves and the capacity grows (§7.10).
+ *
+ * Every probe it keeps that it could have evicted is counted into its age's bucket, from
+ * `PROBE_COUNTER_AGES`, for the frame's schedule to choose the next eviction by; and every one it keeps
+ * that waits for an update into `PROBE_COUNTER_WAITING`, for the period.
  *
  * Running before want means a window's move needs no pass of its own: the storage cells it vacated
  * are emptied before any point it exposed can claim them.
@@ -77,18 +91,43 @@ fn main(
 
     var slot = 0u;
     var keep = false;
+    var waiting = false;
+    var evictable = false;
+    var bucket = 0u;
 
     if (index < min(probe_active_read.count, settings.capacity)) {
         slot = probe_active_read.elements[index];
 
         let cell = probe_records[slot].cell;
-        let cascade = probe_records[slot].cascade;
+        let cascade = probe_record_cascade(probe_records[slot].flags);
         let level = probe_levels[cascade];
+        let wanted_frame = probe_records[slot].wanted_frame;
 
         // the lattice's window is one point wider than the cages' on each axis
         let held = clipmap_contains(cell, level.corner, level.size + vec3<i32>(1));
 
-        keep = held && settings.time - probe_records[slot].wanted_time <= settings.retention_time;
+        waiting = probe_state_kind(probe_states[slot].x) == PROBE_STATE_NEW || wanted_frame > probe_records[slot].traced_frame;
+        // not wanted the frame before: wanted_frame < frame − 1, which does not wrap at the first frame
+        evictable = !waiting && wanted_frame + 1u < settings.frame;
+
+        let age = settings.frame - wanted_frame;
+
+        bucket = probe_clipmap_age_bucket(age);
+
+        // the bucket the last frame's schedule counted it in, a frame younger: a probe that aged into an asked
+        // bucket since, uncounted, is not taken for it
+        let counted = probe_clipmap_age_bucket(age - 1u);
+
+        // the oldest buckets whole, and as many of the one below them as are asked for; one that left its
+        // window goes anyway and takes none of those
+        let whole = PROBE_AGE_BUCKETS - min(probe_eviction.buckets, PROBE_AGE_BUCKETS);
+        var evicted = evictable && counted >= whole;
+
+        if (held && evictable && counted + 1u == whole && probe_eviction.remaining > 0u) {
+            evicted = atomicAdd(&probe_counters[PROBE_COUNTER_EVICTED], 1u) < probe_eviction.remaining;
+        }
+
+        keep = held && !evicted;
 
         if (!keep) {
             let resolution = settings.resolution;
@@ -103,8 +142,13 @@ fn main(
 
             slot_stack_push(&probe_counters[PROBE_COUNTER_FREE], &probe_free, slot);
         }
+
+        if (keep && evictable) {
+            atomicAdd(&probe_counters[PROBE_COUNTER_AGES + bucket], 1u);
+        }
     }
 
+    subgroup_atomic_add_u32(&probe_counters[PROBE_COUNTER_WAITING], select(0u, 1u, keep && waiting));
     collection_u32_append(&probe_active_write, keep, slot, settings.capacity);
 }
 `, [
@@ -114,5 +158,6 @@ fn main(
             chunk_clipmap_storage_coord,
             chunk_slot_stack,
             chunk_collection_u32_append,
+            chunk_subgroup_atomic_add,
         ]),
 });

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_schedule.d.ts

@@ -3,14 +3,29 @@
  */
 export const PROBE_SCHEDULE_SETTINGS: WebGPUStruct;
 /**
- * Schedule (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.5): one thread, after admit, when the frame's active
- * list is whole.
- * - The period: with P_w the points wanted this frame, `T = max(1, ⌈P_w / U⌉)` frames, so that every
- *   wanted probe is updated once a period and the period follows the live count. It goes to
+ * Schedule (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3, §8.5): one thread, after admit, when the frame's
+ * active list is whole.
+ * - The period: with P_w the probes waiting for an update, the NEW and those wanted since their last
+ *   update, `T = max(1, ⌈P_w / U⌉)` frames, so that every probe a want waits on is updated within a period
+ *   and the period follows the live count. Retire and admit counted them in
+ *   `probe_counters[PROBE_COUNTER_WAITING]`, which it empties for the next frame's; the period goes to
  *   `probe_counters[PROBE_COUNTER_PERIOD]` for the due passes.
+ * - The next frame's eviction, `probe_eviction`: as many slots as the free ones fall short of the frame's
+ *   wanted points and the slack, the probes wanted longest ago first. Walking retire's age buckets from the
+ *   oldest, it asks for each bucket whole while the shortfall takes it, then for what is left of the
+ *   shortfall from the next; past the youngest bucket it counted anything in, it asks for nothing, so a
+ *   shortfall the evictable probes cannot cover frees them all and no more. It empties the buckets and
+ *   the count of a bucket's probes retire evicted.
  * - A thread an entry of the frame's active list, at `PROBE_DISPATCH_ACTIVE`: the due passes' launch, and
  *   the next frame's retire's, which reads this list.
  *
+ * A hit wants a probe the frame after its probe's update, so a probe hits keep may be wanted on few of
+ * its turns. The waiting count is what due lists over a period, where this frame's wanted points would
+ * count the probes a pixel wants every frame and miss most of those hits want between their turns.
+ *
+ * The frame's wanted points are the most a frame can admit, so the next frame's admissions find slots
+ * for as many points as this one wanted, and the slack more, before an admission starves.
+ *
  * @type {ComputeShader}
  */
 export const shader_probe_clipmap_schedule: ComputeShader;

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_schedule.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_probe_clipmap_schedule.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_schedule.js"],"names":[],"mappings":"AAcA;;GAEG;AACH,sCAFU,YAAY,CASM;AAY5B;;;;;;;;;;GAUG;AACH,4CAFU,aAAa,CA0BpB;6BAlE0B,sCAAsC;8BAHrC,kCAAkC"}
+{"version":3,"file":"shader_probe_clipmap_schedule.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_schedule.js"],"names":[],"mappings":"AAeA;;GAEG;AACH,sCAFU,YAAY,CAWM;AAa5B;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,4CAFU,aAAa,CA6DpB;6BAxH0B,sCAAsC;8BAHrC,kCAAkC"}