@woosh/meep-engine 3.15.0 → 3.17.0

package/src/shade/renderer/particles/data/PARTICLE_EMITTER_STRUCT.js

@@ -0,0 +1,167 @@
+import { f32, u32, vec2f, vec3f, vec4f } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+
+/**
+ * One emitter's GPU record: which compiled program it runs and where that program's code and
+ * constants sit in the {@link ../runtime/ProgramArena.js} buffers, plus the instance parameters the
+ * tick / emit / simulate / sort / render passes read — the scene node it hangs off, spawn rate,
+ * feature flags, bounds sphere, render-attribute bindings, atlas region and flipbook grid.
+ *
+ * There is no transform here. An emitter is a scene node, and its world matrix is the `global` of
+ * its row in the scene database's `transforms` table, composed on the GPU by the hierarchy pass
+ * from whatever the node is parented to. The passes that need it read it through `node`.
+ *
+ * Nor is there any per-frame state: what the GPU integrates for an emitter (spawn accumulator, age,
+ * sleep) lives in {@link ./PARTICLE_EMITTER_STATE.js}, keyed by the same row, for the reason given
+ * there.
+ *
+ * It lives in a `GPUDatabase` table (see {@link ./PARTICLE_DATABASE_SPEC.js}), so the layout below
+ * is the *only* description of it that exists: the JS writer is
+ * {@link ../../shader/type/serde/write_gpu_typed_buffer.js} and the WGSL reader is generated from
+ * this same struct by the table descriptor. Nothing hand-packs an emitter word by word any more,
+ * and there is no second copy of the offsets to keep in step.
+ *
+ * `.pack()` reorders the fields to close the padding a declaration-order layout would leave; WGSL
+ * field names are what shaders address, never offsets, so the reordering is invisible to them.
+ *
+ * @type {WebGPUStruct}
+ */
+export const PARTICLE_EMITTER_STRUCT = WebGPUStruct.from({
+    /** first instruction of the INIT program, in instruction units */
+    init_offset: u32,
+    /** INIT instruction count */
+    init_count: u32,
+    /** first instruction of the UPDATE program, in instruction units */
+    update_offset: u32,
+    /** UPDATE instruction count */
+    update_count: u32,
+    /** base into the shared constant pool, in vec4 units */
+    constant_offset: u32,
+    /** base RNG seed */
+    seed: u32,
+    /** see {@link EMITTER_FLAG} */
+    flags: u32,
+    /** continuous emission rate, particles/second, integrated on the GPU by the tick pass */
+    spawn_rate: f32,
+
+    /**
+     * Row of the scene database's `transforms` table this emitter is — its world matrix is that
+     * row's `global`.
+     */
+    node: u32,
+
+    /**
+     * Which tenancy of this row the record describes. Bumped every time the row is handed to a new
+     * emitter, never zero for a live row. Every particle carries the generation of the emitter that
+     * spawned it, and the simulate pass kills one whose generation no longer matches its row's —
+     * see {@link ./particle_header.js}.
+     */
+    generation: u32,
+
+    /** local-space bounding sphere centre */
+    bounds_center: vec3f,
+    /** bounding sphere radius */
+    bounds_radius: f32,
+
+    /** attribute word offset of world position (or {@link EMITTER_ATTRIBUTE_ABSENT}) */
+    render_position: u32,
+    /** attribute word offset of size */
+    render_size: u32,
+    /** attribute word offset of rgba colour */
+    render_color: u32,
+    /** attribute word offset of roll angle, radians */
+    render_rotation: u32,
+    /** attribute word offset of flipbook frame index */
+    render_frame: u32,
+    /** attribute word offset of velocity (STRETCHED projection) */
+    render_velocity: u32,
+
+    /** uv offset .xy + uv scale .zw */
+    atlas_region: vec4f,
+    /** flipbook grid: columns, rows */
+    flipbook: vec2f,
+
+    /**
+     * Id of the compiled program this emitter runs, assigned by {@link ../runtime/ProgramHeap.js}.
+     * Emitters sharing a program share an id.
+     *
+     * The simulation-order bucketing (`coherence/`) histograms on this: it needs a small integer to
+     * index a bin with, which neither the emitter id (one bucket per emitter, even when they run the
+     * same code) nor `update_offset` (a heap offset, arbitrarily large and sparse) gives it. Ids are
+     * reused as effects come and go, so they stay below the set's peak program count rather than
+     * climbing with churn.
+     */
+    program_id: u32,
+}, "ParticleEmitter").pack();
+
+/** Sentinel for an absent render-attribute binding. */
+export const EMITTER_ATTRIBUTE_ABSENT = 0xffffffff;
+
+/**
+ * Emitter flag bits. Blend mode occupies bits [4,6), projection mode bits [6,9).
+ */
+export const EMITTER_FLAG = Object.freeze({
+    LIGHTING: 1 << 0,      // forward-shade billboards with scene lighting
+    SOFT_DEPTH: 1 << 1,    // fade against scene depth
+    SORT: 1 << 2,          // depth-sort this emitter's particles for correct transparency
+    CULL: 1 << 3,          // frustum + occlusion simulation culling (sleep when culled)
+});
+
+/** Blend modes (stored in flag bits [4,6)). All expressed by one premultiplied blend pipeline. */
+export const EMITTER_BLEND = Object.freeze({
+    ALPHA: 0,      // premultiplied alpha (normal transparency)
+    ADDITIVE: 1,   // additive (emissive glow)
+    PREMULTIPLIED: 2, // colour already premultiplied by alpha upstream
+});
+
+const BLEND_SHIFT = 4;
+const BLEND_MASK = 0b11 << BLEND_SHIFT;
+
+/** Projection / orientation modes (stored in flag bits [6,9)). */
+export const EMITTER_PROJECTION = Object.freeze({
+    BILLBOARD: 0,          // face the camera
+    STRETCHED: 1,          // billboard stretched along velocity
+    HORIZONTAL: 2,         // lie flat on the ground plane (XZ)
+    VERTICAL: 3,           // axis-locked to world up, yaw toward camera
+    FACING_WORLD: 4,       // oriented by the particle's own rotation attribute in world space
+});
+
+const PROJECTION_SHIFT = 6;
+const PROJECTION_MASK = 0b111 << PROJECTION_SHIFT;
+
+/**
+ * Compose the flags word from feature toggles + blend + projection.
+ * @param {object} options
+ * @param {boolean} [options.lighting]
+ * @param {boolean} [options.soft_depth]
+ * @param {boolean} [options.sort]
+ * @param {boolean} [options.cull]
+ * @param {number} [options.blend] see {@link EMITTER_BLEND}
+ * @param {number} [options.projection] see {@link EMITTER_PROJECTION}
+ * @returns {number}
+ */
+export function make_emitter_flags({ lighting = false, soft_depth = false, sort = false, cull = false, blend = EMITTER_BLEND.ALPHA, projection = EMITTER_PROJECTION.BILLBOARD } = {}) {
+    let flags = 0;
+    if (lighting) flags |= EMITTER_FLAG.LIGHTING;
+    if (soft_depth) flags |= EMITTER_FLAG.SOFT_DEPTH;
+    if (sort) flags |= EMITTER_FLAG.SORT;
+    if (cull) flags |= EMITTER_FLAG.CULL;
+    flags |= (blend << BLEND_SHIFT) & BLEND_MASK;
+    flags |= (projection << PROJECTION_SHIFT) & PROJECTION_MASK;
+    return flags >>> 0;
+}
+
+/** @param {number} flags @returns {number} the blend mode */
+export function emitter_flags_blend(flags) {
+    return (flags & BLEND_MASK) >>> BLEND_SHIFT;
+}
+
+/** @param {number} flags @returns {number} the projection mode */
+export function emitter_flags_projection(flags) {
+    return (flags & PROJECTION_MASK) >>> PROJECTION_SHIFT;
+}
+
+/** Shift/mask constants exposed for the WGSL reader to interpolate. */
+export const EMITTER_FLAG_ENCODING = Object.freeze({
+    BLEND_SHIFT, BLEND_MASK, PROJECTION_SHIFT, PROJECTION_MASK,
+});

