@woosh/meep-engine 3.60.5 → 3.60.7

package/src/shade/renderer/global_illumination/probe_clipmap/ProbeClipmapSettings.d.ts

@@ -1,34 +1,3 @@
-/**
- * Cascades either clipmap may have at most.
- * @type {number}
- */
-export const PROBE_CLIPMAP_CASCADE_COUNT_MAX: number;
-/**
- * Cells per axis a cascade of either clipmap may have.
- * @type {ReadonlyArray<number>}
- */
-export const PROBE_CLIPMAP_CASCADE_RESOLUTIONS: ReadonlyArray<number>;
-/**
- * Bounds of the octahedral radiance and depth resolutions, texels per side.
- * @type {number}
- */
-export const PROBE_CLIPMAP_OCTAHEDRAL_RESOLUTION_MIN: number;
-/**
- * @type {number}
- */
-export const PROBE_CLIPMAP_OCTAHEDRAL_RESOLUTION_MAX: number;
-/**
- * The smallest {@link ProbeClipmapSettings#brick_build_budget}: one workgroup's worth of cells.
- * @type {number}
- */
-export const PROBE_CLIPMAP_BRICK_BUILD_BUDGET_MIN: number;
-/**
- * The most {@link ProbeClipmapSettings#mesh_sdf_max_bricks}: 64 bricks are 448 voxels a side, three and a
- * half times Unreal's cap, in seven levels. It bounds the levels a thread walks, and the bake's ring,
- * which holds twice the largest geometry's bricks, to 2^20 entries.
- * @type {number}
- */
-export const PROBE_CLIPMAP_MESH_SDF_MAX_BRICKS_LIMIT: number;
 /**
  * Settings of {@link ShadeIndirectLightingMode.ProbeClipmap}, held on `Renderer.probe_clipmap` and
  * read every frame the mode runs (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §10).
@@ -48,7 +17,8 @@ export const PROBE_CLIPMAP_MESH_SDF_MAX_BRICKS_LIMIT: number;
  */
 export class ProbeClipmapSettings {
     /**
-     * @param {number} v integer, 1 to {@link PROBE_CLIPMAP_CASCADE_COUNT_MAX}
+     * @param {number} v a positive integer; the brick clipmap checks it against what its layout and the
+     *        device hold when it is built
      */
     set brick_cascade_count(v: number);
     /**
@@ -58,7 +28,8 @@ export class ProbeClipmapSettings {
      */
     get brick_cascade_count(): number;
     /**
-     * @param {number} v one of {@link PROBE_CLIPMAP_CASCADE_RESOLUTIONS}
+     * @param {number} v a power of two, since a cascade's cells wrap by masking; the brick clipmap checks
+     *        the rest of what its layout and the device hold when it is built
      */
     set brick_cascade_resolution(v: number);
     /**
@@ -78,7 +49,7 @@ export class ProbeClipmapSettings {
      */
     get brick_voxel_size(): number;
     /**
-     * @param {number} v integer, at least {@link PROBE_CLIPMAP_BRICK_BUILD_BUDGET_MIN}
+     * @param {number} v a positive integer
      */
     set brick_build_budget(v: number);
     /**
@@ -99,8 +70,8 @@ export class ProbeClipmapSettings {
      */
     get mesh_sdf_voxel_size(): number;
     /**
-     * @param {number} v an even integer from 2, since a geometry's grid grows in steps of two bricks, to
-     *        {@link PROBE_CLIPMAP_MESH_SDF_MAX_BRICKS_LIMIT}
+     * @param {number} v an even integer from 2, since a geometry's grid grows in steps of two bricks; the
+     *        geometry SDF manager checks the bake's ring against the device when it sizes it
      */
     set mesh_sdf_max_bricks(v: number);
     /**
@@ -188,7 +159,8 @@ export class ProbeClipmapSettings {
      */
     get card_capture_mode(): number;
     /**
-     * @param {number} v integer, 1 to {@link PROBE_CLIPMAP_CASCADE_COUNT_MAX}
+     * @param {number} v a positive integer; the probe clipmap checks it against what its layout and the
+     *        device hold when it is built
      */
     set probe_cascade_count(v: number);
     /**
@@ -198,7 +170,8 @@ export class ProbeClipmapSettings {
      */
     get probe_cascade_count(): number;
     /**
-     * @param {number} v one of {@link PROBE_CLIPMAP_CASCADE_RESOLUTIONS}
+     * @param {number} v a power of two, since a cascade's points wrap by masking; the probe clipmap checks
+     *        the rest of what its layout holds when it is built
      */
     set probe_cascade_resolution(v: number);
     /**
@@ -218,8 +191,8 @@ export class ProbeClipmapSettings {
      */
     get probe_spacing(): number;
     /**
-     * @param {number} v a power of two, {@link PROBE_CLIPMAP_OCTAHEDRAL_RESOLUTION_MIN} to
-     * {@link PROBE_CLIPMAP_OCTAHEDRAL_RESOLUTION_MAX}
+     * @param {number} v a power of two from 2: an update's spread of rays walks the texels in bit-reversed
+     *        order, which needs more than one; the atlas checks a tile against the device
      */
     set radiance_resolution(v: number);
     /**
@@ -229,8 +202,7 @@ export class ProbeClipmapSettings {
      */
     get radiance_resolution(): number;
     /**
-     * @param {number} v a power of two, {@link PROBE_CLIPMAP_OCTAHEDRAL_RESOLUTION_MIN} to
-     * {@link PROBE_CLIPMAP_OCTAHEDRAL_RESOLUTION_MAX}
+     * @param {number} v a power of two; the atlas checks a tile against the device
      */
     set depth_resolution(v: number);
     /**
@@ -240,7 +212,8 @@ export class ProbeClipmapSettings {
      */
     get depth_resolution(): number;
     /**
-     * @param {number} v a power of two in `[radiance_resolution² / 4, 4·radiance_resolution²]`, checked
+     * @param {number} v a power of two, at most `PROBE_TEXEL_RAYS·radiance_resolution²` and
+     *        `PROBE_DEPTH_TEXEL_RAYS·depth_resolution²`, the rays one thread gathers into a texel, checked
      * against {@link radiance_resolution} when the GI takes the settings
      */
     set rays_per_probe(v: number);
@@ -251,41 +224,109 @@ export class ProbeClipmapSettings {
      */
     get rays_per_probe(): number;
     /**
-     * @param {number} v integer, at least {@link rays_per_probe}, checked when the GI takes the settings
+     * @param {number} v integer; each set's share is checked against its rays a probe when the GI takes the
+     *        settings
      */
     set ray_budget(v: number);
     /**
-     * Rays traced a frame at most, so `floor(ray_budget / rays_per_probe)` probes update a frame and
-     * every wanted probe is traced again after as many frames as that takes. Between Enshrouded's low and
-     * mid tiers (100k and 250k rays a frame). A time knob.
+     * Rays both probe sets trace a frame at most, between Enshrouded's low and mid tiers (100k and 250k): the
+     * frustum's {@link frustum_ray_budget} and the world cache's {@link world_ray_budget}. A time knob.
      * @returns {number}
      */
     get ray_budget(): number;
+    /**
+     * Rays the frustum's probes trace a frame at most, `FRUSTUM_RAY_BUDGET_FRACTION` of {@link ray_budget}
+     * rounded down, so `floor(frustum_ray_budget / rays_per_probe)` of them update a frame and every wanted one
+     * is traced again after as many frames as that takes.
+     * @returns {number}
+     */
+    get frustum_ray_budget(): number;
+    /**
+     * Rays the world cache's probes trace a frame at most: the rest of {@link ray_budget}.
+     * @returns {number}
+     */
+    get world_ray_budget(): number;
+    /**
+     * @param {number} v a positive integer; the world cache checks its lattice against what its layout and the
+     *        device hold when it is built
+     */
+    set world_cache_spacing_shift(v: number);
+    /**
+     * The world cache's probes against the frustum's (WORLD_PROBE_CACHE_SCOPE_2026_11_01.md §1.2): k, its
+     * spacing the frustum's over 2^k and its lattice 2^k the frustum's {@link probe_cascade_resolution}, in the
+     * frustum's windows, so every frustum probe's point is one of the world cache's. 2, a quarter of the
+     * spacing, Enshrouded's denser world cache. Structure.
+     * @returns {number}
+     */
+    get world_cache_spacing_shift(): number;
+    /**
+     * @param {number} v a power of two from 2, as {@link radiance_resolution}
+     */
+    set world_cache_radiance_resolution(v: number);
+    /**
+     * Octahedral radiance texels per side of a world cache probe: Enshrouded's 4. Its radiance is only made
+     * into its SH, never sampled, so its tiles have no skirt. Structure.
+     * @returns {number}
+     */
+    get world_cache_radiance_resolution(): number;
+    /**
+     * @param {number} v a power of two
+     */
+    set world_cache_depth_resolution(v: number);
+    /**
+     * Octahedral depth-moment texels per side of a world cache probe, which a hit's pick weighs it by.
+     * Structure.
+     * @returns {number}
+     */
+    get world_cache_depth_resolution(): number;
+    /**
+     * @param {number} v a power of two, held as {@link rays_per_probe} is against the world cache's
+     *        resolutions when the GI takes the settings
+     */
+    set world_cache_rays_per_probe(v: number);
+    /**
+     * Rays a world cache probe traces each uniform update: one a texel at the default
+     * {@link world_cache_radiance_resolution}, as {@link rays_per_probe} is for the frustum's.
+     * @returns {number}
+     */
+    get world_cache_rays_per_probe(): number;
     /**
      * @param {number} v frames, positive and finite
      */
     set response_frames(v: number);
     /**
-     * Frames of the short mean a probe's radiance follows a change by, in its multi-scale mean: an update
-     * blends the short mean by `1 − e^(−Δt / response_frames)`, Δt the frames since the probe's last update,
-     * and the mean catches up with it once the two disagree past the texel's noise. The depth's moments
-     * blend by the same. Frames, not seconds: an update happens in a frame, and the records count them.
-     * 30 is half a second at 60 fps; DDGI's hysteresis of 0.97 a frame is 33.
+     * Frames over which a neighbour's history goes stale to an update that re-samples it
+     * (`history_resampling`): a neighbour last updated Δt frames ago weighs `e^(−Δt / response_frames)`.
+     * A probe's own history blends a sample by a sample's blend however long since its last update, the
+     * time between them being no change in the light. Frames, not seconds: an update happens in a frame, and
+     * the records count them. 30 is half a second at 60 fps.
      * @returns {number}
      */
     get response_frames(): number;
     /**
      * @param {boolean} v
      */
-    set resampling(v: boolean);
+    set history_resampling(v: boolean);
     /**
-     * Whether each probe update also re-samples its neighbours: every radiance texel takes what four of the
-     * probe's 26 neighbours in its cascade have already seen of the point it sees, where their depth says
-     * they can see it, each a ray's worth beside its own rays. It traces nothing, and buys convergence for
+     * Whether each probe update also re-samples its neighbours' histories: every radiance texel takes what four of
+     * the probe's 26 neighbours in its cascade have already seen of the point it sees, where their depth says
+     * they can see it, each a ray's worth beside its own rays. It traces nothing, and buys stability for
      * some spatial blur. Off, the update's pass is not recorded. Takes effect the next frame.
      * @returns {boolean}
      */
-    get resampling(): boolean;
+    get history_resampling(): boolean;
+    /**
+     * @param {boolean} v
+     */
+    set ray_resampling(v: boolean);
+    /**
+     * Whether each probe update also re-samples one neighbour's rays of the same frame: it draws a neighbour
+     * updated this frame by its radiance and how well the probe sees it, and takes every one of its rays whose hit,
+     * or sky, the probe's depth confirms, in the texel the probe sees it in. It traces nothing, and brings in light
+     * the neighbour's rays found this frame. Off, the update's passes are not recorded. Takes effect the next frame.
+     * @returns {boolean}
+     */
+    get ray_resampling(): boolean;
     /**
      * @param {ProbeClipmapDebugView} v
      */

package/src/shade/renderer/global_illumination/probe_clipmap/ProbeClipmapSettings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ProbeClipmapSettings.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/probe_clipmap/ProbeClipmapSettings.js"],"names":[],"mappings":"AAOA;;;GAGG;AACH,8CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,gDAFU,cAAc,MAAM,CAAC,CAE8C;AAE7E;;;GAGG;AACH,sDAFU,MAAM,CAEyC;AAEzD;;GAEG;AACH,sDAFU,MAAM,CAE0C;AAE1D;;;GAGG;AACH,mDAFU,MAAM,CAEuC;AAEvD;;;;;GAKG;AACH,sDAFU,MAAM,CAE0C;AAE1D;;;;;;;;;;;;;;;;GAgBG;AACH;IAaI;;OAEG;IACH,mCAKC;IAjBD;;;;OAIG;IACH,kCAEC;IAsBD;;OAEG;IACH,wCAIC;IAfD;;;OAGG;IACH,uCAEC;IAuBD;;OAEG;IACH,gCAKC;IAlBD;;;;;OAKG;IACH,+BAEC;IAuBD;;OAEG;IACH,kCAKC;IAjBD;;;;OAIG;IACH,iCAEC;IAwBD;;OAEG;IACH,mCAKC;IAlBD;;;;;OAKG;IACH,kCAEC;IAyBD;;;OAGG;IACH,mCAOC;IAtBD;;;;;;OAMG;IACH,kCAEC;IAqCD;;;OAGG;IACH,oCAKC;IA7BD;;;;;;;;;;;;;;;OAeG;IACH,mCAEC;IA6CD;;;OAGG;IACH,mCAKC;IAvCD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,kCAEC;IAoCD;;OAEG;IACH,iCAIC;IA5BD;;;;;;;;;;;;;;;;OAgBG;IACH,gCAEC;IAsBD;;OAEG;IACH,mCAKC;IAjBD;;;;OAIG;IACH,kCAEC;IAsBD;;OAEG;IACH,wCAIC;IAfD;;;OAGG;IACH,uCAEC;IAuBD;;OAEG;IACH,6BAKC;IAlBD;;;;;OAKG;IACH,4BAEC;IAuBD;;;OAGG;IACH,mCAOC;IApBD;;;;OAIG;IACH,kCAEC;IA0BD;;;OAGG;IACH,gCAOC;IApBD;;;;OAIG;IACH,+BAEC;IA0BD;;;OAGG;IACH,8BAKC;IAlBD;;;;OAIG;IACH,6BAEC;IAyBD;;OAEG;IACH,0BAIC;IAjBD;;;;;OAKG;IACH,yBAEC;IAyBD;;OAEG;IACH,+BAKC;IApBD;;;;;;;OAOG;IACH,8BAEC;IAyBD;;OAEG;IACH,2BAIC;IAlBD;;;;;;OAMG;IACH,0BAEC;IAsBD;;OAEG;IACH,0BAIC;IAhBD;;;;OAIG;IACH,yBAEC;;CAUJ"}
+{"version":3,"file":"ProbeClipmapSettings.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/probe_clipmap/ProbeClipmapSettings.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;GAgBG;AACH;IAaI;;;OAGG;IACH,mCAIC;IAjBD;;;;OAIG;IACH,kCAEC;IAsBD;;;OAGG;IACH,wCAKC;IAjBD;;;OAGG;IACH,uCAEC;IAyBD;;OAEG;IACH,gCAKC;IAlBD;;;;;OAKG;IACH,+BAEC;IAuBD;;OAEG;IACH,kCAIC;IAhBD;;;;OAIG;IACH,iCAEC;IAuBD;;OAEG;IACH,mCAKC;IAlBD;;;;;OAKG;IACH,kCAEC;IAyBD;;;OAGG;IACH,mCAMC;IArBD;;;;;;OAMG;IACH,kCAEC;IAoCD;;;OAGG;IACH,oCAKC;IA7BD;;;;;;;;;;;;;;;OAeG;IACH,mCAEC;IA6CD;;;OAGG;IACH,mCAKC;IAvCD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,kCAEC;IAoCD;;OAEG;IACH,iCAIC;IA5BD;;;;;;;;;;;;;;;;OAgBG;IACH,gCAEC;IAsBD;;;OAGG;IACH,mCAIC;IAjBD;;;;OAIG;IACH,kCAEC;IAsBD;;;OAGG;IACH,wCAKC;IAjBD;;;OAGG;IACH,uCAEC;IAyBD;;OAEG;IACH,6BAKC;IAlBD;;;;;OAKG;IACH,4BAEC;IAuBD;;;OAGG;IACH,mCAMC;IAnBD;;;;OAIG;IACH,kCAEC;IAyBD;;OAEG;IACH,gCAKC;IAjBD;;;;OAIG;IACH,+BAEC;IAuBD;;;;OAIG;IACH,8BAKC;IAnBD;;;;OAIG;IACH,6BAEC;IAyBD;;;OAGG;IACH,0BAIC;IAjBD;;;;OAIG;IACH,yBAEC;IAYD;;;;;OAKG;IACH,iCAEC;IAED;;;OAGG;IACH,+BAEC;IAeD;;;OAGG;IACH,yCAIC;IAnBD;;;;;;OAMG;IACH,wCAEC;IAuBD;;OAEG;IACH,+CAMC;IAlBD;;;;OAIG;IACH,8CAEC;IAwBD;;OAEG;IACH,4CAKC;IAjBD;;;;OAIG;IACH,2CAEC;IAuBD;;;OAGG;IACH,0CAKC;IAlBD;;;;OAIG;IACH,yCAEC;IA2BD;;OAEG;IACH,+BAKC;IApBD;;;;;;;OAOG;IACH,8BAEC;IAyBD;;OAEG;IACH,mCAIC;IAlBD;;;;;;OAMG;IACH,kCAEC;IAwBD;;OAEG;IACH,+BAIC;IAlBD;;;;;;OAMG;IACH,8BAEC;IAsBD;;OAEG;IACH,0BAIC;IAhBD;;;;OAIG;IACH,yBAEC;;CAUJ"}

package/src/shade/renderer/global_illumination/probe_clipmap/ProbeClipmapSettings.js

@@ -4,43 +4,7 @@ import { MESH_CARD_CAPTURE_BUDGET_MAX } from "../../geometry/sdf/cards/GPUMeshCa
 import { MeshCardCaptureMode } from "../../geometry/sdf/cards/MeshCardCaptureMode.js";
 import { MESH_SDF_BAKE_BUDGET_MAX } from "../../geometry/sdf/GPUGeometrySDFManager.js";
 import { ProbeClipmapDebugView } from "./debug/ProbeClipmapDebugView.js";
-
-/**
- * Cascades either clipmap may have at most.
- * @type {number}
- */
-export const PROBE_CLIPMAP_CASCADE_COUNT_MAX = 8;
-
-/**
- * Cells per axis a cascade of either clipmap may have.
- * @type {ReadonlyArray<number>}
- */
-export const PROBE_CLIPMAP_CASCADE_RESOLUTIONS = Object.freeze([16, 32, 64]);
-
-/**
- * Bounds of the octahedral radiance and depth resolutions, texels per side.
- * @type {number}
- */
-export const PROBE_CLIPMAP_OCTAHEDRAL_RESOLUTION_MIN = 4;
-
-/**
- * @type {number}
- */
-export const PROBE_CLIPMAP_OCTAHEDRAL_RESOLUTION_MAX = 32;
-
-/**
- * The smallest {@link ProbeClipmapSettings#brick_build_budget}: one workgroup's worth of cells.
- * @type {number}
- */
-export const PROBE_CLIPMAP_BRICK_BUILD_BUDGET_MIN = 64;
-
-/**
- * The most {@link ProbeClipmapSettings#mesh_sdf_max_bricks}: 64 bricks are 448 voxels a side, three and a
- * half times Unreal's cap, in seven levels. It bounds the levels a thread walks, and the bake's ring,
- * which holds twice the largest geometry's bricks, to 2^20 entries.
- * @type {number}
- */
-export const PROBE_CLIPMAP_MESH_SDF_MAX_BRICKS_LIMIT = 64;
+import { FRUSTUM_RAY_BUDGET_FRACTION } from "./probe/PROBE_CLIPMAP.js";
 
 /**
  * Settings of {@link ShadeIndirectLightingMode.ProbeClipmap}, held on `Renderer.probe_clipmap` and
@@ -73,11 +37,11 @@ export class ProbeClipmapSettings {
     }
 
     /**
-     * @param {number} v integer, 1 to {@link PROBE_CLIPMAP_CASCADE_COUNT_MAX}
+     * @param {number} v a positive integer; the brick clipmap checks it against what its layout and the
+     *        device hold when it is built
      */
     set brick_cascade_count(v) {
         assert.isPositiveInteger(v, 'brick_cascade_count');
-        assert.lessThanOrEqual(v, PROBE_CLIPMAP_CASCADE_COUNT_MAX, 'brick_cascade_count');
 
         this.#brick_cascade_count = v;
     }
@@ -93,10 +57,12 @@ export class ProbeClipmapSettings {
     }
 
     /**
-     * @param {number} v one of {@link PROBE_CLIPMAP_CASCADE_RESOLUTIONS}
+     * @param {number} v a power of two, since a cascade's cells wrap by masking; the brick clipmap checks
+     *        the rest of what its layout and the device hold when it is built
      */
     set brick_cascade_resolution(v) {
-        assert.isOneOf(v, PROBE_CLIPMAP_CASCADE_RESOLUTIONS, 'brick_cascade_resolution');
+        assert.isPositiveInteger(v, 'brick_cascade_resolution');
+        assert.ok(isPowerOfTwo(v), 'brick_cascade_resolution must be a power of two');
 
         this.#brick_cascade_resolution = v;
     }
@@ -135,11 +101,10 @@ export class ProbeClipmapSettings {
     }
 
     /**
-     * @param {number} v integer, at least {@link PROBE_CLIPMAP_BRICK_BUILD_BUDGET_MIN}
+     * @param {number} v a positive integer
      */
     set brick_build_budget(v) {
         assert.isPositiveInteger(v, 'brick_build_budget');
-        assert.greaterThanOrEqual(v, PROBE_CLIPMAP_BRICK_BUILD_BUDGET_MIN, 'brick_build_budget');
 
         this.#brick_build_budget = v;
     }
@@ -180,13 +145,12 @@ export class ProbeClipmapSettings {
     }
 
     /**
-     * @param {number} v an even integer from 2, since a geometry's grid grows in steps of two bricks, to
-     *        {@link PROBE_CLIPMAP_MESH_SDF_MAX_BRICKS_LIMIT}
+     * @param {number} v an even integer from 2, since a geometry's grid grows in steps of two bricks; the
+     *        geometry SDF manager checks the bake's ring against the device when it sizes it
      */
     set mesh_sdf_max_bricks(v) {
         assert.isPositiveInteger(v, 'mesh_sdf_max_bricks');
         assert.greaterThanOrEqual(v, 2, 'mesh_sdf_max_bricks');
-        assert.lessThanOrEqual(v, PROBE_CLIPMAP_MESH_SDF_MAX_BRICKS_LIMIT, 'mesh_sdf_max_bricks');
         assert.equal(v % 2, 0, 'mesh_sdf_max_bricks must be even');
 
         this.#mesh_sdf_max_bricks = v;
@@ -312,11 +276,11 @@ export class ProbeClipmapSettings {
     }
 
     /**
-     * @param {number} v integer, 1 to {@link PROBE_CLIPMAP_CASCADE_COUNT_MAX}
+     * @param {number} v a positive integer; the probe clipmap checks it against what its layout and the
+     *        device hold when it is built
      */
     set probe_cascade_count(v) {
         assert.isPositiveInteger(v, 'probe_cascade_count');
-        assert.lessThanOrEqual(v, PROBE_CLIPMAP_CASCADE_COUNT_MAX, 'probe_cascade_count');
 
         this.#probe_cascade_count = v;
     }
@@ -332,10 +296,12 @@ export class ProbeClipmapSettings {
     }
 
     /**
-     * @param {number} v one of {@link PROBE_CLIPMAP_CASCADE_RESOLUTIONS}
+     * @param {number} v a power of two, since a cascade's points wrap by masking; the probe clipmap checks
+     *        the rest of what its layout holds when it is built
      */
     set probe_cascade_resolution(v) {
-        assert.isOneOf(v, PROBE_CLIPMAP_CASCADE_RESOLUTIONS, 'probe_cascade_resolution');
+        assert.isPositiveInteger(v, 'probe_cascade_resolution');
+        assert.ok(isPowerOfTwo(v), 'probe_cascade_resolution must be a power of two');
 
         this.#probe_cascade_resolution = v;
     }
@@ -374,14 +340,13 @@ export class ProbeClipmapSettings {
     }
 
     /**
-     * @param {number} v a power of two, {@link PROBE_CLIPMAP_OCTAHEDRAL_RESOLUTION_MIN} to
-     * {@link PROBE_CLIPMAP_OCTAHEDRAL_RESOLUTION_MAX}
+     * @param {number} v a power of two from 2: an update's spread of rays walks the texels in bit-reversed
+     *        order, which needs more than one; the atlas checks a tile against the device
      */
     set radiance_resolution(v) {
         assert.isPositiveInteger(v, 'radiance_resolution');
         assert.ok(isPowerOfTwo(v), 'radiance_resolution must be a power of two');
-        assert.greaterThanOrEqual(v, PROBE_CLIPMAP_OCTAHEDRAL_RESOLUTION_MIN, 'radiance_resolution');
-        assert.lessThanOrEqual(v, PROBE_CLIPMAP_OCTAHEDRAL_RESOLUTION_MAX, 'radiance_resolution');
+        assert.greaterThanOrEqual(v, 2, 'radiance_resolution');
 
         this.#radiance_resolution = v;
     }
@@ -398,14 +363,11 @@ export class ProbeClipmapSettings {
     }
 
     /**
-     * @param {number} v a power of two, {@link PROBE_CLIPMAP_OCTAHEDRAL_RESOLUTION_MIN} to
-     * {@link PROBE_CLIPMAP_OCTAHEDRAL_RESOLUTION_MAX}
+     * @param {number} v a power of two; the atlas checks a tile against the device
      */
     set depth_resolution(v) {
         assert.isPositiveInteger(v, 'depth_resolution');
         assert.ok(isPowerOfTwo(v), 'depth_resolution must be a power of two');
-        assert.greaterThanOrEqual(v, PROBE_CLIPMAP_OCTAHEDRAL_RESOLUTION_MIN, 'depth_resolution');
-        assert.lessThanOrEqual(v, PROBE_CLIPMAP_OCTAHEDRAL_RESOLUTION_MAX, 'depth_resolution');
 
         this.#depth_resolution = v;
     }
@@ -422,7 +384,8 @@ export class ProbeClipmapSettings {
     }
 
     /**
-     * @param {number} v a power of two in `[radiance_resolution² / 4, 4·radiance_resolution²]`, checked
+     * @param {number} v a power of two, at most `PROBE_TEXEL_RAYS·radiance_resolution²` and
+     *        `PROBE_DEPTH_TEXEL_RAYS·depth_resolution²`, the rays one thread gathers into a texel, checked
      * against {@link radiance_resolution} when the GI takes the settings
      */
     set rays_per_probe(v) {
@@ -435,9 +398,8 @@ export class ProbeClipmapSettings {
     #ray_budget = 131072;
 
     /**
-     * Rays traced a frame at most, so `floor(ray_budget / rays_per_probe)` probes update a frame and
-     * every wanted probe is traced again after as many frames as that takes. Between Enshrouded's low and
-     * mid tiers (100k and 250k rays a frame). A time knob.
+     * Rays both probe sets trace a frame at most, between Enshrouded's low and mid tiers (100k and 250k): the
+     * frustum's {@link frustum_ray_budget} and the world cache's {@link world_ray_budget}. A time knob.
      * @returns {number}
      */
     get ray_budget() {
@@ -445,7 +407,8 @@ export class ProbeClipmapSettings {
     }
 
     /**
-     * @param {number} v integer, at least {@link rays_per_probe}, checked when the GI takes the settings
+     * @param {number} v integer; each set's share is checked against its rays a probe when the GI takes the
+     *        settings
      */
     set ray_budget(v) {
         assert.isPositiveInteger(v, 'ray_budget');
@@ -453,14 +416,120 @@ export class ProbeClipmapSettings {
         this.#ray_budget = v;
     }
 
+    /**
+     * Rays the frustum's probes trace a frame at most, `FRUSTUM_RAY_BUDGET_FRACTION` of {@link ray_budget}
+     * rounded down, so `floor(frustum_ray_budget / rays_per_probe)` of them update a frame and every wanted one
+     * is traced again after as many frames as that takes.
+     * @returns {number}
+     */
+    get frustum_ray_budget() {
+        return Math.floor(this.#ray_budget * FRUSTUM_RAY_BUDGET_FRACTION);
+    }
+
+    /**
+     * Rays the world cache's probes trace a frame at most: the rest of {@link ray_budget}.
+     * @returns {number}
+     */
+    get world_ray_budget() {
+        return this.#ray_budget - this.frustum_ray_budget;
+    }
+
+    #world_cache_spacing_shift = 2;
+
+    /**
+     * The world cache's probes against the frustum's (WORLD_PROBE_CACHE_SCOPE_2026_11_01.md §1.2): k, its
+     * spacing the frustum's over 2^k and its lattice 2^k the frustum's {@link probe_cascade_resolution}, in the
+     * frustum's windows, so every frustum probe's point is one of the world cache's. 2, a quarter of the
+     * spacing, Enshrouded's denser world cache. Structure.
+     * @returns {number}
+     */
+    get world_cache_spacing_shift() {
+        return this.#world_cache_spacing_shift;
+    }
+
+    /**
+     * @param {number} v a positive integer; the world cache checks its lattice against what its layout and the
+     *        device hold when it is built
+     */
+    set world_cache_spacing_shift(v) {
+        assert.isPositiveInteger(v, 'world_cache_spacing_shift');
+
+        this.#world_cache_spacing_shift = v;
+    }
+
+    #world_cache_radiance_resolution = 4;
+
+    /**
+     * Octahedral radiance texels per side of a world cache probe: Enshrouded's 4. Its radiance is only made
+     * into its SH, never sampled, so its tiles have no skirt. Structure.
+     * @returns {number}
+     */
+    get world_cache_radiance_resolution() {
+        return this.#world_cache_radiance_resolution;
+    }
+
+    /**
+     * @param {number} v a power of two from 2, as {@link radiance_resolution}
+     */
+    set world_cache_radiance_resolution(v) {
+        assert.isPositiveInteger(v, 'world_cache_radiance_resolution');
+        assert.ok(isPowerOfTwo(v), 'world_cache_radiance_resolution must be a power of two');
+        assert.greaterThanOrEqual(v, 2, 'world_cache_radiance_resolution');
+
+        this.#world_cache_radiance_resolution = v;
+    }
+
+    #world_cache_depth_resolution = 4;
+
+    /**
+     * Octahedral depth-moment texels per side of a world cache probe, which a hit's pick weighs it by.
+     * Structure.
+     * @returns {number}
+     */
+    get world_cache_depth_resolution() {
+        return this.#world_cache_depth_resolution;
+    }
+
+    /**
+     * @param {number} v a power of two
+     */
+    set world_cache_depth_resolution(v) {
+        assert.isPositiveInteger(v, 'world_cache_depth_resolution');
+        assert.ok(isPowerOfTwo(v), 'world_cache_depth_resolution must be a power of two');
+
+        this.#world_cache_depth_resolution = v;
+    }
+
+    #world_cache_rays_per_probe = 16;
+
+    /**
+     * Rays a world cache probe traces each uniform update: one a texel at the default
+     * {@link world_cache_radiance_resolution}, as {@link rays_per_probe} is for the frustum's.
+     * @returns {number}
+     */
+    get world_cache_rays_per_probe() {
+        return this.#world_cache_rays_per_probe;
+    }
+
+    /**
+     * @param {number} v a power of two, held as {@link rays_per_probe} is against the world cache's
+     *        resolutions when the GI takes the settings
+     */
+    set world_cache_rays_per_probe(v) {
+        assert.isPositiveInteger(v, 'world_cache_rays_per_probe');
+        assert.ok(isPowerOfTwo(v), 'world_cache_rays_per_probe must be a power of two');
+
+        this.#world_cache_rays_per_probe = v;
+    }
+
     #response_frames = 30;
 
     /**
-     * Frames of the short mean a probe's radiance follows a change by, in its multi-scale mean: an update
-     * blends the short mean by `1 − e^(−Δt / response_frames)`, Δt the frames since the probe's last update,
-     * and the mean catches up with it once the two disagree past the texel's noise. The depth's moments
-     * blend by the same. Frames, not seconds: an update happens in a frame, and the records count them.
-     * 30 is half a second at 60 fps; DDGI's hysteresis of 0.97 a frame is 33.
+     * Frames over which a neighbour's history goes stale to an update that re-samples it
+     * (`history_resampling`): a neighbour last updated Δt frames ago weighs `e^(−Δt / response_frames)`.
+     * A probe's own history blends a sample by a sample's blend however long since its last update, the
+     * time between them being no change in the light. Frames, not seconds: an update happens in a frame, and
+     * the records count them. 30 is half a second at 60 fps.
      * @returns {number}
      */
     get response_frames() {
@@ -477,26 +546,48 @@ export class ProbeClipmapSettings {
         this.#response_frames = v;
     }
 
-    #resampling = false;
+    #history_resampling = false;
 
     /**
-     * Whether each probe update also re-samples its neighbours: every radiance texel takes what four of the
-     * probe's 26 neighbours in its cascade have already seen of the point it sees, where their depth says
-     * they can see it, each a ray's worth beside its own rays. It traces nothing, and buys convergence for
+     * Whether each probe update also re-samples its neighbours' histories: every radiance texel takes what four of
+     * the probe's 26 neighbours in its cascade have already seen of the point it sees, where their depth says
+     * they can see it, each a ray's worth beside its own rays. It traces nothing, and buys stability for
      * some spatial blur. Off, the update's pass is not recorded. Takes effect the next frame.
      * @returns {boolean}
      */
-    get resampling() {
-        return this.#resampling;
+    get history_resampling() {
+        return this.#history_resampling;
+    }
+
+    /**
+     * @param {boolean} v
+     */
+    set history_resampling(v) {
+        assert.isBoolean(v, 'history_resampling');
+
+        this.#history_resampling = v;
+    }
+
+    #ray_resampling = false;
+
+    /**
+     * Whether each probe update also re-samples one neighbour's rays of the same frame: it draws a neighbour
+     * updated this frame by its radiance and how well the probe sees it, and takes every one of its rays whose hit,
+     * or sky, the probe's depth confirms, in the texel the probe sees it in. It traces nothing, and brings in light
+     * the neighbour's rays found this frame. Off, the update's passes are not recorded. Takes effect the next frame.
+     * @returns {boolean}
+     */
+    get ray_resampling() {
+        return this.#ray_resampling;
     }
 
     /**
      * @param {boolean} v
      */
-    set resampling(v) {
-        assert.isBoolean(v, 'resampling');
+    set ray_resampling(v) {
+        assert.isBoolean(v, 'ray_resampling');
 
-        this.#resampling = v;
+        this.#ray_resampling = v;
     }
 
     #debug_view = ProbeClipmapDebugView.None;

package/src/shade/renderer/global_illumination/probe_clipmap/brick/GPUBrickClipmap.d.ts

@@ -55,8 +55,10 @@ export class GPUBrickClipmap {
     /**
      * @param {GPUDevice} device
      * @param {object} options
-     * @param {number} options.cascade_count
-     * @param {number} options.resolution one of {@link PROBE_CLIPMAP_CASCADE_RESOLUTIONS}
+     * @param {number} options.cascade_count at most the levels table holds, {@link CLIPMAP_LEVEL_LIMIT}
+     * @param {number} options.resolution a power of two, at least an occupancy block,
+     *        {@link BRICK_OCCUPANCY_BLOCK}; the brick map's height, resolution · cascade_count, at most the
+     *        device's `maxTextureDimension3D`
      * @param {number} options.voxel_size metres
      */
     constructor(device: GPUDevice, { cascade_count, resolution, voxel_size }: {

package/src/shade/renderer/global_illumination/probe_clipmap/brick/GPUBrickClipmap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUBrickClipmap.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/GPUBrickClipmap.js"],"names":[],"mappings":"AAiFA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IA2JI;;;;;;OAMG;IACH;QAJ2B,aAAa,EAA7B,MAAM;QACU,UAAU,EAA1B,MAAM;QACU,UAAU,EAA1B,MAAM;OA8FhB;IA7PD;;;OAGG;IACH,wBAHU,MAAM,CAGF;IAEd;;;;OAIG;IACH,qBAHU,MAAM,CAGL;IAEX;;;;OAIG;IACH,qBAHU,MAAM,CAGL;IA6OX;;OAEG;IACH,4BAEC;IAED;;OAEG;IACH,4BAEC;IAED;;OAEG;IACH,4BAEC;IAED;;OAEG;IACH,yBAEC;IAED;;;;OAIG;IACH,wBAEC;IAED;;;;;;;;OAQG;IACH,mCASC;IAED;;;OAGG;IACH,uBAEC;IAED;;;;OAIG;IACH,gBAJW,MAAM,QACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,sBAFW,UAAU,MAAM,CAAC,QAiB3B;IAED;;;OAGG;IACH,oBAHW,oBAAoB,GAClB,OAAO,CAMnB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH;QAZ+B,KAAK,EAAzB,UAAU;QACM,CAAC,EAAjB,MAAM;QACU,CAAC,EAAjB,MAAM;QACU,CAAC,EAAjB,MAAM;QACU,MAAM,EAAtB,MAAM;QAC4B,SAAS,EAA3C,UAAU,aAAa,CAAC;QACM,KAAK,EAAnC,eAAe,GAAC,IAAI;QACH,MAAM,GAAvB,MAAM;QAEJ,MAAM,CAoGlB;IAgWD,gBAcC;;CACJ;mCAl7BY,OAAO,4BAA4B,EAAE,oBAAoB;yBACzD,OAAO,iEAAiE,EAAE,UAAU;8BACpF,OAAO,mCAAmC,EAAE,eAAe;;;;;;;WAyC1D,UAAU;;;;WACV,MAAM;;;;;;UACN,MAAM;;;;;aAGN,MAAM;;;;sBAEN,MAAM;;;;;mBAEN,MAAM;;;;gBACN,MAAM;mBACN,MAAM;;;;;;;;;;WAGN,eAAe;;;+BAMN,UAAU,QAAE,oBAAoB,KAAG,IAAI;;+BA1F/B,0CAA0C"}
+{"version":3,"file":"GPUBrickClipmap.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/GPUBrickClipmap.js"],"names":[],"mappings":"AAwFA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IA2JI;;;;;;;;OAQG;IACH;QAN2B,aAAa,EAA7B,MAAM;QACU,UAAU,EAA1B,MAAM;QAGU,UAAU,EAA1B,MAAM;OAiGhB;IAlQD;;;OAGG;IACH,wBAHU,MAAM,CAGF;IAEd;;;;OAIG;IACH,qBAHU,MAAM,CAGL;IAEX;;;;OAIG;IACH,qBAHU,MAAM,CAGL;IAkPX;;OAEG;IACH,4BAEC;IAED;;OAEG;IACH,4BAEC;IAED;;OAEG;IACH,4BAEC;IAED;;OAEG;IACH,yBAEC;IAED;;;;OAIG;IACH,wBAEC;IAED;;;;;;;;OAQG;IACH,mCASC;IAED;;;OAGG;IACH,uBAEC;IAED;;;;OAIG;IACH,gBAJW,MAAM,QACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,sBAFW,UAAU,MAAM,CAAC,QAiB3B;IAED;;;OAGG;IACH,oBAHW,oBAAoB,GAClB,OAAO,CAMnB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH;QAZ+B,KAAK,EAAzB,UAAU;QACM,CAAC,EAAjB,MAAM;QACU,CAAC,EAAjB,MAAM;QACU,CAAC,EAAjB,MAAM;QACU,MAAM,EAAtB,MAAM;QAC4B,SAAS,EAA3C,UAAU,aAAa,CAAC;QACM,KAAK,EAAnC,eAAe,GAAC,IAAI;QACH,MAAM,GAAvB,MAAM;QAEJ,MAAM,CAoGlB;IAmWD,gBAcC;;CACJ;mCA17BY,OAAO,4BAA4B,EAAE,oBAAoB;yBACzD,OAAO,iEAAiE,EAAE,UAAU;8BACpF,OAAO,mCAAmC,EAAE,eAAe;;;;;;;WAyC1D,UAAU;;;;WACV,MAAM;;;;;;UACN,MAAM;;;;;aAGN,MAAM;;;;sBAEN,MAAM;;;;;mBAEN,MAAM;;;;gBACN,MAAM;mBACN,MAAM;;;;;;;;;;WAGN,eAAe;;;+BAMN,UAAU,QAAE,oBAAoB,KAAG,IAAI;;+BAxF/B,0CAA0C"}