@woosh/meep-engine 3.21.0 → 3.22.0

package/src/shade/renderer/particles/graph_particles_avboit.js

@@ -6,9 +6,9 @@ import { AVBOIT_OCCUPANCY_SETTINGS_STRUCT } from "../rasterize/native/avboit/sha
 import { STATIC_GRAPHICS_ENGINE_ASSETS } from "../STATIC_GRAPHICS_ENGINE_ASSETS.js";
 import { shader_particle_avboit_occupancy } from "./shaders/shader_particle_avboit_occupancy.js";
 import {
-    PARTICLE_AVBOIT_DRAW_ALPHA_PIPELINE,
-    PARTICLE_AVBOIT_DRAW_ADDITIVE_PIPELINE,
-    PARTICLE_AVBOIT_DRAW_GENERAL_PIPELINE,
+    PARTICLE_AVBOIT_DRAW_ALPHA_PIPELINE,
+    PARTICLE_AVBOIT_DRAW_ADDITIVE_PIPELINE,
+    PARTICLE_AVBOIT_DRAW_GENERAL_PIPELINE,
     PARTICLE_AVBOIT_DRAW_RESOURCES,
 } from "./shaders/shader_particle_avboit_draw.js";
 import {
@@ -26,9 +26,9 @@ import {
  * GPU-driven: the draws are `drawIndirect` over the GPU's own alive count, and the occupancy walks
  * the emitter table's pages. Nothing here knows how many particles there are.
  *
- * Order does not matter to any of them — the volume and the accumulators are order-independent — so
- * the depth sort the standalone billboard draw needs is not run for this path, and its buffers are
- * never made. That is what {@link ParticleRenderMode.AVBOIT} means.
+ * Order does not matter to any of them: the volume and the accumulators are sums, so no arrangement
+ * of the draw changes a pixel. That is why the particles are never depth-sorted — the alive list
+ * comes off the simulation compacted, and it is drawn as it stands.
  */
 
 /** The accumulators' view: one mip, the one the frame draws into. */
@@ -270,7 +270,7 @@ export function graph_particle_avboit_draw({
         // allowed because the attachment is read-only.
         const pass_encoder = encoder.constructRenderPass({
             label: "Particle AVBOIT Draw",
-            pipeline: PARTICLE_AVBOIT_DRAW_ALPHA_PIPELINE,
+            pipeline: PARTICLE_AVBOIT_DRAW_ALPHA_PIPELINE,
             bindings,
             colorAttachments: [
                 attachment(data.color),
@@ -283,15 +283,15 @@ export function graph_particle_avboit_draw({
                 depthReadOnly: true,
             },
         });
-        // All three use the alive list; their vertex stages select disjoint particle groups.
-        // Premultiplied particles can both cover and emit, so they retain the general pipeline.
-        const args = resources.get(data.draw_args);
-        pass_encoder.drawIndirect(args, 0);
-        pass_encoder.setPipeline(graphics.render_pipelines.obtain(PARTICLE_AVBOIT_DRAW_ADDITIVE_PIPELINE));
-        pass_encoder.drawIndirect(args, 0);
-        pass_encoder.setPipeline(graphics.render_pipelines.obtain(PARTICLE_AVBOIT_DRAW_GENERAL_PIPELINE));
-        pass_encoder.drawIndirect(args, 0);
-        pass_encoder.end();
+        // All three use the alive list; their vertex stages select disjoint particle groups.
+        // Premultiplied particles can both cover and emit, so they retain the general pipeline.
+        const args = resources.get(data.draw_args);
+        pass_encoder.drawIndirect(args, 0);
+        pass_encoder.setPipeline(graphics.render_pipelines.obtain(PARTICLE_AVBOIT_DRAW_ADDITIVE_PIPELINE));
+        pass_encoder.drawIndirect(args, 0);
+        pass_encoder.setPipeline(graphics.render_pipelines.obtain(PARTICLE_AVBOIT_DRAW_GENERAL_PIPELINE));
+        pass_encoder.drawIndirect(args, 0);
+        pass_encoder.end();
     }
 
     const pass_data = {};

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

@@ -75,13 +75,13 @@ export class EmitterRegistry {
      * The emitter table.
      * @returns {GPUTypedTable}
      */
-    get table(): GPUTypedTable;
+    get table(): import("../../buffer/table/GPUTypedTable.js").GPUTypedTable<any>;
     /**
      * The GPU-owned state table: one row per emitter, at the emitter's row, claimed and released
      * here and otherwise the GPU's.
      * @returns {GPUTypedTable}
      */
-    get state_table(): GPUTypedTable;
+    get state_table(): import("../../buffer/table/GPUTypedTable.js").GPUTypedTable<any>;
     /**
      * @returns {number} number of live emitters
      */
@@ -214,6 +214,7 @@ export class EmitterRegistry {
     build_program(): Uint32Array;
     #private;
 }
+export type GPUTypedTable = import("../../buffer/table/GPUTypedTable.js").GPUTypedTable<any>;
 import { GPUDatabase } from "../../buffer/table/GPUDatabase.js";
 import { ProgramHeap } from "./ProgramHeap.js";
 import { ParticleEmitter } from "./ParticleEmitter.js";

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

@@ -1 +1 @@
-{"version":3,"file":"EmitterRegistry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/EmitterRegistry.js"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IA8EI;;OAEG;IACH,+BASC;IAxFD;;OAEG;IACH,UAFU,WAAW,CAEZ;IAET;;;OAGG;IACH,UAFU,WAAW,CAEQ;IAE7B;;;OAGG;IACH,4BAFU,MAAM,CAEe;IAE/B;;;OAGG;IACH,UAFU,eAAe,EAAE,CAEb;IAEd;;;;;OAKG;IACH,QAFU,eAAe,EAAE,CAEf;IAEZ;;;;;;;;;;OAUG;IACH,8BAEC;IA8CD;;;OAGG;IACH,2BAEC;IAED;;;;OAIG;IACH,iCAEC;IAED;;OAEG;IACH,oBAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;;;OAKG;IACH,kCAEC;IAED;;;;;;;OAOG;IACH,iCAEC;IAED;;;;;;;;;OASG;IACH,iBAHW,eAAe,GACb,yBAAyB,GAAC,SAAS,CAI/C;IAED;;;;;;;;OAQG;IACH,YANW,eAAe,GAAC,MAAM,kBAEtB,MAAM,GAEJ,eAAe,CA+B3B;IAED;;;;;;;;;;;;;OAaG;IACH,gBAFW,eAAe,QA6BzB;IAED;;;;;;;;;;;;;;;OAeG;IACH,qBAHW,eAAe,WACf,OAAO,2BAA2B,EAAE,eAAe,QA0B7D;IAED;;;;;OAKG;IACH,SAHW,MAAM,GACJ,eAAe,GAAC,SAAS,CAIrC;IAED;;;;;;OAMG;IACH,2BAHW,eAAe,iBACf,MAAM,QAehB;IAED;;;;;;;;;OASG;IACH,0BAHW,eAAe,UACf,UAAU,MAAM,CAAC,QAoB3B;IAED;;;;;;;;;;;;;OAaG;IACH,cA4BC;IAED;;;;;;;;;OASG;IACH,iBAFa,WAAW,CAMvB;;CACJ;4BAzc2B,mCAAmC;4BAYnC,kBAAkB;gCADd,sBAAsB;0CADZ,gCAAgC"}
+{"version":3,"file":"EmitterRegistry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/EmitterRegistry.js"],"names":[],"mappings":"AA0BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IA8EI;;OAEG;IACH,+BASC;IAxFD;;OAEG;IACH,UAFU,WAAW,CAEZ;IAET;;;OAGG;IACH,UAFU,WAAW,CAEQ;IAE7B;;;OAGG;IACH,4BAFU,MAAM,CAEe;IAE/B;;;OAGG;IACH,UAFU,eAAe,EAAE,CAEb;IAEd;;;;;OAKG;IACH,QAFU,eAAe,EAAE,CAEf;IAEZ;;;;;;;;;;OAUG;IACH,8BAEC;IA8CD;;;OAGG;IACH,8EAEC;IAED;;;;OAIG;IACH,oFAEC;IAED;;OAEG;IACH,oBAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;;;OAKG;IACH,kCAEC;IAED;;;;;;;OAOG;IACH,iCAEC;IAED;;;;;;;;;OASG;IACH,iBAHW,eAAe,GACb,yBAAyB,GAAC,SAAS,CAI/C;IAED;;;;;;;;OAQG;IACH,YANW,eAAe,GAAC,MAAM,kBAEtB,MAAM,GAEJ,eAAe,CA+B3B;IAED;;;;;;;;;;;;;OAaG;IACH,gBAFW,eAAe,QA6BzB;IAED;;;;;;;;;;;;;;;OAeG;IACH,qBAHW,eAAe,WACf,OAAO,2BAA2B,EAAE,eAAe,QA0B7D;IAED;;;;;OAKG;IACH,SAHW,MAAM,GACJ,eAAe,GAAC,SAAS,CAIrC;IAED;;;;;;OAMG;IACH,2BAHW,eAAe,iBACf,MAAM,QAehB;IAED;;;;;;;;;OASG;IACH,0BAHW,eAAe,UACf,UAAU,MAAM,CAAC,QAoB3B;IAED;;;;;;;;;;;;;OAaG;IACH,cA4BC;IAED;;;;;;;;;OASG;IACH,iBAFa,WAAW,CAMvB;;CACJ;;4BA7c2B,mCAAmC;4BAYnC,kBAAkB;gCADd,sBAAsB;0CADZ,gCAAgC"}

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

@@ -13,6 +13,10 @@ import { GPUParticleEmitterContext } from "./GPUParticleEmitterContext.js";
 import { ParticleEmitter } from "./ParticleEmitter.js";
 import { ProgramHeap } from "./ProgramHeap.js";
 
+/**
+ * @typedef {import("../../buffer/table/GPUTypedTable.js").GPUTypedTable} GPUTypedTable
+ */
+
 /**
  * Staging for one emitter row. Reused across every write — the table serializes it into its page
  * shadow synchronously, so nothing outlives the call. This is what keeps a frame's flush free of
@@ -61,13 +65,13 @@ export class EmitterRegistry {
      * Packed instruction + constant buffers for every distinct program in the set.
      * @type {ProgramHeap}
      */
-    programs = new ProgramHeap();
-
-    /**
-     * Changes when a live emitter moves to different bytecode; invalidates simulation grouping.
-     * @type {number}
-     */
-    program_assignment_version = 0;
+    programs = new ProgramHeap();
+
+    /**
+     * Changes when a live emitter moves to different bytecode; invalidates simulation grouping.
+     * @type {number}
+     */
+    program_assignment_version = 0;
 
     /**
      * The live emitters, in no particular order — the row in {@link context} is the identity.
@@ -226,8 +230,8 @@ export class EmitterRegistry {
 
         const context = new GPUParticleEmitterContext();
 
-        context.placement = this.programs.acquire(emitter.program);
-        context.program = emitter.program;
+        context.placement = this.programs.acquire(emitter.program);
+        context.program = emitter.program;
 
         context.generation = this.#generation;
         this.#generation = particle_generation_next(this.#generation);
@@ -287,8 +291,8 @@ export class EmitterRegistry {
 
         this.programs.release(context.placement);
 
-        context.placement = null;
-        context.program = null;
+        context.placement = null;
+        context.program = null;
 
         this.#contexts.delete(emitter);
     }
@@ -323,12 +327,12 @@ export class EmitterRegistry {
         // unpacks it nor gives it a new id
         context.placement = this.programs.acquire(program);
 
-        emitter.program = program;
-        context.program = program;
-
-        if (context.placement !== previous) {
-            this.program_assignment_version++;
-        }
+        emitter.program = program;
+        context.program = program;
+
+        if (context.placement !== previous) {
+            this.program_assignment_version++;
+        }
 
         this.programs.release(previous);
 
@@ -411,16 +415,16 @@ export class EmitterRegistry {
      * Stages through the one module-static record, so a frame's restaging allocates nothing however
      * many rows it touches.
      */
-    flush() {
-        const table = this.table;
-
-        // Reconcile plain-field edits before checking relocation: an acquire can repack the heap
-        // and move placements of rows we would otherwise have already staged.
-        for (const [emitter, context] of this.#contexts) {
-            if (emitter.program !== context.program) {
-                this.set_program(emitter, emitter.program);
-            }
-        }
+    flush() {
+        const table = this.table;
+
+        // Reconcile plain-field edits before checking relocation: an acquire can repack the heap
+        // and move placements of rows we would otherwise have already staged.
+        for (const [emitter, context] of this.#contexts) {
+            if (emitter.program !== context.program) {
+                this.set_program(emitter, emitter.program);
+            }
+        }
 
         const placement_version = this.programs.placement_version;
 

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/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/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"}