package/src/shade/renderer/particles/data/chunk_particle_emitter.d.ts

@@ -1,13 +1,29 @@
 /**
- * WGSL reader for emitter records stored in an `array<u32>` (see
- * {@link ./PARTICLE_EMITTER_LAYOUT.js}). `particle_emitter_read` decodes one record into a value-type
- * `ParticleEmitter` struct; helpers extract the blend and projection sub-fields from `flags`.
+ * WGSL access to emitter records.
  *
- * Reading via explicit indexing (rather than an `array<Struct>` binding) keeps every consuming shader
- * reliable under the WGSL emulator.
+ * The reader itself is not written here: emitters live in a `GPUDatabase` table, so the
+ * `ParticleEmitter` struct declaration and the function that decodes one row of it are both
+ * generated from {@link ./PARTICLE_EMITTER_STRUCT.js} by the table descriptor. Pulling this chunk in
+ * brings them along; call {@link particle_emitter_read} with the database binding and a row id.
+ * There is no second, hand-maintained copy of the layout for them to disagree with.
+ *
+ * What is written here is the part the struct cannot express: `flags` packs four feature bits, a
+ * two-bit blend mode and a three-bit projection mode into one word, and these two helpers are the
+ * shift/mask pair that gets the sub-fields back out.
  *
  * @type {CodeChunk}
  */
 export const chunk_particle_emitter: CodeChunk;
