@woosh/meep-engine 3.20.0 → 3.22.0

package/src/shade/renderer/particles/runtime/ParticleEmitter.d.ts

@@ -198,11 +198,11 @@ export class ParticleEmitter extends Node3D {
      * Bind render channels to per-particle attributes of this emitter's effect, by attribute name.
      * Channels left out of `channels` keep whatever they had; a channel that was never bound stays
      * at {@link EMITTER_ATTRIBUTE_ABSENT}, which the passes read as "this emitter has no such
-     * attribute" — the render pass substitutes a default, the sort pass treats the particle as
-     * being at the origin.
+     * attribute" — the passes that draw substitute a default, and the bounds pass treats the
+     * particle as being at the origin.
      *
-     * The record stores word offsets rather than names because that is what the render and sort
-     * passes index a particle record with; resolving here is the only place a name is involved.
+     * The record stores word offsets rather than names because that is what those passes index a
+     * particle record with; resolving here is the only place a name is involved.
      *
      * @param {Object<string,string>} channels channel name (see {@link EMITTER_RENDER_CHANNELS}) ->
      *        attribute name in the effect's layout

package/src/shade/renderer/particles/runtime/ParticleEmitter.js

@@ -192,11 +192,11 @@ export class ParticleEmitter extends Node3D {
      * Bind render channels to per-particle attributes of this emitter's effect, by attribute name.
      * Channels left out of `channels` keep whatever they had; a channel that was never bound stays
      * at {@link EMITTER_ATTRIBUTE_ABSENT}, which the passes read as "this emitter has no such
-     * attribute" — the render pass substitutes a default, the sort pass treats the particle as
-     * being at the origin.
+     * attribute" — the passes that draw substitute a default, and the bounds pass treats the
+     * particle as being at the origin.
      *
-     * The record stores word offsets rather than names because that is what the render and sort
-     * passes index a particle record with; resolving here is the only place a name is involved.
+     * The record stores word offsets rather than names because that is what those passes index a
+     * particle record with; resolving here is the only place a name is involved.
      *
      * @param {Object<string,string>} channels channel name (see {@link EMITTER_RENDER_CHANNELS}) ->
      *        attribute name in the effect's layout

package/src/shade/renderer/particles/runtime/create_particle_effect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create_particle_effect.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/create_particle_effect.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH;IALwE,MAAM,EAAnE,OAAO,6BAA6B,EAAE,cAAc;IACjC,IAAI;IACJ,MAAM;;YACb,OAAO,6BAA6B,EAAE,cAAc;aAAW,OAAO,2BAA2B,EAAE,eAAe;EAKxI"}
+{"version":3,"file":"create_particle_effect.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/create_particle_effect.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH;IALwE,MAAM,EAAnE,OAAO,6BAA6B,EAAE,cAAc;IACjC,IAAI;IACJ,MAAM;IACvB;IAAE,MAAM,EAAE,OAAO,6BAA6B,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,OAAO,2BAA2B,EAAE,eAAe,CAAA;CAAE,CAK1I"}

package/src/shade/renderer/particles/shaders/chunk_particle_avboit_contribution.js

@@ -57,10 +57,10 @@ fn particle_avboit_contribution(
     if (coverage <= 0.0) {
         /*
          Covers nothing: an additive emitter, or a premultiplied sprite with no alpha, which the
-         billboard pipeline blends the same way. It is dimmed by the fog in front of it, but it does
-         not carry the fog's own in-scatter: the scene it draws over already has that composited in,
-         and the resolve adds emission outside the normalization that would otherwise take the
-         duplicate away. Carrying it would add one copy of the fog per fragment.
+         blended billboard pipeline blends the same way. It is dimmed by the fog in front of it,
+         but it does not carry the fog's own in-scatter: the scene it draws over already has that
+         composited in, and the resolve adds emission outside the normalization that would otherwise
+         take the duplicate away. Carrying it would add one copy of the fog per fragment.
         */
         out.color = vec4<f32>(0.0);
         out.norm = vec4<f32>(0.0);

package/src/shade/renderer/particles/shaders/chunk_particle_billboard_vertex.d.ts

@@ -1,14 +1,15 @@
 /**
- * The billboard vertex stage, shared by every pass that rasterizes particles: the standalone
- * renderer, and the AVBOIT splat and draw. One instance per particle, six vertices per instance;
- * the instance indexes the slot list, the vertex picks a quad corner, and the corner is expanded
- * per the emitter's projection mode and projected with the camera.
+ * The billboard vertex stage, shared by every pass that rasterizes particles: the AVBOIT splat and
+ * draw, and the blended pipeline `particular` draws its CPU-simulated particles with. One instance
+ * per particle, six vertices per instance; the instance indexes the slot list, the vertex picks a
+ * quad corner, and the corner is expanded per the emitter's projection mode and projected with the
+ * camera.
  *
  * The enclosing shader binds `camera` (`CAMERA_UNIFORM_STRUCT`), `pool` and `emitter_database`
  * (`array<u32>`) and `draw_list` (the slot list, `array<u32>`) under those names; this reads them
  * directly, the way `sample_volumetrics` reads its textures. Which list that is, is the caller's
- * choice: the standalone path binds the depth-sorted one because a blended draw needs order, the
- * AVBOIT passes bind the alive list because the volume makes order irrelevant.
+ * choice: the AVBOIT passes bind the GPU system's alive list as it comes off compaction, because
+ * the volume and the accumulators are sums and no ordering would change a pixel.
  *
  * `view_depth` is the vertex's own view-space depth, interpolated across the quad — the depth the
  * AVBOIT passes place the fragment at.

package/src/shade/renderer/particles/shaders/chunk_particle_billboard_vertex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_particle_billboard_vertex.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_billboard_vertex.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;GAgBG;AACH,8CAFU,SAAS,CAuE6D;0BA7FtD,oCAAoC"}
+{"version":3,"file":"chunk_particle_billboard_vertex.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_billboard_vertex.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;GAiBG;AACH,8CAFU,SAAS,CAuE6D;0BA9FtD,oCAAoC"}

package/src/shade/renderer/particles/shaders/chunk_particle_billboard_vertex.js

@@ -6,16 +6,17 @@ import { chunk_particle_header } from "../data/particle_header.js";
 import { chunk_particle_render_math } from "./chunk_particle_render_math.js";
 
 /**
- * The billboard vertex stage, shared by every pass that rasterizes particles: the standalone
- * renderer, and the AVBOIT splat and draw. One instance per particle, six vertices per instance;
- * the instance indexes the slot list, the vertex picks a quad corner, and the corner is expanded
- * per the emitter's projection mode and projected with the camera.
+ * The billboard vertex stage, shared by every pass that rasterizes particles: the AVBOIT splat and
+ * draw, and the blended pipeline `particular` draws its CPU-simulated particles with. One instance
+ * per particle, six vertices per instance; the instance indexes the slot list, the vertex picks a
+ * quad corner, and the corner is expanded per the emitter's projection mode and projected with the
+ * camera.
  *
  * The enclosing shader binds `camera` (`CAMERA_UNIFORM_STRUCT`), `pool` and `emitter_database`
  * (`array<u32>`) and `draw_list` (the slot list, `array<u32>`) under those names; this reads them
  * directly, the way `sample_volumetrics` reads its textures. Which list that is, is the caller's
- * choice: the standalone path binds the depth-sorted one because a blended draw needs order, the
- * AVBOIT passes bind the alive list because the volume makes order irrelevant.
+ * choice: the AVBOIT passes bind the GPU system's alive list as it comes off compaction, because
+ * the volume and the accumulators are sums and no ordering would change a pixel.
  *
  * `view_depth` is the vertex's own view-space depth, interpolated across the quad — the depth the
  * AVBOIT passes place the fragment at.

package/src/shade/renderer/particles/shaders/chunk_particle_lighting.d.ts

@@ -1,8 +1,9 @@
 /**
- * Pluggable lighting hook for the billboard fragment shader. `particle_apply_lighting(color, world, normal)`
- * returns the lit colour; the default is a pass-through (unlit / emissive).
+ * Pluggable lighting hook for every particle fragment shader — the AVBOIT draw and the blended
+ * billboard pipeline alike. `particle_apply_lighting(color, world, normal)` returns the lit colour;
+ * the default is a pass-through (unlit / emissive).
  *
- * The production feature swaps this for a chunk that binds
+ * A caller swaps this for a chunk that binds
  * {@link ../../deferred/SHADING_LIGHT_RESOURCE_GROUP.js} and calls `shade_standard_material_direct` + IBL —
  * i.e. billboards reuse the exact same lighting path as opaque surfaces when an emitter opts in via
  * its `lighting` flag. Keeping it a hook means unlit emitters compile without pulling in the whole

package/src/shade/renderer/particles/shaders/chunk_particle_lighting.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_particle_lighting.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_lighting.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,4CAFU,SAAS,CAQhB;0BApBuB,oCAAoC"}
+{"version":3,"file":"chunk_particle_lighting.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_lighting.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,4CAFU,SAAS,CAQhB;0BArBuB,oCAAoC"}

package/src/shade/renderer/particles/shaders/chunk_particle_lighting.js

@@ -1,10 +1,11 @@
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 
 /**
- * Pluggable lighting hook for the billboard fragment shader. `particle_apply_lighting(color, world, normal)`
- * returns the lit colour; the default is a pass-through (unlit / emissive).
+ * Pluggable lighting hook for every particle fragment shader — the AVBOIT draw and the blended
+ * billboard pipeline alike. `particle_apply_lighting(color, world, normal)` returns the lit colour;
+ * the default is a pass-through (unlit / emissive).
  *
- * The production feature swaps this for a chunk that binds
+ * A caller swaps this for a chunk that binds
  * {@link ../../deferred/SHADING_LIGHT_RESOURCE_GROUP.js} and calls `shade_standard_material_direct` + IBL —
  * i.e. billboards reuse the exact same lighting path as opaque surfaces when an emitter opts in via
  * its `lighting` flag. Keeping it a hook means unlit emitters compile without pulling in the whole

package/src/shade/renderer/particles/shaders/chunk_particle_render_math.d.ts

@@ -1,6 +1,6 @@
 /**
- * Pure render-math helpers for the billboard renderer, kept separate so they can be unit-tested in
- * isolation (they take no bindings):
+ * Pure render-math helpers shared by every pass that draws a particle, kept separate so they can be
+ * unit-tested in isolation (they take no bindings):
  *
  * - `particle_billboard_offset` — expand a quad corner into a world-space offset for each projection
  *   / orientation mode (camera-facing, velocity-stretched, ground-aligned, axis-locked, world).

package/src/shade/renderer/particles/shaders/chunk_particle_render_math.js

@@ -2,8 +2,8 @@ import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 import { EMITTER_BLEND, EMITTER_PROJECTION } from "../data/PARTICLE_EMITTER_STRUCT.js";
 
 /**
- * Pure render-math helpers for the billboard renderer, kept separate so they can be unit-tested in
- * isolation (they take no bindings):
+ * Pure render-math helpers shared by every pass that draws a particle, kept separate so they can be
+ * unit-tested in isolation (they take no bindings):
  *
  * - `particle_billboard_offset` — expand a quad corner into a world-space offset for each projection
  *   / orientation mode (camera-facing, velocity-stretched, ground-aligned, axis-locked, world).
@@ -120,16 +120,16 @@ fn particle_atlas_uv(local_uv : vec2<f32>, region : vec4<f32>, flipbook : vec2<f
 
 // Soft-particle fade: 0 when the particle is at/behind the scene surface, ramping to 1 across
 // fade_range in view-space units. A non-positive scene depth means background (no fade).
-fn particle_soft_fade(scene_view_depth : f32, particle_view_depth : f32, fade_range : f32) -> f32 {
+fn particle_soft_fade(scene_view_depth : f32, particle_view_depth : f32, fade_range : f32) -> f32 {
     if (scene_view_depth <= 0.0) { return 1.0; }
     return smoothstep(0.0, max(fade_range, 1e-4), scene_view_depth - particle_view_depth);
-}
-
-// Premultiplied RGB already includes coverage, so fading it must scale both parts of the pair.
-fn particle_fade_color(color : vec4<f32>, blend : u32, fade : f32) -> vec4<f32> {
-    if (blend == PARTICLE_BLEND_PREMULTIPLIED) { return color * fade; }
-    return vec4<f32>(color.rgb, color.a * fade);
-}
+}
+
+// Premultiplied RGB already includes coverage, so fading it must scale both parts of the pair.
+fn particle_fade_color(color : vec4<f32>, blend : u32, fade : f32) -> vec4<f32> {
+    if (blend == PARTICLE_BLEND_PREMULTIPLIED) { return color * fade; }
+    return vec4<f32>(color.rgb, color.a * fade);
+}
 
 // Produce the premultiplied colour the single blend pipeline expects.
 fn particle_premultiply(color : vec4<f32>, blend : u32) -> vec4<f32> {

package/src/shade/renderer/particles/shaders/shader_particle_avboit_draw.js

@@ -26,9 +26,9 @@ import { chunk_particle_lighting_unlit } from "./chunk_particle_lighting.js";
  * (`avboit_draw_fragment_body`). The particle counterpart of `shader_avboit_draw_ibl`.
  *
  * Per fragment: the atlas sample times the particle colour, the soft-depth fade against the scene
- * depth and the lighting hook exactly as the standalone renderer applies them, the volumetric fog
- * composite exactly as the mesh draw applies it, then the transmittance of everything in front from
- * the integral texture — and a fragment the volume already calls extinct is discarded unshaded.
+ * depth and the lighting hook, the volumetric fog composite exactly as the mesh draw applies it,
+ * then the transmittance of everything in front from the integral texture — and a fragment the
+ * volume already calls extinct is discarded unshaded.
  *
  * What is written depends on how the particle blends:
  *

package/src/shade/renderer/particles/shaders/shader_particle_avboit_splat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_avboit_splat.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_avboit_splat.js"],"names":[],"mappings":"AAoBA;;;;GAIG;AACH,sDAFU,MAAM,CAEyC;AAqGzD;;;GAGG;AACH,6CAFU,wBAAwB,CAY/B;AAEH,8FAA8F;AAC9F,0EAAyD;AAEzD,mDAAmD;AACnD,4DAAuD;yCAjJd,iEAAiE;4CAY9D,sDAAsD;iCAFjE,kCAAkC"}
+{"version":3,"file":"shader_particle_avboit_splat.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_avboit_splat.js"],"names":[],"mappings":"AAoBA;;;;GAIG;AACH,sDAFU,MAAM,CAEyC;AAsGzD;;;GAGG;AACH,6CAFU,wBAAwB,CAY/B;AAEH,8FAA8F;AAC9F,0EAAyD;AAEzD,mDAAmD;AACnD,4DAAuD;yCAlJd,iEAAiE;4CAY9D,sDAAsD;iCAFjE,kCAAkC"}

package/src/shade/renderer/particles/shaders/shader_particle_avboit_splat.js

@@ -37,7 +37,8 @@ export const PARTICLE_AVBOIT_SPLAT_BIND_GROUP_VOLUME = 1;
  * Depth is the fragment's own view depth, from the vertex stage, through curve → warp → physical
  * and the two-slice linear splat. No depth attachment, for the reason the meshlet splat has none.
  *
- * The `draw_list` this binds is the alive list, unsorted: the volume does not care about order.
+ * The `draw_list` this binds is the alive list as compaction left it. The volume is a sum, so
+ * there is no order for it to be in.
  */
 
 const resources = new ShaderResourceSetDescriptor();

package/src/shade/renderer/particles/shaders/shader_particle_finalize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_finalize.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_finalize.js"],"names":[],"mappings":"AAqCA,2DAgBG;AAaH,2DAmCG;;8BAnG2B,+BAA+B;iDAIZ,+BAA+B"}
+{"version":3,"file":"shader_particle_finalize.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_finalize.js"],"names":[],"mappings":"AAoCA,2DAeG;AAaH,2DAkCG;;8BAhG2B,+BAA+B;iDAIZ,+BAA+B"}

package/src/shade/renderer/particles/shaders/shader_particle_finalize.js

@@ -9,25 +9,24 @@ import { PARTICLE_SIMULATE_WORKGROUP_SIZE } from "./shader_particle_simulate.js"
 /**
  * Small housekeeping passes that keep the pipeline GPU-driven:
  *
- * - {@link shader_particle_reset_counters} — zero the alive / sorted / sim-padded counters at the
- *   top of the frame (the dead count and the ALIVE_IN snapshot persist across frames), and seed the
+ * - {@link shader_particle_reset_counters} — zero the alive and sim-padded counters at the top of
+ *   the frame (the dead count and the ALIVE_IN snapshot persist across frames), and seed the
  *   frame's spawn budget from the dead count.
  * - {@link shader_particle_build_indirect} — turn the frame's two final counts into next frame's
  *   input contract: (a) snapshot the coherence pass's padded list length into
  *   {@link PARTICLE_COUNTER.ALIVE_IN} — the exact input length for NEXT frame's simulate, (b) write
  *   the indirect dispatch args next frame's simulate consumes, from that SAME value, and (c) write
- *   the indirect draw args for THIS frame's billboard render, from the alive count. Nothing
- *   round-trips to the CPU. Sizing the dispatch or draw from a stale CPU readback instead is a
- *   correctness bug: when the alive count grows the tail of the list is never simulated (slots leak
- *   into limbo), and when it shrinks stale entries beyond the written range get re-simulated — a
- *   dead slot is pushed to the free list twice and later popped twice, leaving two live particles
- *   sharing one record.
+ *   the indirect draw args for THIS frame's draws, from the alive count. Nothing round-trips to the
+ *   CPU. Sizing the dispatch or draw from a stale CPU readback instead is a correctness bug: when
+ *   the alive count grows the tail of the list is never simulated (slots leak into limbo), and when
+ *   it shrinks stale entries beyond the written range get re-simulated — a dead slot is pushed to
+ *   the free list twice and later popped twice, leaving two live particles sharing one record.
  *
  * The two lengths are deliberately different quantities and must not be conflated. Simulate consumes
- * the SIMULATION order: the program-coherent list from `../coherence/`, padded so no wave spans two
- * VM programs, and therefore longer than the alive count and always a whole number of workgroups.
- * The billboard draw consumes the RENDER order: one instance per live particle, unpadded — a
- * padding entry drawn as an instance would read a garbage record.
+ * the program-coherent list from `../coherence/`, padded so no wave spans two VM programs, and
+ * therefore longer than the alive count and always a whole number of workgroups. The draws consume
+ * the alive list: one instance per live particle, unpadded — a padding entry drawn as an instance
+ * would read a garbage record.
  */
 
 // --- reset ---
@@ -43,7 +42,6 @@ export const shader_particle_reset_counters = ComputeShader.from({
 @compute @workgroup_size(1, 1, 1)
 fn main() {
     atomicStore(&counters[${PARTICLE_COUNTER.ALIVE}u], 0u);
-    atomicStore(&counters[${PARTICLE_COUNTER.SORTED}u], 0u);
     atomicStore(&counters[${PARTICLE_COUNTER.SIM_PADDED}u], 0u);
 
     // This frame's spawn budget is the free list as it stands: the emitter tick pass takes from it
@@ -90,9 +88,8 @@ fn main() {
     dispatch_args[1] = 1u;
     dispatch_args[2] = 1u;
 
-    // Instanced billboard draw (consumed THIS frame): 6 verts per particle, one instance per alive.
-    // The render list is the unpadded one — an instance per padding entry would read a garbage
-    // record.
+    // Instanced draw (consumed THIS frame): 6 verts per particle, one instance per alive. The draw
+    // walks the unpadded alive list — an instance per padding entry would read a garbage record.
     draw_args[0] = 6u;
     draw_args[1] = alive;
     draw_args[2] = 0u;

package/src/shade/renderer/particles/shaders/shader_particle_render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_render.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_render.js"],"names":[],"mappings":"AA6FA;;;;;;;;;GASG;AACH;IAP4B,YAAY,GAA7B,MAAM;IACgB,YAAY,GAAlC,MAAM,GAAC,IAAI;IAEkB,aAAa;IAExC,wBAAwB,CA2BpC;;;;;;;;;;;;;;;;AAED,yFAAyF;AACzF,uEAAsD;yCAnIb,iEAAiE;4CAO9D,sDAAsD"}
+{"version":3,"file":"shader_particle_render.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_render.js"],"names":[],"mappings":"AAgGA;;;;;;;;;GASG;AACH;IAP4B,YAAY,GAA7B,MAAM;IACgB,YAAY,GAAlC,MAAM,GAAC,IAAI;IAEkB,aAAa;IAExC,wBAAwB,CA2BpC;;;;;;;;;;;;;;;;AAED,yFAAyF;AACzF,uEAAsD;yCAtIb,iEAAiE;4CAO9D,sDAAsD"}

package/src/shade/renderer/particles/shaders/shader_particle_render.js

@@ -7,22 +7,29 @@ import { ShaderDescriptor } from "../../shader/ShaderDescriptor.js";
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
 import { EMITTER_FLAG } from "../data/PARTICLE_EMITTER_STRUCT.js";
+import { PARTICLE_SOFT_FADE_RANGE } from "../ParticleConstants.js";
 import { chunk_particle_billboard_vertex } from "./chunk_particle_billboard_vertex.js";
 import { chunk_particle_lighting_unlit } from "./chunk_particle_lighting.js";
+import { chunk_particle_scene_view_depth } from "./chunk_particle_scene_view_depth.js";
 
 /**
- * The standalone billboard renderer: particles drawn straight over the scene colour, back to
- * front, with fixed-function blending. This is the path a page without the renderer's transparency
- * pipeline uses; under the renderer the particles go through AVBOIT instead
- * (`../graph_particles_avboit.js`), where order does not matter and they composite against the
- * transparent meshes.
+ * Blended billboards drawn straight over a colour target with fixed-function blending, in whatever
+ * order the caller's draw list happens to be in.
  *
- * One instanced draw covers every visible particle: `instance_index` indexes the depth-sorted
- * `draw_list`, `vertex_index` (0..5) picks a quad corner. The vertex stage is `chunk_particle_billboard_vertex`,
- * shared with the AVBOIT particle passes. The fragment stage samples the atlas sub-rect + flipbook
- * cell, applies an optional soft-depth fade against the scene depth, runs the pluggable lighting hook
- * (unlit by default; the feature swaps in the shading-chunk-backed one when an emitter enables
- * lighting), and emits premultiplied colour.
+ * Its one consumer is
+ * {@link ../../../../engine/graphics3/particles/GPUParticularRenderer.js GPUParticularRenderer},
+ * which draws `particular`'s CPU-simulated particles: it sorts every live particle back to front on
+ * the CPU and hands that order in as `draw_list`, which is what makes an order-dependent blend
+ * correct here. The GPU particle system does not use this pipeline — its particles go through
+ * AVBOIT (`../graph_particles_avboit.js`), where the accumulators are sums and no ordering exists
+ * or is needed.
+ *
+ * One instanced draw covers every particle: `instance_index` indexes `draw_list`, `vertex_index`
+ * (0..5) picks a quad corner. The vertex stage is `chunk_particle_billboard_vertex`, shared with the
+ * AVBOIT particle passes. The fragment stage samples the atlas sub-rect + flipbook cell, applies an
+ * optional soft-depth fade against the scene depth, runs the pluggable lighting hook (unlit by
+ * default; a caller swaps in the shading-chunk-backed one when an emitter enables lighting), and
+ * emits premultiplied colour.
  *
  * A single blend state — `src*1 + dst*(1-srcAlpha)` on both channels — expresses alpha and additive
  * blending; the shader chooses per particle by how it premultiplies (see `particle_premultiply`), so
@@ -54,7 +61,7 @@ const body = CodeChunk.from(
     /* language=wgsl */ `
 const PARTICLE_FLAG_SOFT_DEPTH : u32 = ${EMITTER_FLAG.SOFT_DEPTH}u;
 const PARTICLE_FLAG_LIGHTING : u32 = ${EMITTER_FLAG.LIGHTING}u;
-const PARTICLE_SOFT_FADE_RANGE : f32 = 0.5;
+const PARTICLE_SOFT_FADE_RANGE : f32 = ${PARTICLE_SOFT_FADE_RANGE};
 
 @vertex
 fn vs_main(@builtin(vertex_index) vi : u32, @builtin(instance_index) ii : u32) -> ParticleVertexOut {
@@ -67,12 +74,8 @@ fn fs_main(in : ParticleVertexOut) -> @location(0) vec4<f32> {
     var color = sampled * in.color;
 
     if ((in.flags & PARTICLE_FLAG_SOFT_DEPTH) != 0u) {
-        let scene_dev = textureLoad(scene_depth, vec2<i32>(in.clip.xy), 0).r;
-        // Reverse-Z hyperbolic linearisation: view_depth = A / (device_depth + B).
-        let A = camera.device_depth_to_view_space.y;
-        let B = camera.device_depth_to_view_space.x;
-        let scene_vd = select(A / (scene_dev + B), 1e9, scene_dev <= 0.0);
-        color = particle_fade_color(color, in.blend, particle_soft_fade(scene_vd, in.view_depth, PARTICLE_SOFT_FADE_RANGE));
+        let scene_vd = particle_scene_view_depth(textureLoad(scene_depth, vec2<i32>(in.clip.xy), 0).r, camera);
+        color = particle_fade_color(color, in.blend, particle_soft_fade(scene_vd, in.view_depth, PARTICLE_SOFT_FADE_RANGE));
     }
 
     if ((in.flags & PARTICLE_FLAG_LIGHTING) != 0u) {
@@ -81,7 +84,7 @@ fn fs_main(in : ParticleVertexOut) -> @location(0) vec4<f32> {
 
     return particle_premultiply(color, in.blend);
 }
-`, [chunk_particle_billboard_vertex, chunk_particle_lighting_unlit]);
+`, [chunk_particle_billboard_vertex, chunk_particle_lighting_unlit, chunk_particle_scene_view_depth]);
 
 /**
  * The shader itself. One compilation, shared by every pipeline built from it — the options below

package/src/shade/renderer/particles/vm/ParticleVMReference.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ParticleVMReference.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/vm/ParticleVMReference.js"],"names":[],"mappings":"AA0BA;;;;;;;GAOG;AACH,gCAHW,MAAM;WACK,MAAM;WAAS,MAAM;EAW1C;AAED;;;;;GAKG;AACH,mCAHW,MAAM,GACJ,MAAM,CAIlB;AA8DD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAR+B,KAAK,EAAzB,WAAW;IACU,SAAS,EAA9B,YAAY;IACG,cAAc,EAA7B,MAAM;IACc,MAAM,EAA1B,WAAW;IACS,QAAQ,GAA5B,MAAM,EAAE,EAAE;IACM,SAAS,GAAzB,MAAM;;YACM,OAAO;eAAa,MAAM;EAuRhD"}
+{"version":3,"file":"ParticleVMReference.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/vm/ParticleVMReference.js"],"names":[],"mappings":"AA0BA;;;;;;;GAOG;AACH,gCAHW,MAAM,GACJ;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAW5C;AAED;;;;;GAKG;AACH,mCAHW,MAAM,GACJ,MAAM,CAIlB;AA8DD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAR+B,KAAK,EAAzB,WAAW;IACU,SAAS,EAA9B,YAAY;IACG,cAAc,EAA7B,MAAM;IACc,MAAM,EAA1B,WAAW;IACS,QAAQ,GAA5B,MAAM,EAAE,EAAE;IACM,SAAS,GAAzB,MAAM;IACJ;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAuRlD"}

package/src/shade/renderer/path_tracer/accumulating/AccumulatingPathTracer.d.ts

@@ -49,11 +49,18 @@ export class AccumulatingPathTracer {
     /**
      * Render one tile worth of new samples and blend it into the accumulation buffer.
      *
-     * @param {GPUViewContext} view
-     * @param {FrameGraph} graph
+     * @param {Object} options
+     * @param {GPUViewContext} options.view
+     * @param {FrameGraph} options.graph
      * @returns {number} resource id of the accumulated output texture
      */
-    render({ view, graph }: GPUViewContext): number;
+    render({ view, graph }: {
+        view: GPUViewContext;
+        graph: FrameGraph;
+    }): number;
     #private;
 }
+export type FrameGraph = import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+export type GraphicsContext = import("../../GraphicsContext.js").GraphicsContext;
+export type GPUViewContext = import("../../view/GPUViewContext.js").GPUViewContext;
 //# sourceMappingURL=AccumulatingPathTracer.d.ts.map

package/src/shade/renderer/path_tracer/accumulating/AccumulatingPathTracer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AccumulatingPathTracer.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/path_tracer/accumulating/AccumulatingPathTracer.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;GAcG;AACH;IA8EI;;;OAGG;IACH,uCAgBC;IAhGD;;;;OAIG;IACH,kBAFU,MAAM,CAEO;IAEvB;;;;OAIG;IACH,wBAFU,MAAM,CAEc;IAE9B;;;;OAIG;IACH,eAFU,OAAO,CAEK;IA+NtB;;;;;;;OAOG;IACH,+BAgBC;IAED;;;;;;OAMG;IACH,yCAFa,MAAM,CAyJlB;;CACJ"}
+{"version":3,"file":"AccumulatingPathTracer.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/path_tracer/accumulating/AccumulatingPathTracer.js"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;GAcG;AACH;IA8EI;;;OAGG;IACH,sBAFW,eAAe,EAkBzB;IAhGD;;;;OAIG;IACH,kBAFU,MAAM,CAEO;IAEvB;;;;OAIG;IACH,wBAFU,MAAM,CAEc;IAE9B;;;;OAIG;IACH,eAFU,OAAO,CAEK;IA+NtB;;;;;;;OAOG;IACH,+BAgBC;IAED;;;;;;;OAOG;IACH;QAJmC,IAAI,EAA5B,cAAc;QACM,KAAK,EAAzB,UAAU;QACR,MAAM,CAyJlB;;CACJ;yBAxcY,OAAO,8DAA8D,EAAE,UAAU;8BAIjF,OAAO,0BAA0B,EAAE,eAAe;6BAClD,OAAO,8BAA8B,EAAE,cAAc"}

package/src/shade/renderer/path_tracer/accumulating/AccumulatingPathTracer.js

@@ -7,6 +7,15 @@ import { graph_flood_fill } from "./graph_flood_fill.js";
 import { graph_float32rgba_to_float16rgba } from "./graph_float32rgba_to_float16rgba.js";
 import { shader_accumulating_path_tracer } from "./shader_accumulating_path_tracer.js";
 
+/**
+ * @typedef {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
+ */
+
+/**
+ * @typedef {import("../../GraphicsContext.js").GraphicsContext} GraphicsContext
+ * @typedef {import("../../view/GPUViewContext.js").GPUViewContext} GPUViewContext
+ */
+
 
 const RGBA32FLOAT_BYTES_PER_PIXEL = 16;
 
@@ -298,8 +307,9 @@ export class AccumulatingPathTracer {
     /**
      * Render one tile worth of new samples and blend it into the accumulation buffer.
      *
-     * @param {GPUViewContext} view
-     * @param {FrameGraph} graph
+     * @param {Object} options
+     * @param {GPUViewContext} options.view
+     * @param {FrameGraph} options.graph
      * @returns {number} resource id of the accumulated output texture
      */
     render({ view, graph }) {

package/src/shade/renderer/path_tracer/graph_path_trace_scene.d.ts

@@ -1,8 +1,12 @@
 /**
  *
- * @param {FrameGraph} graph
- * @param {GPUViewContext} view
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {GPUViewContext} options.view
  * @returns {number}
  */
-export function graph_path_trace_scene({ graph, view, }: FrameGraph): number;
+export function graph_path_trace_scene({ graph, view, }: {
+    graph: FrameGraph;
+    view: GPUViewContext;
+}): number;
 //# sourceMappingURL=graph_path_trace_scene.d.ts.map

package/src/shade/renderer/path_tracer/graph_path_trace_scene.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_path_trace_scene.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/path_tracer/graph_path_trace_scene.js"],"names":[],"mappings":"AAgGA;;;;;GAKG;AACH,sEAFa,MAAM,CAoFlB"}
+{"version":3,"file":"graph_path_trace_scene.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/path_tracer/graph_path_trace_scene.js"],"names":[],"mappings":"AAgGA;;;;;;GAMG;AACH;IAJ+B,KAAK;IACD,IAAI;IAC1B,MAAM,CAoFlB"}

package/src/shade/renderer/path_tracer/graph_path_trace_scene.js

@@ -96,8 +96,9 @@ const shader = ComputeShader.from({
 
 /**
  *
- * @param {FrameGraph} graph
- * @param {GPUViewContext} view
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {GPUViewContext} options.view
  * @returns {number}
  */
 export function graph_path_trace_scene({

package/src/shade/renderer/postprocess/bloom/graph_bloom_downsample.d.ts

@@ -1,9 +1,15 @@
 /**
  *
- * @param {FrameGraph} graph
- * @param {number} input
- * @param {number[]} resolution
- * @param {number} [mips] how many mips to generate, more mips generally equals higher quality, but 5 is generally enough for high quality, less than 3 is not recommended
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {number} options.input
+ * @param {number[]} options.resolution
+ * @param {number} [options.mips] how many mips to generate, more mips generally equals higher quality, but 5 is generally enough for high quality, less than 3 is not recommended
  */
-export function graph_bloom_downsample({ graph, input, resolution, mips, }: FrameGraph): any;
+export function graph_bloom_downsample({ graph, input, resolution, mips, }: {
+    graph: FrameGraph;
+    input: number;
+    resolution: number[];
+    mips?: number;
+}): any;
 //# sourceMappingURL=graph_bloom_downsample.d.ts.map

package/src/shade/renderer/postprocess/bloom/graph_bloom_downsample.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_bloom_downsample.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/postprocess/bloom/graph_bloom_downsample.js"],"names":[],"mappings":"AASA;;;;;;GAMG;AACH,6FA6FC"}
+{"version":3,"file":"graph_bloom_downsample.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/postprocess/bloom/graph_bloom_downsample.js"],"names":[],"mappings":"AASA;;;;;;;GAOG;AACH;IAL+B,KAAK;IACT,KAAK,EAArB,MAAM;IACY,UAAU,EAA5B,MAAM,EAAE;IACS,IAAI,GAArB,MAAM;QA+FhB"}

package/src/shade/renderer/postprocess/bloom/graph_bloom_downsample.js

@@ -9,10 +9,11 @@ import { downsample_standard } from "./downsample_standard.js";
 
 /**
  *
- * @param {FrameGraph} graph
- * @param {number} input
- * @param {number[]} resolution
- * @param {number} [mips] how many mips to generate, more mips generally equals higher quality, but 5 is generally enough for high quality, less than 3 is not recommended
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {number} options.input
+ * @param {number[]} options.resolution
+ * @param {number} [options.mips] how many mips to generate, more mips generally equals higher quality, but 5 is generally enough for high quality, less than 3 is not recommended
  */
 export function graph_bloom_downsample({
                                            graph,

package/src/shade/renderer/postprocess/bloom/graph_postprocess_bloom.d.ts

@@ -1,12 +1,19 @@
 /**
  *
- * @param {FrameGraph} graph
- * @param {number} input
- * @param {number[]} resolution
- * @param {number} [intensity]
- * @param {number} [mips] how many mips to generate, more mips generally equals higher quality, but 5 is generally enough for high quality, less than 3 is not recommended
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {number} options.input
+ * @param {number[]} options.resolution
+ * @param {number} [options.intensity]
+ * @param {number} [options.mips] how many mips to generate, more mips generally equals higher quality, but 5 is generally enough for high quality, less than 3 is not recommended
  */
-export function graph_postprocess_bloom({ graph, input, resolution, intensity, mips }: FrameGraph): {
+export function graph_postprocess_bloom({ graph, input, resolution, intensity, mips }: {
+    graph: FrameGraph;
+    input: number;
+    resolution: number[];
+    intensity?: number;
+    mips?: number;
+}): {
     composited: number;
     downsampled: any;
 };

package/src/shade/renderer/postprocess/bloom/graph_postprocess_bloom.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_postprocess_bloom.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/postprocess/bloom/graph_postprocess_bloom.js"],"names":[],"mappings":"AAoGA;;;;;;;GAOG;AACH;;;EA+CC"}
+{"version":3,"file":"graph_postprocess_bloom.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/postprocess/bloom/graph_postprocess_bloom.js"],"names":[],"mappings":"AAqGA;;;;;;;;GAQG;AACH;IAN+B,KAAK;IACT,KAAK,EAArB,MAAM;IACY,UAAU,EAA5B,MAAM,EAAE;IACS,SAAS,GAA1B,MAAM;IACW,IAAI,GAArB,MAAM;;;;EAiDhB"}

package/src/shade/renderer/postprocess/bloom/graph_postprocess_bloom.js

@@ -11,10 +11,11 @@ import { upsample_blur } from "./upsample_blur.js";
 
 /**
  *
- * @param {FrameGraph} graph
- * @param {number} input downsampled map (half res)
- * @param {number[]} resolution
- * @param {number} [mips] how many mips to generate, more mips generally equals higher quality, but 5 is generally enough for high quality, less than 3 is not recommended
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {number} options.input downsampled map (half res)
+ * @param {number[]} options.resolution
+ * @param {number} [options.mips] how many mips to generate, more mips generally equals higher quality, but 5 is generally enough for high quality, less than 3 is not recommended
  */
 function graph_bloom_upsample({
                                   graph,
@@ -100,11 +101,12 @@ function graph_bloom_upsample({
 
 /**
  *
- * @param {FrameGraph} graph
- * @param {number} input
- * @param {number[]} resolution
- * @param {number} [intensity]
- * @param {number} [mips] how many mips to generate, more mips generally equals higher quality, but 5 is generally enough for high quality, less than 3 is not recommended
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {number} options.input
+ * @param {number[]} options.resolution
+ * @param {number} [options.intensity]
+ * @param {number} [options.mips] how many mips to generate, more mips generally equals higher quality, but 5 is generally enough for high quality, less than 3 is not recommended
  */
 export function graph_postprocess_bloom({
                                             graph,