@woosh/meep-engine 3.15.0 → 3.16.0

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

@@ -1,26 +1,55 @@
-import { PARTICLE_VM_INSTRUCTION_WORDS } from "../ParticleConstants.js";
+import {
+    PARTICLE_PROGRAM_CODE_BASE_WORD,
+    PARTICLE_PROGRAM_HEADER_WORDS,
+    PARTICLE_VM_INSTRUCTION_WORDS,
+} from "../ParticleConstants.js";
 
 /**
- * Packs many compiled {@link ../isa/ParticleProgram.js} programs into two shared buffers — one of
- * instruction words, one of constant words — and hands back the offsets each emitter records.
+ * Packs many compiled {@link ../isa/ParticleProgram.js} programs into one shared buffer — a header,
+ * every program's constant pool, then every program's instruction words — and hands back the
+ * offsets each emitter records.
+ *
+ * Data before code, behind a four-word header whose first word says where the code starts: the VM
+ * reads both sections through one binding (a storage buffer per stage is not free, and code and
+ * constants are read together), and an emitter's constant pool sits next to the pools of the
+ * programs it shares a wave with.
  *
  * Because VM instructions carry no absolute code addresses (control flow is branchless) and
- * constant references are program-local (the shader adds the emitter's `constant_offset`), programs
- * can be concatenated at any offset. SPAWN and UPDATE sections are laid out back-to-back per program.
+ * constant references are program-local (the VM adds the emitter's `constant_offset`), programs
+ * can be concatenated at any offset. INIT and UPDATE sections are laid out back-to-back per program.
  */
 export class ProgramArena {
-    constructor() {
-        /** @type {number[]} flat instruction words */
-        this.instruction_words = [];
-        /** @type {number[]} flat constant words (f32 bit patterns) */
-        this.constant_words = [];
-        /** @type {number} running instruction index (SPAWN/UPDATE offsets are in these units) */
-        this.instruction_count = 0;
-        /** @type {number} running vec4 constant index */
-        this.constant_count = 0;
-        /** @type {Map<string, object>} content key -> the placement the first identical program got */
-        this.programs = new Map();
-    }
+
+    /**
+     * Flat instruction words, every program's INIT and UPDATE sections concatenated.
+     * @type {number[]}
+     */
+    instruction_words = [];
+
+    /**
+     * Flat constant words (f32 bit patterns), every program's pool concatenated.
+     * @type {number[]}
+     */
+    constant_words = [];
+
+    /**
+     * Running instruction index — INIT/UPDATE offsets are in these units.
+     * @type {number}
+     */
+    instruction_count = 0;
+
+    /**
+     * Running constant word index — the pool is addressed by word, so a scalar literal costs one
+     * rather than the four a `vec4` entry used to.
+     * @type {number}
+     */
+    constant_word_count = 0;
+
+    /**
+     * Content key -> the placement the first identical program got.
+     * @type {Map<string, {init_offset: number, init_count: number, update_offset: number, update_count: number, constant_offset: number, program_id: number}>}
+     */
+    programs = new Map();
 
     /**
      * Number of distinct programs in the arena — and therefore the number of buckets the
@@ -45,7 +74,7 @@ export class ProgramArena {
      * which both wastes lanes and splits a run that was already program-coherent.
      *
      * @param {import("../isa/ParticleProgram.js").ParticleProgram} program
-     * @returns {{spawn_offset: number, spawn_count: number, update_offset: number, update_count: number, constant_offset: number, program_id: number}}
+     * @returns {{init_offset: number, init_count: number, update_offset: number, update_count: number, constant_offset: number, program_id: number}}
      */
     add(program) {
         const key = program_content_key(program);
@@ -55,23 +84,23 @@ export class ProgramArena {
             return existing;
         }
 
-        const spawn_offset = this.instruction_count;
-        this.#append_instructions(program.spawn);
-        const spawn_count = program.spawn_instruction_count;
+        const init_offset = this.instruction_count;
+        this.#append_instructions(program.init);
+        const init_count = program.init_instruction_count;
 
         const update_offset = this.instruction_count;
         this.#append_instructions(program.update);
         const update_count = program.update_instruction_count;
 
-        const constant_offset = this.constant_count;
+        const constant_offset = this.constant_word_count;
         const constant_u32 = new Uint32Array(program.constants.buffer, program.constants.byteOffset, program.constants.length);
         for (let i = 0; i < constant_u32.length; i++) {
             this.constant_words.push(constant_u32[i]);
         }
-        this.constant_count += program.constant_count;
+        this.constant_word_count += program.constant_word_count;
 
         const placement = {
-            spawn_offset, spawn_count, update_offset, update_count, constant_offset,
+            init_offset, init_count, update_offset, update_count, constant_offset,
             program_id: this.programs.size,
         };
         this.programs.set(key, placement);
@@ -87,14 +116,25 @@ export class ProgramArena {
         this.instruction_count += words.length / PARTICLE_VM_INSTRUCTION_WORDS;
     }
 
-    /** @returns {Uint32Array} the packed instruction buffer (at least length 1) */
-    build_instruction_buffer() {
-        return new Uint32Array(this.instruction_words.length > 0 ? this.instruction_words : [0]);
-    }
+    /**
+     * The packed buffer: `[header][constants][code]`. Word {@link PARTICLE_PROGRAM_CODE_BASE_WORD} of
+     * the header is the word index the code starts at, which moves every time a program's constants
+     * are appended — the emitter records never carry it, they carry offsets into each section.
+     *
+     * @returns {Uint32Array}
+     */
+    build_program_buffer() {
+        const constants = this.constant_words;
+        const code = this.instruction_words;
+
+        const code_base = PARTICLE_PROGRAM_HEADER_WORDS + constants.length;
+        const buffer = new Uint32Array(code_base + code.length);
+
+        buffer[PARTICLE_PROGRAM_CODE_BASE_WORD] = code_base;
+        buffer.set(constants, PARTICLE_PROGRAM_HEADER_WORDS);
+        buffer.set(code, code_base);
 
-    /** @returns {Uint32Array} the packed constant buffer (at least length 4 for one vec4) */
-    build_constant_buffer() {
-        return new Uint32Array(this.constant_words.length > 0 ? this.constant_words : [0, 0, 0, 0]);
+        return buffer;
     }
 }
 
@@ -111,5 +151,5 @@ function program_content_key(program) {
     const constants = program.constants;
     const constant_u32 = new Uint32Array(constants.buffer, constants.byteOffset, constants.length);
 
-    return `${program.register_count}|${program.spawn.join(",")}|${program.update.join(",")}|${constant_u32.join(",")}`;
+    return `${program.register_count}|${program.init.join(",")}|${program.update.join(",")}|${constant_u32.join(",")}`;
 }

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

@@ -1,5 +1,5 @@
 /**
- * Compile a particle effect: a per-particle attribute {@link ../layout/ParticleLayout.js} plus SPAWN
+ * Compile a particle effect: a per-particle attribute {@link ../layout/ParticleLayout.js} plus INIT
  * and UPDATE node graphs, lowered to VM bytecode.
  *
  * The returned value bundles the layout with the compiled program so the {@link ./EmitterRegistry.js}
@@ -7,13 +7,13 @@
  *
  * @param {object} params
  * @param {import("../layout/ParticleLayout.js").ParticleLayout} params.layout
- * @param {NodeGraph} [params.spawn]
+ * @param {NodeGraph} [params.init]
  * @param {NodeGraph} [params.update]
  * @returns {{ layout: import("../layout/ParticleLayout.js").ParticleLayout, program: import("../isa/ParticleProgram.js").ParticleProgram }}
  */
-export function create_particle_effect({ layout, spawn, update }: {
+export function create_particle_effect({ layout, init, update }: {
     layout: import("../layout/ParticleLayout.js").ParticleLayout;
-    spawn?: NodeGraph;
+    init?: NodeGraph;
     update?: NodeGraph;
 }): {
     layout: import("../layout/ParticleLayout.js").ParticleLayout;

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;;;;;;;;;;;;GAYG;AACH;IALwE,MAAM,EAAnE,OAAO,6BAA6B,EAAE,cAAc;IACjC,KAAK;IACL,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;;;;;;;;;;;;GAYG;AACH;IALwE,MAAM,EAAnE,OAAO,6BAA6B,EAAE,cAAc;IACjC,IAAI;IACJ,MAAM;;YACb,OAAO,6BAA6B,EAAE,cAAc;aAAW,OAAO,2BAA2B,EAAE,eAAe;EAKxI"}

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

@@ -1,7 +1,7 @@
 import { compile_particle_effect } from "../graph/compile_particle_graph.js";
 
 /**
- * Compile a particle effect: a per-particle attribute {@link ../layout/ParticleLayout.js} plus SPAWN
+ * Compile a particle effect: a per-particle attribute {@link ../layout/ParticleLayout.js} plus INIT
  * and UPDATE node graphs, lowered to VM bytecode.
  *
  * The returned value bundles the layout with the compiled program so the {@link ./EmitterRegistry.js}
@@ -9,11 +9,11 @@ import { compile_particle_effect } from "../graph/compile_particle_graph.js";
  *
  * @param {object} params
  * @param {import("../layout/ParticleLayout.js").ParticleLayout} params.layout
- * @param {NodeGraph} [params.spawn]
+ * @param {NodeGraph} [params.init]
  * @param {NodeGraph} [params.update]
  * @returns {{ layout: import("../layout/ParticleLayout.js").ParticleLayout, program: import("../isa/ParticleProgram.js").ParticleProgram }}
  */
-export function create_particle_effect({ layout, spawn, update }) {
-    const program = compile_particle_effect({ spawn, update, layout });
+export function create_particle_effect({ layout, init, update }) {
+    const program = compile_particle_effect({ init, update, layout });
     return { layout, program };
 }

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

@@ -0,0 +1,15 @@
+/**
+ * The emitter table as the `array<u32>` a shader binds, built on the CPU.
+ *
+ * For the WGSL emulator: on a device the rows get there through the database's upload dispatch, and
+ * the software device records dispatches without running them, so a spec that wants to run
+ * `shader_particle_emit` (or simulate, or sort, or the bucket histogram) over real emitters has no
+ * other way to hand it their bytes. See
+ * {@link ../../buffer/table/gpu_database_emulator_image.js}.
+ *
+ * @param {Iterable<import("./Emitter.js").Emitter>} emitters registered emitters — each one's
+ *        {@link Emitter#id} is the row it lands on, so the layout matches what the shaders index
+ * @returns {Uint32Array}
+ */
+export function emitter_database_image(emitters: Iterable<import("./Emitter.js").Emitter>): Uint32Array;
+//# sourceMappingURL=emitter_database_image.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"emitter_database_image.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/emitter_database_image.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AACH,iDAJW,SAAS,OAAO,cAAc,EAAE,OAAO,CAAC,GAEtC,WAAW,CAMvB"}

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

@@ -0,0 +1,17 @@
+/**
+ * What one particle fragment contributes to AVBOIT's four accumulators.
+ *
+ * The whole of the particle draw's decision, taken apart from the sampling that feeds it: which
+ * accumulator a fragment belongs in, and with what weight. Lifted out of the fragment stage so it
+ * can be run on the WGSL emulator against plain numbers — a fragment that samples an atlas, a depth
+ * buffer, an integral texture and a froxel volume cannot be.
+ *
+ * The inputs are the shaded, *un*premultiplied colour and its emitter's blend mode; the
+ * transmittance the voxel volume leaves in front of this fragment, per channel; and
+ * `sample_volumetrics` at this fragment, `.xyz` in-scatter and `.w` transmittance.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_avboit_contribution: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_particle_avboit_contribution.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_particle_avboit_contribution.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_avboit_contribution.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AACH,iDAFU,SAAS,CA0Dc;0BA1EP,oCAAoC"}

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

@@ -0,0 +1,75 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { OIT_COVERAGE_MAX } from "../../rasterize/native/oit/OIT_CONSTANTS.js";
+import { chunk_particle_render_math } from "./chunk_particle_render_math.js";
+
+/**
+ * What one particle fragment contributes to AVBOIT's four accumulators.
+ *
+ * The whole of the particle draw's decision, taken apart from the sampling that feeds it: which
+ * accumulator a fragment belongs in, and with what weight. Lifted out of the fragment stage so it
+ * can be run on the WGSL emulator against plain numbers — a fragment that samples an atlas, a depth
+ * buffer, an integral texture and a froxel volume cannot be.
+ *
+ * The inputs are the shaded, *un*premultiplied colour and its emitter's blend mode; the
+ * transmittance the voxel volume leaves in front of this fragment, per channel; and
+ * `sample_volumetrics` at this fragment, `.xyz` in-scatter and `.w` transmittance.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_avboit_contribution = CodeChunk.from(/* language=wgsl */ `
+struct ParticleAVBOITContribution {
+    color : vec4<f32>,
+    norm : vec4<f32>,
+    extinction : vec4<f32>,
+    emission : vec4<f32>,
+}
+
+fn particle_avboit_contribution(
+    shaded : vec4<f32>,
+    blend : u32,
+    transmittance : vec3<f32>,
+    fog : vec4<f32>
+) -> ParticleAVBOITContribution {
+    var out : ParticleAVBOITContribution;
+
+    let premultiplied = particle_premultiply(shaded, blend);
+
+    /*
+     Full opacity would be zero transmittance, whose logarithm breaks the accumulators; below zero
+     it would be a negative extinction, and the resolve's exp(-sum) would brighten what is behind
+     the fragment instead of dimming it.
+    */
+    let coverage = clamp(premultiplied.a, 0.0, ${OIT_COVERAGE_MAX});
+
+    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.
+        */
+        out.color = vec4<f32>(0.0);
+        out.norm = vec4<f32>(0.0);
+        out.extinction = vec4<f32>(0.0);
+        out.emission = vec4<f32>(max(premultiplied.rgb * fog.w * transmittance, vec3<f32>(0.0)), 0.0);
+        return out;
+    }
+
+    // the ceiling is on the pair, so the colour is rescaled with the coverage it is weighted by
+    let scale = coverage / premultiplied.a;
+
+    // this one does hide part of the scene, so it owes that part its in-scatter back — and the
+    // resolve's normalization is what keeps the sum to one copy however many fragments there are
+    let color = premultiplied.rgb * scale * fog.w + fog.xyz * coverage;
+
+    let self_transmittance = vec3<f32>(1.0 - coverage);
+
+    out.color = vec4<f32>(color * transmittance, 0.0);
+    out.norm = vec4<f32>((1.0 - self_transmittance) * transmittance, 0.0);
+    out.extinction = vec4<f32>(-log(self_transmittance), 0.0);
+    out.emission = vec4<f32>(0.0);
+
+    return out;
+}
+`, [chunk_particle_render_math]);

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

@@ -0,0 +1,20 @@
+/**
+ * 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 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.
+ *
+ * `view_depth` is the vertex's own view-space depth, interpolated across the quad — the depth the
+ * AVBOIT passes place the fragment at.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_billboard_vertex: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_particle_billboard_vertex.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,94 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { PARTICLE_RECORD_HEADER_EMITTER, PARTICLE_RECORD_WORD_COUNT } from "../ParticleConstants.js";
+import { EMITTER_ATTRIBUTE_ABSENT } from "../data/PARTICLE_EMITTER_STRUCT.js";
+import { chunk_particle_emitter } from "../data/chunk_particle_emitter.js";
+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 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.
+ *
+ * `view_depth` is the vertex's own view-space depth, interpolated across the quad — the depth the
+ * AVBOIT passes place the fragment at.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_billboard_vertex = CodeChunk.from(
+    /* language=wgsl */ `
+const PARTICLE_RECORD_WORDS : u32 = ${PARTICLE_RECORD_WORD_COUNT}u;
+const PARTICLE_HEADER_EMITTER : u32 = ${PARTICLE_RECORD_HEADER_EMITTER}u;
+const PARTICLE_ATTRIBUTE_ABSENT : u32 = ${EMITTER_ATTRIBUTE_ABSENT}u;
+
+struct ParticleVertexOut {
+    @builtin(position) clip : vec4<f32>,
+    @location(0) uv : vec2<f32>,
+    @location(1) color : vec4<f32>,
+    @location(2) world_position : vec3<f32>,
+    @location(3) normal : vec3<f32>,
+    @location(4) view_depth : f32,
+    @location(5) @interpolate(flat) flags : u32,
+    @location(6) @interpolate(flat) blend : u32,
+}
+
+fn particle_read_vec(base : u32, offset : u32, count : u32) -> vec4<f32> {
+    var v = vec4<f32>(0.0);
+    if (count > 0u) { v.x = bitcast<f32>(pool[base + offset]); }
+    if (count > 1u) { v.y = bitcast<f32>(pool[base + offset + 1u]); }
+    if (count > 2u) { v.z = bitcast<f32>(pool[base + offset + 2u]); }
+    if (count > 3u) { v.w = bitcast<f32>(pool[base + offset + 3u]); }
+    return v;
+}
+
+fn particle_billboard_vertex(vi : u32, ii : u32) -> ParticleVertexOut {
+    var corners = array<vec2<f32>, 6>(
+        vec2<f32>(-1.0, -1.0), vec2<f32>(1.0, -1.0), vec2<f32>(1.0, 1.0),
+        vec2<f32>(-1.0, -1.0), vec2<f32>(1.0, 1.0), vec2<f32>(-1.0, 1.0),
+    );
+    let corner = corners[vi];
+
+    let slot = draw_list[ii];
+    let base = slot * PARTICLE_RECORD_WORDS;
+    let emitter_index = particle_header_emitter(pool[base + PARTICLE_HEADER_EMITTER]);
+    let em = particle_emitter_read(&emitter_database, emitter_index);
+
+    var world_center = vec3<f32>(0.0);
+    if (em.render_position != PARTICLE_ATTRIBUTE_ABSENT) { world_center = particle_read_vec(base, em.render_position, 3u).xyz; }
+    var size = 1.0;
+    if (em.render_size != PARTICLE_ATTRIBUTE_ABSENT) { size = bitcast<f32>(pool[base + em.render_size]); }
+    var color = vec4<f32>(1.0);
+    if (em.render_color != PARTICLE_ATTRIBUTE_ABSENT) { color = particle_read_vec(base, em.render_color, 4u); }
+    var rotation = 0.0;
+    if (em.render_rotation != PARTICLE_ATTRIBUTE_ABSENT) { rotation = bitcast<f32>(pool[base + em.render_rotation]); }
+    var frame = 0.0;
+    if (em.render_frame != PARTICLE_ATTRIBUTE_ABSENT) { frame = bitcast<f32>(pool[base + em.render_frame]); }
+    var velocity = vec3<f32>(0.0);
+    if (em.render_velocity != PARTICLE_ATTRIBUTE_ABSENT) { velocity = particle_read_vec(base, em.render_velocity, 3u).xyz; }
+
+    let cam_right = camera.transform[0].xyz;
+    let cam_up = camera.transform[1].xyz;
+    let cam_forward = -camera.transform[2].xyz;
+
+    let offset = particle_billboard_offset(corner, size, rotation, cam_right, cam_up, cam_forward, velocity, particle_emitter_projection(em.flags));
+    let world = world_center + offset;
+
+    var out : ParticleVertexOut;
+    out.clip = camera.view_projection_matrix * vec4<f32>(world, 1.0);
+    out.uv = particle_atlas_uv(corner * 0.5 + vec2<f32>(0.5), em.atlas_region, em.flipbook, frame);
+    out.color = color;
+    out.world_position = world;
+    out.normal = -cam_forward;
+    out.view_depth = -(camera.view_matrix * vec4<f32>(world, 1.0)).z;
+    out.flags = em.flags;
+    out.blend = particle_emitter_blend(em.flags);
+    return out;
+}
+`, [chunk_particle_emitter, chunk_particle_header, chunk_particle_render_math]);

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

@@ -1,11 +1,21 @@
 /**
  * Populates the VM's builtin context and seeds its RNG for one particle before a program section
- * runs. Emitter world position / direction / up are derived from the emitter transform, so an
- * emitter attached to a bone (whose transform is resolved from the scene graph each frame) spawns
- * and simulates in the right place automatically.
+ * runs.
  *
- * Depends on {@link chunk_particle_vm} (owns `vm_ctx` / `vm_rng_state`) and
- * {@link chunk_particle_emitter} (the `ParticleEmitter` struct).
+ * The emitter's world position / direction / up come from its scene node — the `global` of its row
+ * in the scene database's `transforms` table, which the GPU hierarchy pass composed this frame from
+ * the node's own transform and its parents'. An emitter parented to an animated joint therefore
+ * spawns and simulates where the joint is *now*, with nothing copied through the CPU: the joint's
+ * pose was written by the animation passes and composed by the hierarchy pass, and this reads the
+ * result. The caller fetches the node with `scene_read_node(&scene_database, em.node)`.
+ *
+ * The emitter's age is the tick pass's running total, read off the `emitter_state` table of the
+ * same database the emitter record came from ({@link ../data/PARTICLE_EMITTER_STATE.js}) — one
+ * binding for both, through the table's single-field reader.
+ *
+ * Depends on {@link chunk_particle_vm} (owns `vm_ctx` / `vm_rng_state`),
+ * {@link chunk_particle_emitter} (the `ParticleEmitter` struct) and
+ * {@link chunk_scene_database_access} (the node struct + reader).
  *
  * @type {CodeChunk}
  */

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

@@ -1 +1 @@
-{"version":3,"file":"chunk_particle_context.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_context.js"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AACH,qCAFU,SAAS,CAiC6B;AAEhD;;;;;;GAMG;AACH,4CAFU,SAAS,CAIhB;0BAzDuB,oCAAoC"}
+{"version":3,"file":"chunk_particle_context.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_context.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qCAFU,SAAS,CA8ChB;AAEH;;;;;;GAMG;AACH,4CAFU,SAAS,CAIhB;0BAnFuB,oCAAoC"}

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

@@ -10,8 +10,7 @@
  *
  * The simulate shader that includes this chunk must also bind `particle_curve_database :
  * array<u32>` to `GPUAnimationManager.database.buffer` (in place of the no-op
- * {@link ./chunk_particle_context.js#chunk_particle_curve_disabled} provider used when no effect
- * uses curves).
+ * {@link ./chunk_particle_curve_disabled.js} provider used when no effect uses curves).
  *
  * @type {CodeChunk}
  */

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

@@ -1 +1 @@
-{"version":3,"file":"chunk_particle_curve_animation.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_curve_animation.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;GAgBG;AACH,6CAFU,SAAS,CAS0C;0BA5BnC,oCAAoC"}
+{"version":3,"file":"chunk_particle_curve_animation.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_curve_animation.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;GAeG;AACH,6CAFU,SAAS,CAS0C;0BA3BnC,oCAAoC"}

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

@@ -16,8 +16,7 @@ const CURVE_TABLE = ANIMATION_DATABASE_SPEC.get("animation_curves");
  *
  * The simulate shader that includes this chunk must also bind `particle_curve_database :
  * array<u32>` to `GPUAnimationManager.database.buffer` (in place of the no-op
- * {@link ./chunk_particle_context.js#chunk_particle_curve_disabled} provider used when no effect
- * uses curves).
+ * {@link ./chunk_particle_curve_disabled.js} provider used when no effect uses curves).
  *
  * @type {CodeChunk}
  */

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

@@ -0,0 +1,11 @@
+/**
+ * Default curve provider: no curves bound, `CURVE` opcodes evaluate to 0. The production feature
+ * swaps this for an animation-database-backed provider
+ * ({@link ./chunk_particle_curve_animation.js}). Kept separate so an effect that uses no curves
+ * compiles without any animation bindings.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_curve_disabled: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_particle_curve_disabled.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_particle_curve_disabled.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_curve_disabled.js"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,4CAFU,SAAS,CAIhB;0BAZuB,oCAAoC"}

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

@@ -0,0 +1,13 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+
+/**
+ * Default curve provider: no curves bound, `CURVE` opcodes evaluate to 0. The production feature
+ * swaps this for an animation-database-backed provider
+ * ({@link ./chunk_particle_curve_animation.js}). Kept separate so an effect that uses no curves
+ * compiles without any animation bindings.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_curve_disabled = CodeChunk.from(/* wgsl */ `
+fn particle_vm_sample_curve(handle : u32, t : f32) -> f32 { return 0.0; }
+`);

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

@@ -0,0 +1,17 @@
+/**
+ * The emitter's age, as the tick pass left it this frame.
+ *
+ * It is the tick pass's running total, read off the `emitter_state` table of the same database the
+ * emitter record came from ({@link ../data/PARTICLE_EMITTER_STATE.js}) — one binding for both,
+ * through the table's single-field reader, so there is no second copy of the row layout here to
+ * drift from the table's.
+ *
+ * Kept apart from {@link ./chunk_particle_setup_context.js} because the context setup takes the age
+ * as a value: a caller that already has it (or that has no emitter-state binding at all) pulls in
+ * the setup without pulling in this table read.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_emitter_age: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_particle_emitter_age.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_particle_emitter_age.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_emitter_age.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;GAaG;AACH,yCAFU,SAAS,CAM6C;0BArBtC,oCAAoC"}

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

@@ -0,0 +1,22 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { PARTICLE_EMITTER_STATE_DESCRIPTOR } from "../data/PARTICLE_DATABASE_SPEC.js";
+
+/**
+ * The emitter's age, as the tick pass left it this frame.
+ *
+ * It is the tick pass's running total, read off the `emitter_state` table of the same database the
+ * emitter record came from ({@link ../data/PARTICLE_EMITTER_STATE.js}) — one binding for both,
+ * through the table's single-field reader, so there is no second copy of the row layout here to
+ * drift from the table's.
+ *
+ * Kept apart from {@link ./chunk_particle_setup_context.js} because the context setup takes the age
+ * as a value: a caller that already has it (or that has no emitter-state binding at all) pulls in
+ * the setup without pulling in this table read.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_emitter_age = CodeChunk.from(/* wgsl */ `
+fn particle_emitter_age(database : ptr<storage, array<u32>>, emitter_row : u32) -> f32 {
+    return ${PARTICLE_EMITTER_STATE_DESCRIPTOR.marshalling_method_read_field('age')}(database, emitter_row);
+}
+`, [PARTICLE_EMITTER_STATE_DESCRIPTOR.chunk_read_field('age')]);

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

@@ -0,0 +1,14 @@
+/**
+ * An emitter's bounds sphere in world space: the centre through the node's matrix, the radius
+ * scaled by the largest axis scale the matrix carries.
+ *
+ * The axes are read as transformed unit vectors rather than as matrix columns — the same numbers,
+ * in a form the WGSL emulator also evaluates. Shared by the tick pass (frustum culling of spawning)
+ * and the AVBOIT occupancy pass (which depth slices the emitter's particles can reach), so both
+ * test the same sphere.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_emitter_world_sphere: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_particle_emitter_world_sphere.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_particle_emitter_world_sphere.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_emitter_world_sphere.js"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,kDAFU,SAAS,CAUU;0BAtBH,oCAAoC"}

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

@@ -0,0 +1,23 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_particle_emitter } from "../data/chunk_particle_emitter.js";
+
+/**
+ * An emitter's bounds sphere in world space: the centre through the node's matrix, the radius
+ * scaled by the largest axis scale the matrix carries.
+ *
+ * The axes are read as transformed unit vectors rather than as matrix columns — the same numbers,
+ * in a form the WGSL emulator also evaluates. Shared by the tick pass (frustum culling of spawning)
+ * and the AVBOIT occupancy pass (which depth slices the emitter's particles can reach), so both
+ * test the same sphere.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_emitter_world_sphere = CodeChunk.from(/* language=wgsl */ `
+fn particle_emitter_world_sphere(em : ParticleEmitter, transform : mat4x4<f32>) -> vec4<f32> {
+    let center = (transform * vec4<f32>(em.bounds_center, 1.0)).xyz;
+    let sx = length((transform * vec4<f32>(1.0, 0.0, 0.0, 0.0)).xyz);
+    let sy = length((transform * vec4<f32>(0.0, 1.0, 0.0, 0.0)).xyz);
+    let sz = length((transform * vec4<f32>(0.0, 0.0, 1.0, 0.0)).xyz);
+    return vec4<f32>(center, em.bounds_radius * max(sx, max(sy, sz)));
+}
+`, [chunk_particle_emitter]);

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

@@ -1,5 +1,5 @@
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
-import { EMITTER_BLEND, EMITTER_PROJECTION } from "../data/PARTICLE_EMITTER_LAYOUT.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