+/**
+ * Reader for just the emitter's `program_id` — the simulation-order bucket key.
+ *
+ * Split out from {@link chunk_particle_emitter} because the histogram pass that wants it runs once
+ * per live PARTICLE, and decoding a whole emitter record (transform matrix included) to reach one
+ * word would be pure waste at that rate. Call
+ * {@link PARTICLE_EMITTER_DESCRIPTOR#marshalling_method_read_field}`('program_id')`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_emitter_program_id: CodeChunk;
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 //# sourceMappingURL=chunk_particle_emitter.d.ts.map

package/src/shade/renderer/particles/data/chunk_particle_emitter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_particle_emitter.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/chunk_particle_emitter.js"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AACH,qCAFU,SAAS,CAuEhB;0BApFuB,oCAAoC"}
+{"version":3,"file":"chunk_particle_emitter.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/chunk_particle_emitter.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AACH,qCAFU,SAAS,CAc0B;AAE7C;;;;;;;;;GASG;AACH,gDAFU,SAAS,CAEyF;0BA3ClF,oCAAoC"}

package/src/shade/renderer/particles/data/chunk_particle_emitter.js

@@ -1,85 +1,44 @@
-import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
-import { EMITTER_FIELD, EMITTER_FLAG_ENCODING, EMITTER_STRIDE } from "./PARTICLE_EMITTER_LAYOUT.js";
-
-const F = EMITTER_FIELD;
-
-/**
- * WGSL reader for emitter records stored in an `array<u32>` (see
- * {@link ./PARTICLE_EMITTER_LAYOUT.js}). `particle_emitter_read` decodes one record into a value-type
- * `ParticleEmitter` struct; helpers extract the blend and projection sub-fields from `flags`.
- *
- * Reading via explicit indexing (rather than an `array<Struct>` binding) keeps every consuming shader
- * reliable under the WGSL emulator.
- *
- * @type {CodeChunk}
- */
-export const chunk_particle_emitter = CodeChunk.from(/* language=wgsl */ `
-const PARTICLE_EMITTER_STRIDE : u32 = ${EMITTER_STRIDE}u;
-const EMITTER_BLEND_SHIFT : u32 = ${EMITTER_FLAG_ENCODING.BLEND_SHIFT}u;
-const EMITTER_BLEND_MASK : u32 = ${EMITTER_FLAG_ENCODING.BLEND_MASK}u;
-const EMITTER_PROJECTION_SHIFT : u32 = ${EMITTER_FLAG_ENCODING.PROJECTION_SHIFT}u;
-const EMITTER_PROJECTION_MASK : u32 = ${EMITTER_FLAG_ENCODING.PROJECTION_MASK}u;
-
-struct ParticleEmitter {
-    spawn_offset : u32,
-    spawn_count : u32,
-    update_offset : u32,
-    update_count : u32,
-    constant_offset : u32,
-    seed : u32,
-    flags : u32,
-    spawn_rate : f32,
-    transform : mat4x4<f32>,
-    bounds_center : vec3<f32>,
-    bounds_radius : f32,
-    render_position : u32,
-    render_size : u32,
-    render_color : u32,
-    render_rotation : u32,
-    render_frame : u32,
-    render_velocity : u32,
-    atlas_region : vec4<f32>,
-    flipbook : vec2<f32>,
-    program_id : u32,
-}
-
-fn particle_emitter_read(e : ptr<storage, array<u32>, read>, index : u32) -> ParticleEmitter {
-    let b = index * PARTICLE_EMITTER_STRIDE;
-    var r : ParticleEmitter;
-    r.spawn_offset = (*e)[b + ${F.SPAWN_OFFSET}u];
-    r.spawn_count = (*e)[b + ${F.SPAWN_COUNT}u];
-    r.update_offset = (*e)[b + ${F.UPDATE_OFFSET}u];
-    r.update_count = (*e)[b + ${F.UPDATE_COUNT}u];
-    r.constant_offset = (*e)[b + ${F.CONSTANT_OFFSET}u];
-    r.seed = (*e)[b + ${F.SEED}u];
-    r.flags = (*e)[b + ${F.FLAGS}u];
-    r.spawn_rate = bitcast<f32>((*e)[b + ${F.SPAWN_RATE}u]);
-
-    let t = b + ${F.TRANSFORM}u;
-    r.transform = mat4x4<f32>(
-        vec4<f32>(bitcast<f32>((*e)[t + 0u]), bitcast<f32>((*e)[t + 1u]), bitcast<f32>((*e)[t + 2u]), bitcast<f32>((*e)[t + 3u])),
-        vec4<f32>(bitcast<f32>((*e)[t + 4u]), bitcast<f32>((*e)[t + 5u]), bitcast<f32>((*e)[t + 6u]), bitcast<f32>((*e)[t + 7u])),
-        vec4<f32>(bitcast<f32>((*e)[t + 8u]), bitcast<f32>((*e)[t + 9u]), bitcast<f32>((*e)[t + 10u]), bitcast<f32>((*e)[t + 11u])),
-        vec4<f32>(bitcast<f32>((*e)[t + 12u]), bitcast<f32>((*e)[t + 13u]), bitcast<f32>((*e)[t + 14u]), bitcast<f32>((*e)[t + 15u])),
-    );
-
-    r.bounds_center = vec3<f32>(bitcast<f32>((*e)[b + ${F.BOUNDS_CENTER}u]), bitcast<f32>((*e)[b + ${F.BOUNDS_CENTER + 1}u]), bitcast<f32>((*e)[b + ${F.BOUNDS_CENTER + 2}u]));
-    r.bounds_radius = bitcast<f32>((*e)[b + ${F.BOUNDS_RADIUS}u]);
-
-    r.render_position = (*e)[b + ${F.RENDER_POSITION}u];
-    r.render_size = (*e)[b + ${F.RENDER_SIZE}u];
-    r.render_color = (*e)[b + ${F.RENDER_COLOR}u];
-    r.render_rotation = (*e)[b + ${F.RENDER_ROTATION}u];
-    r.render_frame = (*e)[b + ${F.RENDER_FRAME}u];
-    r.render_velocity = (*e)[b + ${F.RENDER_VELOCITY}u];
-
-    r.atlas_region = vec4<f32>(bitcast<f32>((*e)[b + ${F.ATLAS_REGION}u]), bitcast<f32>((*e)[b + ${F.ATLAS_REGION + 1}u]), bitcast<f32>((*e)[b + ${F.ATLAS_REGION + 2}u]), bitcast<f32>((*e)[b + ${F.ATLAS_REGION + 3}u]));
-    r.flipbook = vec2<f32>(bitcast<f32>((*e)[b + ${F.FLIPBOOK}u]), bitcast<f32>((*e)[b + ${F.FLIPBOOK + 1}u]));
-
-    r.program_id = (*e)[b + ${F.PROGRAM_ID}u];
-    return r;
-}
-
-fn particle_emitter_blend(flags : u32) -> u32 { return (flags & EMITTER_BLEND_MASK) >> EMITTER_BLEND_SHIFT; }
-fn particle_emitter_projection(flags : u32) -> u32 { return (flags & EMITTER_PROJECTION_MASK) >> EMITTER_PROJECTION_SHIFT; }
-`);
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { PARTICLE_EMITTER_DESCRIPTOR } from "./PARTICLE_DATABASE_SPEC.js";
+import { EMITTER_FLAG_ENCODING } from "./PARTICLE_EMITTER_STRUCT.js";
+
+/**
+ * WGSL access to emitter records.
+ *
+ * The reader itself is not written here: emitters live in a `GPUDatabase` table, so the
+ * `ParticleEmitter` struct declaration and the function that decodes one row of it are both
+ * generated from {@link ./PARTICLE_EMITTER_STRUCT.js} by the table descriptor. Pulling this chunk in
+ * brings them along; call {@link particle_emitter_read} with the database binding and a row id.
+ * There is no second, hand-maintained copy of the layout for them to disagree with.
+ *
+ * What is written here is the part the struct cannot express: `flags` packs four feature bits, a
+ * two-bit blend mode and a three-bit projection mode into one word, and these two helpers are the
+ * shift/mask pair that gets the sub-fields back out.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_emitter = CodeChunk.from(/* language=wgsl */ `
+const EMITTER_BLEND_SHIFT : u32 = ${EMITTER_FLAG_ENCODING.BLEND_SHIFT}u;
+const EMITTER_BLEND_MASK : u32 = ${EMITTER_FLAG_ENCODING.BLEND_MASK}u;
+const EMITTER_PROJECTION_SHIFT : u32 = ${EMITTER_FLAG_ENCODING.PROJECTION_SHIFT}u;
+const EMITTER_PROJECTION_MASK : u32 = ${EMITTER_FLAG_ENCODING.PROJECTION_MASK}u;
+
+fn particle_emitter_read(database : ptr<storage, array<u32>>, index : u32) -> ParticleEmitter {
+    return ${PARTICLE_EMITTER_DESCRIPTOR.marshalling_method_read}(database, index);
+}
+
+fn particle_emitter_blend(flags : u32) -> u32 { return (flags & EMITTER_BLEND_MASK) >> EMITTER_BLEND_SHIFT; }
+fn particle_emitter_projection(flags : u32) -> u32 { return (flags & EMITTER_PROJECTION_MASK) >> EMITTER_PROJECTION_SHIFT; }
+`, [PARTICLE_EMITTER_DESCRIPTOR.chunk_read]);
+
+/**
+ * Reader for just the emitter's `program_id` — the simulation-order bucket key.
+ *
+ * Split out from {@link chunk_particle_emitter} because the histogram pass that wants it runs once
+ * per live PARTICLE, and decoding a whole emitter record (transform matrix included) to reach one
+ * word would be pure waste at that rate. Call
+ * {@link PARTICLE_EMITTER_DESCRIPTOR#marshalling_method_read_field}`('program_id')`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_emitter_program_id = PARTICLE_EMITTER_DESCRIPTOR.chunk_read_field('program_id');

package/src/shade/renderer/particles/data/particle_emitter_record.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The translation between an emitter and the row the GPU reads for it: one function that fills a
+ * {@link ./PARTICLE_EMITTER_STRUCT.js} record from a {@link ../runtime/ParticleEmitter.js} and the
+ * {@link ../runtime/GPUParticleEmitterContext.js} the registry holds for it.
+ *
+ * It sits here, with the struct, rather than on the emitter. Half of what a row says is the
+ * context's — the program placement, the tenancy, the `transforms` row, the atlas patch — and the other
+ * half only means anything in the terms this struct sets: `render_position` is a word offset
+ * because that is what the render pass indexes a particle record with. An emitter that knew how to
+ * write one would be an emitter that knew what a table row is.
+ */
+/**
+ * Fill `record` with an emitter as the value the emitter table stores — every field of
+ * {@link ./PARTICLE_EMITTER_STRUCT.js}, none omitted.
+ *
+ * Omitting one would not write zeros: the serializer skips absent fields, and table pages are
+ * recycled buffers, so a skipped field keeps whatever the previous tenant of the slot left there.
+ *
+ * Writes into a caller-supplied object rather than returning a fresh one so the registry can stage
+ * every row of a frame through one module-static record — the table serializes it synchronously, so
+ * nothing outlives the call.
+ *
+ * @param {object} record the staging object, see {@link create_emitter_record}
+ * @param {import("../runtime/ParticleEmitter.js").ParticleEmitter} emitter
+ * @param {import("../runtime/GPUParticleEmitterContext.js").GPUParticleEmitterContext} context the
+ *        registry's bookkeeping for `emitter`
+ * @returns {object} `record`
+ */
+export function write_emitter_record(record: object, emitter: import("../runtime/ParticleEmitter.js").ParticleEmitter, context: import("../runtime/GPUParticleEmitterContext.js").GPUParticleEmitterContext): object;
+/**
+ * An empty staging record with every field of {@link ./PARTICLE_EMITTER_STRUCT.js} present, typed
+ * arrays for the vector fields so {@link write_emitter_record} can copy into them.
+ *
+ * @returns {object}
+ */
+export function create_emitter_record(): object;
+//# sourceMappingURL=particle_emitter_record.d.ts.map

package/src/shade/renderer/particles/data/particle_emitter_record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"particle_emitter_record.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/particle_emitter_record.js"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,6CANW,MAAM,WACN,OAAO,+BAA+B,EAAE,eAAe,WACvD,OAAO,yCAAyC,EAAE,yBAAyB,GAEzE,MAAM,CA2ClB;AAED;;;;;GAKG;AACH,yCAFa,MAAM,CA8BlB"}

package/src/shade/renderer/particles/data/particle_emitter_record.js

@@ -0,0 +1,109 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * The translation between an emitter and the row the GPU reads for it: one function that fills a
+ * {@link ./PARTICLE_EMITTER_STRUCT.js} record from a {@link ../runtime/ParticleEmitter.js} and the
+ * {@link ../runtime/GPUParticleEmitterContext.js} the registry holds for it.
+ *
+ * It sits here, with the struct, rather than on the emitter. Half of what a row says is the
+ * context's — the program placement, the tenancy, the `transforms` row, the atlas patch — and the other
+ * half only means anything in the terms this struct sets: `render_position` is a word offset
+ * because that is what the render pass indexes a particle record with. An emitter that knew how to
+ * write one would be an emitter that knew what a table row is.
+ */
+
+/**
+ * Fill `record` with an emitter as the value the emitter table stores — every field of
+ * {@link ./PARTICLE_EMITTER_STRUCT.js}, none omitted.
+ *
+ * Omitting one would not write zeros: the serializer skips absent fields, and table pages are
+ * recycled buffers, so a skipped field keeps whatever the previous tenant of the slot left there.
+ *
+ * Writes into a caller-supplied object rather than returning a fresh one so the registry can stage
+ * every row of a frame through one module-static record — the table serializes it synchronously, so
+ * nothing outlives the call.
+ *
+ * @param {object} record the staging object, see {@link create_emitter_record}
+ * @param {import("../runtime/ParticleEmitter.js").ParticleEmitter} emitter
+ * @param {import("../runtime/GPUParticleEmitterContext.js").GPUParticleEmitterContext} context the
+ *        registry's bookkeeping for `emitter`
+ * @returns {object} `record`
+ */
+export function write_emitter_record(record, emitter, context) {
+    assert.defined(record, 'record');
+    assert.defined(emitter, 'emitter');
+    assert.defined(context, 'context');
+    assert.notEqual(context.placement, null, 'context.placement — this emitter has no program in the heap');
+
+    const placement = context.placement;
+
+    record.init_offset = placement.init_offset;
+    record.init_count = placement.init_count;
+    record.update_offset = placement.update_offset;
+    record.update_count = placement.update_count;
+    record.constant_offset = placement.constant_offset;
+    record.program_id = placement.program_id;
+
+    // Two emitters running one program produce identical particles from identical seeds, and 0 is
+    // what an emitter that was never given one has. The generation stands in: it is distinct for
+    // every emitter the registry has ever registered, so "unset" comes out as "unlike anything
+    // else" rather than "the same as its twin". Derived here rather than written back onto the
+    // emitter, which is authoring data and has no seed of its own to gain from being registered.
+    record.seed = emitter.seed !== 0 ? emitter.seed : context.generation;
+
+    record.flags = emitter.flags;
+    record.spawn_rate = emitter.spawn_rate;
+    record.node = context.transform_row;
+    record.generation = context.generation;
+
+    record.bounds_center.set(emitter.bounds_center);
+    record.bounds_radius = emitter.bounds_radius;
+
+    record.render_position = emitter.render_position;
+    record.render_size = emitter.render_size;
+    record.render_color = emitter.render_color;
+    record.render_rotation = emitter.render_rotation;
+    record.render_frame = emitter.render_frame;
+    record.render_velocity = emitter.render_velocity;
+
+    record.atlas_region.set(context.atlas_region);
+    record.flipbook.set(emitter.flipbook);
+
+    return record;
+}
+
+/**
+ * An empty staging record with every field of {@link ./PARTICLE_EMITTER_STRUCT.js} present, typed
+ * arrays for the vector fields so {@link write_emitter_record} can copy into them.
+ *
+ * @returns {object}
+ */
+export function create_emitter_record() {
+    return {
+        init_offset: 0,
+        init_count: 0,
+        update_offset: 0,
+        update_count: 0,
+        constant_offset: 0,
+        program_id: 0,
+
+        seed: 0,
+        flags: 0,
+        spawn_rate: 0,
+        node: 0,
+        generation: 0,
+
+        bounds_center: new Float32Array(3),
+        bounds_radius: 0,
+
+        render_position: 0,
+        render_size: 0,
+        render_color: 0,
+        render_rotation: 0,
+        render_frame: 0,
+        render_velocity: 0,
+
+        atlas_region: new Float32Array(4),
+        flipbook: new Float32Array(2),
+    };
+}

package/src/shade/renderer/particles/data/particle_header.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The generation that follows `generation` when a row is reused — skips zero on wrap.
+ *
+ * @param {number} generation
+ * @returns {number}
+ */
+export function particle_generation_next(generation: number): number;
+/**
+ * @param {number} emitter_row
+ * @param {number} generation
+ * @returns {number} the packed header word
+ */
+export function particle_header_pack(emitter_row: number, generation: number): number;
+/**
+ * @param {number} header
+ * @returns {number} emitter row
+ */
+export function particle_header_emitter(header: number): number;
+/**
+ * @param {number} header
+ * @returns {number} generation
+ */
+export function particle_header_generation(header: number): number;
+/**
+ * Encoding of a particle record's header word: which emitter row the particle belongs to, and the
+ * generation that row had when the particle was born.
+ *
+ * The row alone is not enough. Rows are reused — a removed emitter's row goes to the next emitter
+ * added — and the particles of the removed one are still in flight, carrying that row. Without a
+ * generation they would adopt the newcomer: run its program, follow its node, draw with its atlas.
+ * With one, the simulate pass compares the particle's generation against the row's and kills any
+ * particle whose emitter has gone, within a frame of it going. A freed row is zero-filled by the
+ * table, and a live row's generation is never zero, so the check also covers the window between a
+ * removal and the next add.
+ *
+ * Layout: low 16 bits = emitter row, high 16 bits = generation. Sixteen bits of row is the same
+ * bound the emitter table's page limit implies; sixteen bits of generation wraps after 65535
+ * reuses of one row, which at a removal per frame is eighteen minutes of churn on one row before a
+ * collision is even possible, and the colliding particle would have to have lived that long.
+ *
+ * The WGSL side is {@link chunk_particle_header}; the two must agree, so both read the constants
+ * below.
+ */
+/** @type {number} */
+export const PARTICLE_HEADER_EMITTER_MASK: number;
+/** @type {number} */
+export const PARTICLE_HEADER_GENERATION_SHIFT: number;
+/** @type {number} */
+export const PARTICLE_HEADER_GENERATION_MASK: number;
+/**
+ * The first generation a row is given. Zero is what a freed row reads as, so it is never live.
+ * @type {number}
+ */
+export const PARTICLE_GENERATION_FIRST: number;
+/**
+ * The same encoding, for every pass that reads a record's header word.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_header: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=particle_header.d.ts.map

package/src/shade/renderer/particles/data/particle_header.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"particle_header.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/particle_header.js"],"names":[],"mappings":"AAuCA;;;;;GAKG;AACH,qDAHW,MAAM,GACJ,MAAM,CAMlB;AAED;;;;GAIG;AACH,kDAJW,MAAM,cACN,MAAM,GACJ,MAAM,CASlB;AAED;;;GAGG;AACH,gDAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;GAGG;AACH,mDAHW,MAAM,GACJ,MAAM,CAIlB;AA5ED;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,qBAAqB;AACrB,2CADW,MAAM,CACkC;AAEnD,qBAAqB;AACrB,+CADW,MAAM,CACkC;AAEnD,qBAAqB;AACrB,8CADW,MAAM,CACqC;AAEtD;;;GAGG;AACH,wCAFU,MAAM,CAE2B;AA4C3C;;;;GAIG;AACH,oCAFU,SAAS,CAkBhB;0BArGuB,oCAAoC"}

package/src/shade/renderer/particles/data/particle_header.js

@@ -0,0 +1,103 @@
+import { assert } from "../../../../core/assert.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+
+/**
+ * Encoding of a particle record's header word: which emitter row the particle belongs to, and the
+ * generation that row had when the particle was born.
+ *
+ * The row alone is not enough. Rows are reused — a removed emitter's row goes to the next emitter
+ * added — and the particles of the removed one are still in flight, carrying that row. Without a
+ * generation they would adopt the newcomer: run its program, follow its node, draw with its atlas.
+ * With one, the simulate pass compares the particle's generation against the row's and kills any
+ * particle whose emitter has gone, within a frame of it going. A freed row is zero-filled by the
+ * table, and a live row's generation is never zero, so the check also covers the window between a
+ * removal and the next add.
+ *
+ * Layout: low 16 bits = emitter row, high 16 bits = generation. Sixteen bits of row is the same
+ * bound the emitter table's page limit implies; sixteen bits of generation wraps after 65535
+ * reuses of one row, which at a removal per frame is eighteen minutes of churn on one row before a
+ * collision is even possible, and the colliding particle would have to have lived that long.
+ *
+ * The WGSL side is {@link chunk_particle_header}; the two must agree, so both read the constants
+ * below.
+ */
+
+/** @type {number} */
+export const PARTICLE_HEADER_EMITTER_MASK = 0xFFFF;
+
+/** @type {number} */
+export const PARTICLE_HEADER_GENERATION_SHIFT = 16;
+
+/** @type {number} */
+export const PARTICLE_HEADER_GENERATION_MASK = 0xFFFF;
+
+/**
+ * The first generation a row is given. Zero is what a freed row reads as, so it is never live.
+ * @type {number}
+ */
+export const PARTICLE_GENERATION_FIRST = 1;
+
+/**
+ * The generation that follows `generation` when a row is reused — skips zero on wrap.
+ *
+ * @param {number} generation
+ * @returns {number}
+ */
+export function particle_generation_next(generation) {
+    const next = (generation + 1) & PARTICLE_HEADER_GENERATION_MASK;
+
+    return next === 0 ? PARTICLE_GENERATION_FIRST : next;
+}
+
+/**
+ * @param {number} emitter_row
+ * @param {number} generation
+ * @returns {number} the packed header word
+ */
+export function particle_header_pack(emitter_row, generation) {
+    assert.isNonNegativeInteger(emitter_row, 'emitter_row');
+    assert.lessThanOrEqual(emitter_row, PARTICLE_HEADER_EMITTER_MASK, 'emitter_row');
+    assert.isNonNegativeInteger(generation, 'generation');
+    assert.lessThanOrEqual(generation, PARTICLE_HEADER_GENERATION_MASK, 'generation');
+
+    return ((generation << PARTICLE_HEADER_GENERATION_SHIFT) | emitter_row) >>> 0;
+}
+
+/**
+ * @param {number} header
+ * @returns {number} emitter row
+ */
+export function particle_header_emitter(header) {
+    return header & PARTICLE_HEADER_EMITTER_MASK;
+}
+
+/**
+ * @param {number} header
+ * @returns {number} generation
+ */
+export function particle_header_generation(header) {
+    return (header >>> PARTICLE_HEADER_GENERATION_SHIFT) & PARTICLE_HEADER_GENERATION_MASK;
+}
+
+/**
+ * The same encoding, for every pass that reads a record's header word.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_header = CodeChunk.from(/* language=wgsl */ `
+const PARTICLE_HEADER_EMITTER_MASK : u32 = ${PARTICLE_HEADER_EMITTER_MASK}u;
+const PARTICLE_HEADER_GENERATION_SHIFT : u32 = ${PARTICLE_HEADER_GENERATION_SHIFT}u;
+const PARTICLE_HEADER_GENERATION_MASK : u32 = ${PARTICLE_HEADER_GENERATION_MASK}u;
+
+fn particle_header_pack(emitter_row : u32, generation : u32) -> u32 {
+    return (generation << PARTICLE_HEADER_GENERATION_SHIFT) | (emitter_row & PARTICLE_HEADER_EMITTER_MASK);
+}
+
+fn particle_header_emitter(header : u32) -> u32 {
+    return header & PARTICLE_HEADER_EMITTER_MASK;
+}
+
+fn particle_header_generation(header : u32) -> u32 {
+    return (header >> PARTICLE_HEADER_GENERATION_SHIFT) & PARTICLE_HEADER_GENERATION_MASK;
+}
+`);