@woosh/meep-engine 3.60.4 → 3.60.6

package/src/shade/renderer/particles/DESIGN.md

@@ -1,1011 +0,0 @@
-# GPU-Driven Particle System — Design
-
-A specialized, deeply-integrated, GPU-driven particle engine for the v2 renderer.
-Destiny-style: **one** simulation dispatch runs **all** particles of **all** emitters by
-interpreting a compact per-emitter bytecode program (a shader VM). Effects are authored as
-node graphs and lowered to that bytecode by a testable JS compiler. Emitters run at entities'
-rows, and the decision to spawn is the GPU's.
-
-## Goals (from the brief)
-
-- Single simulation execution shader (data-driven VM, not one-pipeline-per-effect).
-- Projection modes: camera-facing billboard (+ velocity-stretched, axis-locked, world-oriented),
-  each a frame a particle's own orientation (a quaternion) turns the quad inside. See "Orientation".
-- Order-independent transparency: the particles are a side channel of the AVBOIT pipeline, so they
-  composite against the transparent meshes with no depth ordering of any kind.
-- Node-based composition → shader VM (compile graph → bytecode).
-- Frustum culling of spawning (optional, flagged, sleep-when-culled + bounded catch-up).
-- Flipbooks (atlas sub-rect + frame grid).
-- Texture lookup via atlas (region table; mirrors meep `AtlasPatch` uv offset/scale).
-- Soft-depth fade (flagged).
-- `GPUDatabase` for CPU-managed, low-churn tables (emitters).
-- Scene / bone attachment: an emitter stands at an entity with a row; its world matrix is that row
-  of the scene's `transforms` table, composed by the GPU hierarchy pass.
-- Distinct per-particle lifecycle: **no** built-in age/position — the schema + program define state.
-- Lighting per emitter (`EMITTER_FLAG.LIGHTING`): the scene's lights from the froxel irradiance
-  volume the fog pass writes, plus the environment map. See "Lighting" below.
-- Blend modes (alpha + additive) via a **single** premultiplied blend setup.
-- Authored curves and RGB/RGBA gradients compiled into arithmetic for simulation.
-- Spawning decided on the GPU, per emitter, with the CPU able to ask for bursts through the same path.
-- No per-frame allocation on the CPU beyond the frame graph's own records.
-
-## Layered architecture
-
-```
-authoring:   NodeGraph (nodes+ports)      ──compile──▶  Program (bytecode: INIT + UPDATE)
-             standard node library                       │
-                                                         ▼
-runtime CPU: ParticleEmitter (at an entity) ── Scene ──▶ GPUSceneContext (transforms table)
-             EmitterRegistry ── GPUDatabase(emitters + emitter_state + field_bindings) ─┤  ProgramHeap ([header][constants][code][fields])
-             GPUParticleSystem (owns every buffer, records the frame)
-                                                         ▼
-runtime GPU: particle pool (array<u32>, uniform stride) + alive/dead lists + counters
-             emitter state table (GPU-owned: generation, accumulator, age, sleep, pending)
-             ┌─ field bind (per binding row: a bound transform → its field; only while rows exist)
-             ├─ spawn commands (CPU bursts → pending)
-             ├─ emitter tick  (per row: cull on the published box, integrate rate, take budget → count)
-             ├─ scan (csdldf) → emit dispatch
-             ├─ emit  (VM INIT program)   ── per newborn: find emitter in scan, pop dead → init → append alive_new
-             ├─ simulate (VM UPDATE program) ── update → (kill|orphan→dead | keep→alive_new)
-             ├─ bucket (histogram → csdldf scan → scatter)  ── alive → program-coherent sim list
-             ├─ bounds (per particle → per emitter box, published to the state row)
-             └─ build indirect (dispatch + draw args)
-
-             the AVBOIT transparency pipeline then draws the alive list through the side channel:
-             ├─ occupancy (per emitter box → depth slices)
-             ├─ splat     (extinction into the voxel volume)
-             └─ draw      (instanced billboard quads → the four accumulators)
-```
-
-### Vocabulary: fields
-
-State is a set of **fields**, named and laid out by a `ParticleLayout`, one kind per scope:
-`particle_field`s live in a particle's pool record, `emitter_field`s in its emitter's block and
-`global_field`s in the system's shared section. Particle fields were once called attributes, and
-saves under that name still load: graph node types `attribute` and `setAttribute`
-(`PARTICLE_NODE_TYPE_RENAMES`), a document's `attributes` key, and the assembly mnemonics `LOAD_ATTR`
-and `STORE_ATTR`. The binary effect format never wrote the word.
-
-### Emitter fields
-
-The program is a class and an emitter an instance of it. An effect declares **emitter fields** — an
-`emitter_layout`, a `ParticleLayout.emitter` packed from word zero with no fixed size — and every
-emitter of it carries its own values for them (`emitter_fields`, f32 bit patterns). Two emitters of
-one effect that differ only there share one program, one heap placement and one simulation bucket.
-
-- **Storage.** The packed program buffer's fourth section, after the code:
-  `[header][constants][code][fields]`, header word `PARTICLE_PROGRAM_FIELD_BASE_WORD` saying where it
-  starts. The section opens with `PARTICLE_GLOBAL_FIELD_WORDS` reserved for global fields; each
-  emitter's block is an allocation of the same `OffsetAllocator` kind the other sections use, held
-  by its context as a `FieldBlock` and moved in place by a repack, which moves `placement_version`
-  because the record carries the block's offset (`field_offset`). The fields share the program
-  buffer's binding.
-- **Reading.** The engine's builtins are the emitter's members as the engine declares them, and an
-  effect's emitter fields are the members it declares, so they are read through the same
-  instruction: a `LOAD_BUILTIN` id from `VM_BUILTIN_EMITTER_FIELD_BASE` up reads the
-  instruction's width in words from the emitter's block, as `LOAD_CONST` reads the pool.
-  `vm_ctx.emitter_field_offset` is set beside `emitter_position` by `particle_setup_context`,
-  so emit, simulate and the warm-up all have it. The offset is per lane, as the emitter's position
-  is: a simulate wave is one program, not one emitter, so the read is a vector load where
-  `LOAD_CONST`'s is scalar. The plan's Outcome has what that costs.
-- **Writing.** The CPU's: gameplay writes the component's values in place, `apply_particle_effect`
-  finds the change by comparison and copies it to the emitter, and the registry writes the block
-  when it restages the row. The heap tracks the changed span, and `GPUParticleSystem` writes that
-  span into the existing buffer rather than rebuilding it.
-- **Authoring.** `ParticleEffectDocument.emitter_fields` declares them with the value an emitter
-  starts from; the `emitterField` node reads one. `ParticleEffect` serializes them at version 3.
-
-### Global fields
-
-The system's static members, read by every effect by name — `TIME` and `DELTA_TIME` are the
-engine's, a gust strength or the player's position a game's.
-
-- **Layout.** `ParticleGlobalFields`, owned by the heap: the union of what is loaded, append-only,
-  in the `PARTICLE_GLOBAL_FIELD_WORDS` reserved at the start of the field section, so a global field
-  is addressed from zero and never moves. A program placing a name the system does not have
-  declares it, zero-filled; a game may declare names first. A name is one field: a later reader may
-  not want more components than it was declared with.
-- **Refusal.** A program whose imports the layout cannot take is refused before anything is claimed
-  for it (`ParticleGlobalFields.check`): no id, range or declaration is left behind. The registry's
-  flush keeps the emitter on the program it had, with that program's emitter layout — its block,
-  values and bindings, even when the emitter's layout changed along with the refused program — and
-  does not offer the refused one again until it changes; `GPUParticleEmitterSystem` does the same for an effect it cannot register, and for a
-  global value set at a width the layout refuses, so one bad effect never stops the others.
-- **Linking.** A compiled program cannot know a scene's offsets, so it carries `global_imports`
-  (name and width, in the order it first reads them) and its global `LOAD_BUILTIN` ids are import
-  indices. `ProgramHeap` rewrites them to offsets as it copies the code into place
-  (`particle_link_global_fields`); the program it is keyed by stays unlinked, so deduplication
-  holds. Assembly carries imports as `.global name n`; the optimizers carry them through.
-- **Values.** The CPU's: `GPUParticleSystem.global_fields.set(name, values)` writes words and marks
-  the span, which goes out as one `writeBuffer`; nothing is restaged and no program changes. For a
-  game, `GPUParticleEmitterSystem.set_global_field(name, values)` holds the value until a particle
-  system exists and hands it over again to a replacement one. A global nobody has set reads 0.
-- **Authoring.** `ParticleEffectDocument.global_fields` declares the imports with the value the
-  preview gives them; the `globalField` node reads one; the preview links its own copy of the
-  program to its own layout.
-
-### Transform bindings
-
-A field — an emitter's or a global one — can be bound to a row of the scene's `transforms` table,
-and the GPU writes that row's composed `global` into it every frame: a beam's far end, a homing
-target, a joint the CPU never sees.
-
-- **Table.** `field_bindings`, the particle database's third table (CPU-staged): `source` (a
-  non-owning link to `transforms`, as the emitter's `node` is), `word` (from the field section's
-  base) and `channel` — `POSITION`, `DIRECTION`, `UP` (three words, computed as the emitter's
-  builtins of the same names are) or `ORIENTATION` (a quaternion, scale divided out). A field is
-  bound only to a channel exactly as wide as it.
-- **Pass.** `shader_particle_field_bind`: one thread per binding row, a page group per workgroup,
-  after the counter reset and before the emitter tick, so every VM pass reads this frame's
-  transforms. The program buffer is bound read-write in this pass only. Recorded only while the
-  table has rows.
-- **Authority.** A bound word is rewritten from scratch every frame, so a span upload or a buffer
-  rebuild landing on it is overwritten before anything reads it. Unbinding hands the word
-  back to its own value — the emitter's, or the global's last set value or zero — which goes out
-  with the next upload.
-- **Mirrors.** A mirrored transform is a reflection, which no quaternion is: `ORIENTATION` takes the
-  mirror out of the x axis and writes the rotation that is left.
-- **Bookkeeping.** `EmitterRegistry.bind_emitter_field` / `bind_global_field` and their unbinds. An
-  emitter's bindings are restaged with it, because the word they write is its block's offset plus
-  the field's, and the block moves; one whose field the layout no longer has is dropped, and they
-  go with the emitter.
-- **ECS.** `ParticleEffect.bindings` (`{field, entity, channel}`) and
-  `GPUParticleEmitterSystem.bind_global_field`: entity references, resolved with `row_of_entity`,
-  the row held through the scene's rows while bound. Runtime data and not saved: nothing in the
-  engine's saves carries an entity reference across a load. A target is let go on its own
-  `EntityRemoved`, before the entity is gone; a request the registry refuses — or that names an
-  entity with no `Transform64` — is remembered and not retried until it, or the emitter's layout,
-  changes; one field asked for twice is bound to the first request.
-
-### Particle storage — single shared pool, uniform stride
-
-All particles live in one `array<u32>` pool with a fixed `RECORD_WORDS` stride (config, default 32
-words = 128 B). Word 0 is a reserved header holding the owning **emitter row** and that row's
-**generation** (`data/particle_header.js`); particle fields occupy words `1..RECORD_WORDS`. A
-single pool + single alive/dead lists means **one** emit dispatch and **one** simulate dispatch
-cover every emitter — the Destiny single-shader property.
-
-Lifecycle uses the canonical GPU dead-list / alive-list pair:
-- `dead_list`: stack of free slot indices (+ atomic count). Filled `dead[i] = i` at construction by
-  `shaders/shader_particle_init_free_list.js` — a dispatch, not a host upload, which is why the
-  buffer carries no `COPY_DST`.
-- `alive_list`: a compact list of live slot indices (+ count), rebuilt from scratch every frame.
-- `counters`: atomics {alive_count, dead_count, spawn budget, …} + derived indirect dispatch/draw args.
-
-Emit: pop dead → run INIT → append `alive_new`. Simulate: read the **coherence list** last frame's
-bucketing pass built from `alive_current` → run UPDATE → kill pushes to `dead`, survival appends to
-`alive_new`.
-
-There is no ping-pong pair, although the shape invites one. The frame appends to the new list from a
-counter its first pass zeroes and the draws walk that same new list, so the previous frame's list has
-exactly one reader in the whole design: the bucketing rebuild on a frame whose program assignments
-changed. So the list is taken from the graphics context's buffer allocator and given back every
-frame, before the next is asked for — the pool answers with the same memory, the reserved footprint
-is one list, and only a rebuild frame holds two. See `GPUParticleSystem#swap_alive_list`.
-
-**The loop is strictly GPU-driven.** The build-indirect pass snapshots the padded length of the
-coherence list into `counters[ALIVE_IN]` and writes the indirect dispatch args next frame's simulate
-consumes (`dispatchWorkgroupsIndirect`) plus the indirect draw args this frame's draws consume
-(`drawIndirect`, sized by the *unpadded* alive count); simulate bound-checks against the ALIVE_IN
-snapshot. The bounds pass takes the dispatch the bucket reset writes from the alive count. Sizing
-any of this from a CPU readback is a correctness bug, not a shortcut: the readback is inevitably
-stale, so a growing population orphans the tail of the alive list (slots leak into limbo)
-and a shrinking one re-simulates stale entries — double-freeing slots so two live particles later
-share one record. The emit pass's dead-list pop guards against wrapped counters
-(`old == 0 || old > capacity`), so racing an exhausted pool drops spawns cleanly instead of handing
-out garbage slots.
-
-### Spawning is the GPU's decision
-
-The CPU never walks the emitters per frame and never counts particles. Per frame:
-
-1. **spawn commands** (`shaders/shader_particle_spawn_commands.js`, only when the host queued any):
-   one thread per `[row, count]` pair the host authored, `atomicAdd` into that row's `PENDING` in
-   the GPU-owned emitter state. This is `GPUParticleSystem#spawn` — the CPU's facade over the GPU
-   path, not a second path: a burst goes through the same budget, expansion and INIT program as the
-   emitter's rate. It is also the channel a VM opcode would use to spawn from the GPU (a sub-emitter
-   or trail would `atomicAdd` its target's `PENDING`).
-2. **emitter tick** (`shaders/shader_particle_emitter_tick.js`): one thread per emitter table row,
-   walked with the table's page iterator so an unallocated page costs one word and a freed row one
-   bit. Per live row: recognise the row by generation (a mismatch starts the state over — new
-   emitter, or a reused row, with nothing for the CPU to clear); take `PENDING`; publish the
-   bounding box emit and simulate measured last frame into the state row and reset the accumulator
-   (see **Bounds**); if the emitter opts into culling, test that box against the camera frustum and
-   sleep while culled, paying back a bounded catch-up on wake; integrate
-   `spawn_rate * dt`; turn the whole part of the accumulator into this frame's count, clamped by the
-   **spawn budget** the reset pass seeded from the dead count — so an emitter is only ever debited
-   for particles the pool can hold; write the count to `spawn_counts.elements[row]`.
-3. **scan**: `graph_prefix_scan_csdldf` over the counts — each row's batch ends at its inclusive sum,
-   and the last sum is the number of particles born.
-4. **spawn args**: `shader_prefix_sum_to_command` (the rasteriser's own) turns that total into the
-   emit dispatch.
-5. **emit**: one thread per newborn, locating its emitter by `lower_bound_branchless` over the sums
-   and its batch fraction from the sum before — the meshes-to-meshlets expansion applied to
-   particles. No per-emitter cap, no thread loops over its particles.
-
-On a frame that registered emitters with a `prewarm`, and only then, a loop of the warm-up pipeline
-(`warmup/`) runs after the frame's own simulate: the same decision-scan-emit shape per tick over a
-transient population, plus an advance of its own, then a migration into the main pool. See
-**Pre-warm**.
-
-The host contributes two numbers to all of that: the emitter table's element capacity (the scan's
-length — static topology) and the length of the command list it wrote itself.
-
-### The emitter state (`data/PARTICLE_EMITTER_STATE.js`)
-
-What the GPU integrates per emitter — generation, accumulator, age, sleep, pending — is the
-`emitter_state` table of the same database, one row per emitter at the emitter's row, **not**
-fields of the emitter record. The record is CPU-shadowed and restaged whole whenever the author
-changes a field, and that restage would overwrite an accumulator the GPU has been adding to for a
-hundred frames. The scene's transforms table mixes CPU fields with a GPU-written `global` only
-because `global` is recomputed from scratch every frame; nothing here is. In its own table the CPU
-touches a row exactly twice — a zero record when the emitter's row is claimed, the table's own
-zero-fill when it is released — and the database's resize copies pages on the GPU, so growth keeps
-what the tick has written. Nothing in it is atomic: each row is one tick thread's, and the
-spawn-command pass is handed one command per row (the system merges bursts on the CPU). The
-emitter's `age` here is the VM's `EMITTER_AGE` builtin — and the one field the warm-up pipeline
-writes, as it runs an emitter's clock forward (see **Pre-warm**).
-
-### Eight storage buffers
-
-A compute stage gets eight storage buffers by default, and the design does not ask for more. Two
-things keep every pass under it: the emitter record, the GPU-owned state and the transform bindings
-are three tables of one database buffer, read through one binding; and the VM's constants, code and
-fields are one packed buffer — `[header][constants][code][fields]`, the header's first two words
-saying where the code and the fields start (`ParticleConstants.PARTICLE_PROGRAM_HEADER_WORDS`). Emit and simulate bind exactly eight; their
-wide-register variants bind nine, which is the one place the system spends past the default and is
-still inside the ten the engine demands of an adapter. `particle_shaders_wgsl_validity.spec` pins
-the count for every pass.
-
-Every pass that runs the VM — emit, simulate, their wide variants and the warm-up's advance — also
-binds the scene's published wind field (`../wind/`, `GPUSceneWind.bind`, per frame): one uniform, one
-3-D texture and a sampler, and no storage buffer, so it costs none of the eight. It is bound with or
-without a producer; with none it reads still air. `graph_particles_wind.spec` holds every one of
-those passes to it.
-
-### The VM (`ParticleVM`)
-
-Register machine, emulator-safe (bounded instruction loop + big `switch`, no subgroup ops, no
-recursion, no data-dependent jumps — conditionals are predicated via CMP/SELECT, destruction via
-`KILL`).
-
-- Register file: `array<f32>`, a register being one slot and a value of width *w* occupying *w*
-  consecutive ones. The interpreter reaches it through `vm_reg_read` / `vm_reg_write`, which a
-  **backing chunk** supplies, and the two backings are the two interpreters:
-  `vm/chunk_particle_vm_registers_fast.js` puts the file in `var<private>`
-  (`PARTICLE_VM_FAST_REGISTER_SLOTS`, dynamically indexed, so its size is the shader's register
-  footprint), and `vm/chunk_particle_vm_registers_wide.js` puts it in a storage buffer
-  (`PARTICLE_VM_REGISTER_SLOTS` — every slot an 8-bit operand base can name). See **Two
-  interpreters** below.
-- Instruction: fixed **4×u32** words `[op | width << 8 | kinds << 16 | dst << 24, s0, s1, s2]`.
-  Word 0 packs the opcode (bits 0..7), the lane count (8..10), each source's `VM_KIND` (two bits per
-  slot at 16..21) and the destination slot (24..31). A source word means what its kind says: `REG`
-  is a base slot plus a swizzle, `IMM` is an `f32` bit pattern read in every lane, and `NONE` is a
-  raw field the opcode reads for itself (particle field word-offset+comp / builtin id /
-  pool index).
-- Constant pool: `array<vec4f>` per program, referenced by `LOAD_CONST`.
-- Two entry sections per program: **INIT** and **UPDATE** (offsets in the emitter record). INIT
-  gives an already-allocated record its state; it has no say in whether the particle exists.
-- Builtins (`LOAD_BUILTIN`): DT, EMITTER_AGE, EMITTER_POSITION, EMITTER_DIRECTION, EMITTER_UP,
-  PARTICLE_INDEX, SPAWN_FRACTION, TIME … assembled per-invocation by the host shader. The emitter's
-  position and axes are its node's `global` out of the scene database.
-- `SAMPLE_WIND dst, position` (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §13): the scene's wind at a
-  world position, m/s — three lanes in, three out (a fourth, if asked for, is zero). The one opcode
-  that reads a resource the host binds: the interpreter calls `particle_vm_sample_wind`, which every
-  particle host defines over the published wind field (`vm/chunk_particle_vm_wind_field.js`), and the
-  JS reference calls its `sample_wind` host function — still air when a host passes none. To the
-  optimizer it is a pure read: removable, shareable within a run, narrowable to three, never folded.
-
-#### Two interpreters
-
-The register file normally lives in shader registers, which is what makes it fast and what makes it
-small. An effect whose compiled program wants more slots than it holds is not an error and not an
-authoring ceiling: the whole system swaps emit and simulate for variants whose file is a storage
-buffer, and everything runs, slowly.
-
-- **The trigger is the set, not the program.** `ProgramHeap` reports `max_register_count` over the
-  programs it holds, and `GPUParticleSystem` is where that number is compared against
-  `PARTICLE_VM_FAST_REGISTER_SLOTS` — the store has no opinion about what a register budget means,
-  and which backing a pass is compiled against is the VM's business. One hungry effect moves every
-  emitter onto the wide pair; there is one pipeline per pass and it is chosen once, per frame, in
-  `graph_particles`. It moves back when that effect is unregistered: the heap knows what it holds,
-  so the number is a maximum over the live set rather than a high-water mark.
-- **The launch is bounded.** The wide passes need a register file per invocation in flight, so they
-  do not run one lane per particle — that would size the buffer by pool capacity. They launch
-  `PARTICLE_VM_WIDE_LAUNCH_LANES` lanes whatever the workload and walk their input with a grid-stride
-  loop, so the file is `LANES * SLOTS * 4` bytes and nothing else. The stride is a whole number of
-  workgroups, which is what keeps a wave inside one coherence bucket and the wave-uniform section
-  decode sound.
-- **Slot-major, and never cleared.** `vm_registers[slot * LANES + lane]`, so a wave reading one slot
-  reads a coalesced run. The buffer is transient and no pass zeroes it: a register is undefined until
-  written, and a program that reads one first is corrupt. That is the one place the two backings are
-  not interchangeable — the fast file zeroes, so the reference executor and the fast VM agree on a
-  value the wide VM has no opinion about.
-- **Held to the same bar.** `vm/chunk_particle_vm.spec.js` runs every parity case, fuzz included,
-  against BOTH backings; `shaders/particle_wide_register_passes.spec.js` runs the wide passes against
-  the fast ones under the emulator and exercises the grid-stride loop.
-
-**Parity strategy.** The opcode numbers + operand semantics live in one source of truth
-(`isa/ParticleVMISA.js`). Two executors implement it: a JS reference VM (`vm/ParticleVMReference.js`)
-and a hand-written WGSL interpreter (`vm/chunk_particle_vm.js`). A spec runs identical programs
-through both (WGSL via the emulator) and asserts bit-for-bit-close equality. A meta-test asserts both
-executors cover every opcode in the ISA table.
-
-### Node graph → bytecode
-
-A core `NodeGraph` holds particle nodes (ports + parameters) for INIT and UPDATE. `compile()`:
-1. topologically orders reachable nodes,
-2. lowers each node to VM ops (nodes emit via a small builder that allocates result registers),
-3. linear-scan register allocation with liveness,
-4. interns constants into the pool,
-5. resolves particle, emitter and global field references,
-6. emits `ParticleProgram { init, update, constants, register_count, global_imports }`.
-
-Standard node library: constants, particle field get/set, emitter and global field get,
-arithmetic/vector/math, random (uniform/sphere/disk/cone), authored curves and RGB/RGBA gradients,
-noise (curl), integrate, gravity, emit-shapes, compare/select, kill-if, and `wind` (a world position
-in, the scene's wind there out: `SAMPLE_WIND`). Curves and gradients expand into graph nodes that
-emit ordinary VM arithmetic; no animation-table binding or sampling opcode is needed.
-
-### Emitters run at entities' rows
-
-A `ParticleEmitter` is placed by registration: `GPUParticleSystem#add_emitter(emitter,
-transform_row)` gives it a row in the emitter table pointed at a `transforms` row — an entity's,
-one on, held through the scene context's rows by whoever owns the entity — and `remove_emitter`
-retires the row and frees its particles. The GPU hierarchy pass composes that row's `global` from
-its pose and its parents' every frame, animation included, so an emitter registered at a joint's
-row follows the joint with nothing copied through the CPU — which a CPU-side copy of a world
-matrix could not do, since the CPU never sees the matrix of a row the GPU owns. Nothing walks the
-scene: an emitter is where its owner says it is, and per-frame upkeep is proportional to what
-changed rather than to how many emitters there are.
-
-**The emitter knows nothing about the GPU, and nothing about where.** A `ParticleEmitter` is a
-particle field `layout`, a compiled `program`, an `emitter_layout` with this emitter's
-`emitter_fields`, a `texture` URL, and the emission parameters — all of
-it the author's, all of it meaning the same thing with no device present, all of it what a saved
-effect is made of. Everything the system assigns is a `GPUParticleEmitterContext`, held by the
-`EmitterRegistry` against the emitter and reached through `registry.context(emitter)`: the table
-row, the generation, the program placement, the `transforms` row it is placed at, the atlas patch.
-So an emitter cannot be saved with a row in it, cannot be given one by hand, and "is this emitter
-live?" is asked of the registry rather than read off a `-1` that anything could have written. The
-record writer is where the two meet — `write_emitter_record(record, emitter, context)`, next to
-the struct it fills.
-
-Restaging is driven by `ParticleEmitter#version`, the emitter's own change counter; the context
-remembers the version its row was staged from. An author who edits an emitter says so with
-`needsUpdate = true`, and there is no second flag to forget. A change to the context itself (a
-`transforms` row, a repacked atlas patch) moves no version, so the context marks itself instead.
-
-### Emitter table (`GPUDatabase`)
-
-One `emitters` table (CPU-managed, low churn). Row = `PARTICLE_EMITTER_STRUCT`: program
-offsets+lengths, constant-pool offset, seed, spawn rate, **node** (transforms row), **generation**,
-flags (lighting/soft/cull/blend/projection), render binding (attr offsets for
-position/size/color/orientation/frame/velocity), atlas region + flipbook grid, and the program id
-the coherence pass buckets on. The atlas region is resolved, not authored: the emitter names an
-image and the system packs it, the way `ShaderManager` packs the old engine's sprites, so a repack
-moves every patch without any emitter changing. The seed is resolved too — an emitter left at 0 gets
-its registration's generation, which no other emitter of the registry shares, rather than being
-written to. Programs+constants live in a packed `ProgramHeap` buffer
-(variable length → not a fixed-stride table).
-
-The struct is the ONLY statement of that layout. The JS writer is the database's
-`write_wgsl_type_value`, and the WGSL reader — the `ParticleEmitter` struct declaration plus
-`database_read_..._element` — is generated from the same struct by the table descriptor. There is no
-hand-packed word offset table to drift out of step with the shaders, and no hand-written reader.
-The bucket histogram, which runs once per live particle and wants only `program_id`, reads it
-through `chunk_read_field` rather than decoding a whole row.
-
-**Editing the set at runtime is the point of using a table.** `EmitterRegistry.add` stages one
-record and `remove` frees one row; neither touches the others. Rows are stable for an emitter's
-lifetime because a live particle's record header holds the row of the emitter that spawned it —
-renumbering a survivor would re-point its particles at somebody else. A removed row is handed back
-to the next `add`, so the id space does not grow without bound.
-
-**Generations make that reuse safe.** Every add takes the next value of one running counter, never
-zero, and the particles of an emitter carry its generation in their header. The simulate pass kills
-any particle whose generation is not its row's current one — the row is zero-filled (generation 0)
-or a later tenant's — so a hard removal frees the emitter's particles within a frame, and a reused
-row cannot adopt a stranger's. Graceful retirement (rate to zero, remove once the tail has died)
-remains an author's choice rather than a correctness rule.
-
-**Programs are edited the same way.** `ProgramHeap` is a pair of range allocators
-(`OffsetAllocator`) over the two sections of the packed buffer, keyed by a `HashMap` on the bytecode
-itself — `ParticleProgram` answers `equals`/`hash`, so content deduplication is the map's doing
-rather than a stringified key's. `acquire` takes a reference and `release` gives one back, so the
-last emitter of an effect is what unpacks it, and `EmitterRegistry.set_program` swaps an emitter onto
-different bytecode while it is live. What makes that possible is that a program is **relocatable**:
-instructions carry no absolute addresses and constant references are program-local, so the heap can
-move one by copying its words and rewriting the placement.
-
-Two things are deliberately NOT reclaimed. **Program ids** are reused rather than renumbered — they
-are baked into every emitter record, so compacting them would mean rewriting the whole table — and
-`bucketCount()` is sized from the id capacity, the set's peak, so it does not move every time an
-effect comes or goes. An id below the peak with nothing in it is an empty bin, which rounds up to
-zero workgroups and shifts nothing after it. **Section capacity** only rises: a repack (which happens
-when a section has no contiguous run long enough) compacts what is live and grows only if it must,
-so a set that peaked at a hundred effects does not pay for a resize every time it returns to three.
-
-A repack is the one change no emitter announces, since it is not an edit to any of them.
-`EmitterRegistry.flush` asks the heap once per frame — `placement_version` — and restages every row
-when it has moved.
-
-Programs are immutable after compilation. Both `registry.set_program(emitter, program)` and replacing
-`emitter.program` followed by `needsUpdate = true` are supported. Flush reconciles replacements
-before inspecting heap relocation, since acquiring a replacement may move other programs too.
-The layout must remain compatible with particles already in flight.
-
-A live program assignment increments `program_assignment_version`. On the next frame, before reset
-or simulation, the previous compact alive list is bucketed again and its padded count and dispatch
-are rebuilt. This prevents a previously shared wave from executing one emitter's newly edited program
-over another emitter's particles. Ordinary frames keep the existing end-of-frame bucketing only;
-content-identical replacements need no repair. Both bucket runs on an edit frame reuse the latest
-graph handles for their scratch, so it is created once and both runs share one dependency chain.
-
-The coherence list is persistent GPU state, including its padding — the one thing the bucketing
-leaves behind. Growing the bucket capacity copies it to the replacement buffer before destroying the
-old one; the old count and indirect dispatch remain valid across growth. The histogram, cursors, keys
-and dispatch args beside it live and die inside one frame graph, so the passes that write them
-declare them (a `BufferResourceDescriptor` in place of a handle) and the graph allocates and releases
-them around their users. None asks for a clear: the reset pass already covers every word it will
-read, and `keys` is written by the same indirect dispatch that reads it.
-
-Every row of a frame is staged through one module-static record (`EmitterRegistry`), so a flush
-allocates nothing however many rows it restages.
-
-### Bounds
-
-An emitter has no bounds it could declare. Its particles are simulated in world space by arbitrary
-bytecode: they go where the program sends them, at whatever size it gives them, for as long as it
-keeps them alive. The only bound an author could write down and still be right is an infinite one,
-which culls nothing and reserves every depth slice. So the box is **measured**, on the GPU, every
-frame.
-
-Two passes of its own (`bounds/`), at the end of the frame, after emit and simulate have both
-finished appending to the alive list:
-
-- **accumulate** — one thread per live particle: read where its quad is and merge it into its
-  emitter's accumulator. The centre is the record's `render_position`; the dilation is
-  `particle_billboard_radius`, the largest offset `particle_billboard_offset` can produce for that
-  size, velocity and projection, over every corner, every orientation and any camera. The box has to hold
-  the *quads*, not the centres, and it has to be camera-independent, because it is read on a later
-  frame. The merge is `atomic_min_f32_storage` / `atomic_max_f32_storage`, the same CAS-spin the
-  skinned-mesh bounds refresh uses; both load first and return without a CAS once the box holds the
-  contribution, so what survives is load traffic, not exchanges. Dispatched indirectly from
-  `sim_dispatch_args`, the args the coherence reset wrote from the GPU's own alive count.
-- **publish** — one thread per emitter row: write the accumulation to `bounds_min` / `bounds_max` of
-  the state row (`data/PARTICLE_EMITTER_STATE.js` — measured state is GPU-owned state, and on the
-  record it would be clobbered by the next restage), and reset the accumulator. The reset is
-  unconditional, which is what lets a row that changes hands start clean.
-
-**Why a pass and not a tail on emit and simulate.** It was that first. Booking from inside those two
-measures no single population — simulate sees last frame's survivors and emit sees this frame's
-newborns, so the union spans two frames and is looser than either — and it pays six atomics per
-particle inside the pass whose register pressure decides the system's occupancy, to compute
-something that needs none of the VM, none of the scene, and five words of the record. Over the alive
-list instead, the measurement is of exactly the set that is alive and about to be drawn.
-
-**Where the accumulator lives.** Six words per emitter row, in the **counters** buffer, after the
-counters themselves (`data/PARTICLE_COUNTERS.js`). It has to be an `array<atomic<u32>>` binding, and
-the emitter database cannot be it — the passes that read a record read it out of an `array<u32>`
-binding, and one buffer under two access types is aliasing. The counters buffer is already bound in
-both bounds passes, already atomic, already the system's cross-pass scratch, so a buffer of its own
-would add a binding and a growth path to say the same thing. It therefore grows with the emitter
-table, by copy — the free-list length in it is GPU-owned and unreconstructable — and the rows the
-growth adds are written to the empty interval, because a zeroed accumulator reads back as a
-degenerate box at the world origin rather than as an absence.
-
-**The empty case.** An emitter with no measured particles has infinite, unknown bounds:
-`bounds_min = [-Infinity, -Infinity, -Infinity]`, `bounds_max = [Infinity, Infinity, Infinity]`.
-The CPU stages this on registration and the publish pass restores it whenever the population is
-empty. The tick treats unknown bounds as visible, so a slow emitter can accumulate its first spawn
-without prewarm even when its node is offscreen. A depleted population can restart the same way.
-AVBOIT occupancy skips unknown bounds because there are no live particles to splat. Both readers
-test the sentinel before geometric arithmetic, avoiding NaNs from operations on infinities.
-The sentinel check compares integer bits. The publish pass swaps the empty accumulator's loaded
-endpoints; neither path constructs an infinite floating-point constant, which WGSL rejects at
-shader creation time.
-Measured, nonempty populations continue to use their finite bounds for culling. No bounds are authored.
-Prewarm controls the initial age distribution only; it is not required for culling correctness.
-
-### Pre-warm
-
-A continuous effect that starts empty grows into its steady state over one particle lifetime, in
-front of whoever is watching. `ParticleEmitter.prewarm` — seconds, `0` for off — buys that lifetime
-back: an emitter registered with one is run forward by that long before it is first drawn.
-
-**A warm-up is the ordinary loop, run over a population of its own.** Spawn, init, advance, per
-tick, until every emitter in the batch has been running for its own `prewarm`. It is *not* a batch
-of particles dumped in one tick and aged: the emitter keeps spawning throughout, what dies is
-replaced as it is in a live scene, and whatever drives the rate — a spawn curve, `EMITTER_AGE`, the
-program itself — drives it here, because it is the same program being run. What the loop leaves is
-the population the emitter would have had.
-
-**It is a pipeline apart from the main one** (`warmup/`), because the main one is tuned and must not
-pay for this. Emit and simulate are the passes whose register pressure sets the system's occupancy,
-and their waves are kept program-uniform by the bucketing; a warm-up folded into either would spend
-registers on every frame for work that happens on one, and a loop inside a lane would break the
-uniform flow across a wave. So the warm-up shares code with the main frame and integrates nothing
-into it: the main **emit pass is reused unchanged**, bound to the warm-up's buffers; the tick is a
-pass of the warm-up's own over a host-written queue (`shader_particle_warmup_tick`) rather than over
-the emitter table; the **advance** is a pass of the warm-up's own (`chunk_particle_warmup_step.js`),
-decoding the program section per lane — it reads the raw alive list, so it cannot lean on the
-bucketing's wave-uniformity, and its occupancy is its own business. The main passes' compiled code
-is byte-identical whether `warmup/` exists or not.
-
-**The population is transient.** Pool, both alive lists, free list and counters are frame-graph
-transients that exist for the loop and are then moved, record by record, into the main pool by the
-**migrate** pass — a pop from the main free list per particle, and never a push, so it is the one
-point of contact and it is safe by construction. The loop's own free-list traffic never touches the
-main list, and the main passes never see a half-warmed particle.
-
-**Bounded.** `warmup/warmup_schedule.js`: at most `PARTICLE_WARMUP_MAX_TICKS` ticks, no shorter than
-`PARTICLE_WARMUP_TICK_SECONDS`, the tick *length* stretching to cover the longest pre-warm in the
-batch rather than the count growing to cover it — the count is what the frame pays for, at six or
-seven dispatches a tick. An emitter takes part in a tick once the loop's clock is within its own
-pre-warm of now, so two emitters queued with different durations each end having run for exactly
-their own; the shorter one sat out the start.
-
-**Jittered, so it does not arrive in bands.** Every particle born in one tick would otherwise reach
-the end with exactly that tick's age, and N ticks would read as N cohorts. The advance jitters the
-tick per particle (`PARTICLE_WARMUP_DT_JITTER`, hashed from slot and tick — a hash, not a draw, so
-the program's own random stream is untouched), and the host jitters each emitter's clock and starting
-accumulator (`PARTICLE_WARMUP_EMITTER_JITTER`), so emitters in one batch do not spawn on the same
-beat either. A program does not care what `DELTA_TIME` it is handed; the smear is free.
-
-**Where it sits.** After the frame's own emit and simulate, before the bucketing. Migrate appends to
-the same alive list they did, so the bucketing puts the warmed particles in next frame's simulate
-list, the bounds pass measures them into their emitter's box this frame, and the draw draws them
-this frame. The tick also writes the emitter's
-`age` into its state row as it goes, so `EMITTER_AGE` reads as it would have, and the next real tick
-adds its `dt` to a row that says `prewarm`.
-
-**Only on the frame that needs it.** The host knows: an emitter is queued when it is registered with
-a `prewarm` (`GPUParticleSystem#sync_membership`), the queue is uploaded and consumed by the frame
-that records the loop, and an ordinary frame records nothing of this.
-
-The editor's CPU preview (`editor/particles/effect/ParticleReferenceSimulation.js`) runs the same
-loop over the same schedule before its first frame, and restarts the effect when the duration
-changes: a pre-warm is a statement about how an effect starts, so the only way to show one is to
-start it.
-
-### Culling & attach
-
-An emitter that sets `EMITTER_FLAG.CULL` has the box on its state row tested against the camera
-frustum by the tick pass, with the renderer's shared `chunk_aabb3_intersects_frustum`. The tick does
-not measure it — it reads what the bounds passes published at the end of the previous frame — so all
-that is in the spawn path is one frustum test. Because the box is where the particles are rather
-than where the emitter is, an effect whose particles have drifted on screen keeps spawning even when
-its emitter has not. Culled emitters spawn nothing and accrue sleep; on wake the tick adds a
-catch-up of at most `max_catchup_seconds` of rate. Live particles keep simulating while their
-emitter is culled, so its box keeps moving and keeps being published. HiZ occlusion is not
-written.
-
-### Two orderings, and why they are separate
-
-There are two independent permutations of the live particles each frame. They are produced by
-different passes into different buffers and must not be conflated or derived from one another.
-
-**Simulation order** (`coherence/`) — camera-independent, changes only when emitters or their
-programs change. The alive list comes out of compaction (`atomicAdd(&counters[ALIVE])`), so its
-order says nothing about which emitter a particle belongs to and a wave routinely holds particles
-running different VM programs. That costs twice: the interpreter's ~40-case opcode `switch`
-diverges, so a wave serially executes the union of the opcodes its lanes want; and `vm_reg[dst]` /
-`vm_reg[s0]` index a VGPR-resident register file dynamically, which AMD reaches with
-`v_movrels`/`v_movreld` behind a waterfall loop whose trip count is the number of *distinct*
-register indices live in the wave. Grouping the wave by program collapses both at once.
-
-The grouping is also **load-bearing**: the simulate shader reads its section parameters (code offset,
-instruction count, constant offset) from the wave's first lane through `subgroupBroadcastFirst`
-(`particle_wave_uniform`), which is what lets the driver fetch instruction words through the scalar
-unit, branch the opcode switch on a scalar and index the register file through M0 without a
-waterfall. A wave holding two programs would run one over the other's particles, so the coherence
-pass is part of simulate's correctness. Emit keeps a per-lane decode: its waves span emitters.
-
-The bucket key is the **program**, not the emitter: `ProgramHeap` deduplicates by content and hands
-back a `program_id` the emitter record carries, so emitters compiled from the same graph share
-one bucket. Each bucket is padded out to `PARTICLE_SIMULATE_WORKGROUP_SIZE` (64 — a multiple of both
-plausible subgroup widths, so no shader needs to query `subgroup_size`), which is what makes the
-grouping hold at wave granularity: an unpadded boundary lands mid-wave and that wave spans two
-programs again. Padding entries carry `PARTICLE_SIM_PAD_SLOT` and the simulate shader drops them
-*before* the compaction atomics, so they never enter the alive or dead list.
-
-It is an **indirection** list. Particle records never move: slots are referenced by the dead list and
-across frames, so relocating a record would leave both pointing at the wrong particle.
-
-It is a counting sort in three phases, with the padding added: histogram (atomic per bucket) →
-round each bin up to a whole workgroup → `graph_prefix_scan_csdldf` (reused as-is — the one scan here
-whose only cross-workgroup wait is CSDLDF's bounded spin-then-fallback) → scatter → fill the tails
-with the sentinel. Nothing reads back to the CPU; the only host-supplied number is the bucket count,
-which is static topology.
-
-**There is no render order.** The draws walk the alive list exactly as compaction left it, because
-everything downstream of them is a sum: the AVBOIT volume accumulates extinction and the four
-accumulators accumulate colour, coverage and emission, and no arrangement of the instances changes
-any of those. So the system spends nothing on ordering: no key pass, no scan, no scatter, and no
-per-particle key and index lists to hold them in.
-
-The two lists are still distinct and must stay so: the simulation list is permuted and padded with
-sentinels, so drawing it would draw them, and depth-ordering it would destroy the coherence. They
-share no buffer and no counter slot — `SIM_PADDED` is the simulation list's length, `ALIVE` the
-draw's.
-
-### Rendering
-
-A 6-vertex quad is expanded per instance by `chunk_particle_billboard_vertex`, on the basis the
-particle's projection mode and orientation compose (below). Fragment: sample atlas (region + flipbook frame), optional
-soft-depth fade, optional lighting (below). Soft-depth fading scales both RGB and alpha for
-premultiplied inputs; straight-alpha and additive inputs have alpha scaled before premultiplication.
-
-### Orientation
-
-**The record says how a particle is turned; the projection mode says how a view sees it.**
-
-    offset = F(mode, camera, velocity) · Q · (corner.x · size, corner.y · size · stretch, 0)
-
-- **`Q` is the `orientation` render channel**, a 4-word particle field holding a quaternion (x, y,
-  z, w) — the only rotation a particle has. It is normalised at the draw, because a program
-  integrating a spin drifts off unit length and an unnormalised quaternion scales what it turns by
-  its squared length. The zero quaternion, which is what a particle field nobody wrote holds, reads
-  as no turn with no branch, and so does an unbound channel.
-- **`F` is the mode's frame**, a proper rotation whose x and y are the sprite's right and up and whose
-  z is the side the mode shows: BILLBOARD the camera's axes; STRETCHED the screen velocity as its up
-  and the camera's axes at rest; VERTICAL world +Y as up and a horizontal face toward the eye;
-  HORIZONTAL world +X and -Z, facing +Y; FACING_WORLD the world's axes. Every one of them shows the
-  sprite the way round BILLBOARD does from its front, rather than its mirror image — three did not,
-  until the frames were written down as frames.
-- **`stretch`** is STRETCHED's `1 + |v_screen|` and 1 otherwise. It belongs to the sprite and
-  elongates it along its own +Y, before the turn.
-
-So FACING_WORLD with an orientation is a quad turned any way in the world, BILLBOARD with one is a
-quad turned relative to the eye — a turn about +Z is a roll on the screen, which is how the bonfire's
-flame, smoke and soot spin — and the other modes take a turn inside their frames with no rule of
-their own. The frame is the renderer's and the rotation the record's because the frame is the one
-part a view decides: the VM has no camera, one record is drawn by every view, and no quaternion
-written into it could face all of them.
-
-`particle_basis` composes the two once per vertex and feeds both the offset and the normal, so they
-cannot disagree about which way a mode faces. **Bounds do not change**: the basis is a rotation, so no
-corner reaches past `sqrt(2) · size · stretch`, which is what `particle_billboard_radius` already
-states; the bounds pass never reads the channel. **The VM does not change** either: a program writes
-a vec4 particle field like any other, and the node library has what it takes to build one —
-`quatFromAxisAngle`, `quatLookRotation`, `quatRotate`, `quatMultiply`, `quatIntegrate` (exact for a
-constant angular velocity at any step, which the warm-up's stretched ticks need), `sampleRotation`
-(uniform) and `emitterRotation` (the node's own rotation; `EMITTER_DIRECTION` is its -Z).
-
-There is no scalar roll channel beside it. A version-1 `ParticleEffect`, whose bytecode wrote a roll
-angle there, loads with its orientation unbound. `ORIENTATION_PLAN_2026_10_15.md` has the
-alternatives and why each lost.
-
-Additive vs. alpha is never a pipeline switch: the shader emits premultiplied RGB with alpha 0
-(additive) or alpha a (normal), so one setup covers both and the choice stays per particle and
-GPU-driven. Under AVBOIT that choice picks which accumulators the fragment writes.
-
-### Drawing: an AVBOIT side channel
-
-The particles are drawn by the AVBOIT transparency pipeline (`rasterize/native/avboit/`) as a
-**side channel** — the contract in `AVBOITSideChannel.js` — so they composite order-independently
-with the transparent meshes and against the opaque scene, through the same volume and the same
-accumulators. Quads are not packed into meshlets; the orchestrator asks the channel for its
-contribution at the three points where the meshlet buckets have just made theirs:
-
-1. **occupancy** (`shader_particle_avboit_occupancy`): one thread per emitter row, the emitter's
-   measured box (the culling box, off the state row) as a view-depth interval, dilated and OR-ed
-   into the occupancy bits. The interval is the box's centre depth plus or minus its extent along
-   the view axis — a support projection, not eight transformed corners. Per emitter, not per
-   particle — no contention, and a particle that strays lands on a run boundary rather than anywhere
-   wrong. Additive emitters mark nothing. The box matters here even for an emitter that never opted
-   into culling, which is the second reason it is measured for every emitter rather than only for
-   the ones that cull.
-2. **splat** (`shader_particle_avboit_splat`): the billboard quads rasterized at the volume's
-   resolution, coverage from the atlas alpha, extinction through `avboit_splat_slice` — the same
-   write path as a surface. Additive particles write nothing. A soft-depth particle is faded here
-   against the same scene depth the draw fades it against, averaged over the voxel's footprint at the
-   four standard 4× multisample positions (`chunk_particle_avboit_voxel_fade`): what the volume
-   records has to be the coverage the accumulators are weighted by, or a card that fades out where
-   it meets the floor goes on darkening the floor through itself. (One read at the voxel's corner
-   recorded up to 2.4× the coverage on a floor seen at a distance; AVBOIT ledger entry 26.)
-3. **draw** (`shader_particle_avboit_draw`): the quads at internal resolution, depth-tested read-only
-   against the scene (which lets the soft fade read the same depth), fog composited, transmittance
-   from the integral. Which of the two it is, is decided by coverage rather than by the blend enum,
-   so an additive emitter and a premultiplied sprite with no alpha take the same path — as they do
-   in the splat. A covering particle writes `color / norm / extinction` as a surface does, in-scatter
-   included, weighted by the coverage it took. An emitting one writes the fourth accumulator,
-   **emission**: light attenuated by the fog and by the volume in front of it, and carrying none of
-   the fog's own in-scatter, because the resolve adds emission outside the normalization and the
-   scene behind already has it. That accumulator is the one addition to AVBOIT's resolve for this.
-   The whole decision is `chunk_particle_avboit_contribution`, and it is spec'd on the emulator.
-
-All three read the alive list and the draw args straight from `simulate`; the vertex stage is one
-chunk (`chunk_particle_billboard_vertex`), shared by the splat and the draw. `GPUParticleSystem`
-implements the three methods; `Renderer.feature_particles_enabled`
-runs `execute` before the transparency pass and hands the system to the orchestrator. MBOIT is legacy
-and gets no particle path, so under it the particles simulate and are not drawn.
-
-The particles are no longer the only side channel: the dynamic meshes' (`DynamicMeshAVBOITChannel`,
-which trails are drawn through) meets the same three contracts, and the two share what they have in
-common rather than each keeping a copy — the box's depth interval and the slice marking
-(`aabb3_view_depth_range`, `avboit_occupancy_mark`), the coverage clamp (`avboit_coverage`) and
-everything `chunk_particle_avboit_contribution` does after its premultiply
-(`avboit_premultiplied_contribution`). A change to any of those changes both channels.
-
-### The ECS: `ParticleEffect` + `Transform64`
-
-`engine/graphics3/GPUParticleEmitterSystem.js` is how a game reaches this system. It is an ordinary
-ECS system over the pair `[ParticleEffect, Transform64]` — the component says what an entity emits,
-the transform says where — in exactly the shape `DecalSystem` and `MeshSystem` use for their own
-content. Construct it with `(graphicsEngine, scene, assetManager)` and add it to the EntityManager.
-It is opt-in.
-
-```js
-entityManager.addSystem(new GPUParticleEmitterSystem(graphics, scene, assetManager));
-
-new Entity()
-    .add(new Transform64())
-    .add(ParticleEffect.from({ ...create_particle_effect({ layout, init, update }), spawn_rate: 400 }))
-    .build(dataset);
-```
-
-`engine/graphics/ecs/particles/ParticleEffect.js` carries everything a `ParticleEmitter` node carries
-except the placement: the layout and compiled program, the emitter layout and this entity's emitter
-field values, the texture URL, the rate, `emitting`, the pre-warm, the flags, the render bindings,
-the flipbook grid and the transform `bindings`. Nothing on it depends on a device, which is what
-makes it the unit an editor inspects and a prefab holds.
-
-**All of it serializes, the compiled program included; the transform bindings do not** —
-`ParticleEffectSerializationAdapter`, version 3, registered in `populateEngineSerializationRegistry`. The instruction set was designed to be a durable
-format, so a level carries bytecode the way it carries a mesh's indices and a shipped build needs no
-compiler: authoring is an editor's job and it is not in the runtime. Two things are consequently wire
-format and cannot be renumbered without a version bump and an upgrader — the **opcode numbers** in
-`isa/ParticleVMISA.js`, and the **order of the fields** in a layout, because a layout assigns its
-word offsets from that order: the record's render bindings are particle field offsets, and saved
-emitter field values are words in emitter layout order. The
-constant pool goes out as `Uint32` bit patterns rather than floats, because that is the form the
-pool is already compared and hashed in (`ParticleProgram#constant_words`): `-0` and `+0` are the
-same number and different constants, and whether a NaN's payload survives a round trip through a JS
-`number` is implementation-defined even though V8 happens to preserve it.
-
-The system builds one `ParticleEmitter` per linked entity and owns it — registered with the
-scene's particle system at the entity's row (`row_of_entity`, held through the scene context's
-rows) when the component has a compiled effect and a context exists, its row marked from the
-entity's transform on `TRANSFORM64_EVENT_CHANGE`, and retired with the entity. Registration runs at
-link, at every `update` and at `FrameStart`, so an entity spawned mid-level stands where it should
-from its first frame and a device restart re-registers every entry with the context that replaced
-the old one. `emitter_of(entity)` hands the emitter out for what an entity reference cannot express
-(asking the particle system about it); `burst(entity, count)` is the entity-addressed one-shot,
-queued and drained inside the frame so it works before the first frame has run.
-
-Component changes are found by **comparison** rather than announced: once a frame each entity's
-component values, emitter field values included, are compared against what was last written to its
-emitter, and the emitter is marked dirty
-only where they differ, so a component nobody touched costs a run of integer comparisons and no
-upload. That is what lets gameplay write `effect.spawn_rate = 0` from code that has never heard of
-this system.
-
-A caller with no ECS — a playground, a tool — registers a `ParticleEmitter` with the scene's
-`GPUParticleSystem` directly, at a row of an entity it placed itself. Such an emitter has nothing
-in the ECS system's atlas and is given the white texel; see below.
-
-`shade/playground/particle_ecs/` is the worked example: a bonfire whose flame, smoke, embers and soot
-are four entities, alongside `ShadedGeometry` and `Light` entities in the same scene.
-
-The system loads image URLs through `AssetManager` (`GameAssetType.Image`) and shares one patch per
-URL. It reuses `TextureAtlas`, whose packer is `MaxRectanglesPacker`. When the last entity releases
-an image, its patch is removed. Loads completing after a URL change, removal or shutdown are ignored.
-Failed images are reported and remain transparent until the URL changes or the emitter is re-added.
-Untextured emitters use a white texel; pending images use a transparent texel.
-
-At `FrameStart`, after the scene context has established transform rows, the system registers
-any emitter not yet registered with the frame's context, uploads changed atlas pixels, and refreshes
-the patch region of every emitter the particle system holds — the ones it built get their entity's
-image, and any other gets the white texel, because the atlas is the scene's and an emitter it did
-not build has nothing in it.
-This occurs before particle simulation stages emitter rows. Every repack or resize therefore updates
-existing emitters too. The extension enables the renderer's GPU particle feature for its scene;
-rendering uses the existing AVBOIT path. The system owns a `GPUTextureContext` for the atlas, using
-its resize and cached-view handling and advancing its version after each pixel upload. Shutdown
-restores the default atlas and destroys the owned context. A replacement device gets a fresh upload
-from the retained CPU atlas.
-
-`GPUParticleSystem` itself does no asset loading or packing. Standalone callers can still supply
-`atlas`/`atlas_sampler` and call `registry.set_atlas_region()` themselves. The `atlas` binding remains
-a `GPUTextureView`, obtained from its owner's context; the default white texture is also owned
-through `GPUTextureContext`.
-
-### Ownership: `GPUParticleSystem`
-
-Constructed once against a `GPUSceneContext`, in the mould of `ReSTIRDI`. It owns persistent buffers
-and only those — a buffer is reserved here if and only if its contents cross the frame boundary:
-pool, alive list, dead list, counters, the coherence list, simulate's indirect dispatch args, the
-emitter database (both tables), the packed program buffer, the spawn-command ring and the warm-up
-queue — and grows the ones that depend on the emitter set inside `execute`. Everything else a frame
-touches is the frame graph's, declared by the pass that first writes it: the bucketing scratch, the
-draw args, the spawn counts and the wide register file. The default atlas is a 1x1 white texel.
-`execute({graph, camera, scene_database, dt})` sweeps the scene, pushes what changed (on a command
-context opened only when something needs one), and records the simulation through `graph_particles`,
-returning the handles the side channels draw from. It touches no colour target — the drawing is the
-transparency pipeline's — and an integrator does not encode a particle pass by hand.
-
-The frame reads nothing back, but a HUD or an inspector wants to: `read_stats()` copies the counters
-and the dispatch args out and returns them named — alive, free, the spawn budget, both list lengths
-and the workgroups the next simulate will launch. That is the whole of the readback, and the only
-reason the dispatch args carry `COPY_SRC` (the counters and the coherence list carry it to be copied
-forward when they grow). Nothing it returns may size a pass: the numbers describe a frame already
-submitted, and what sizing from a stale count costs is set out under the finalize pass above. The
-draw args are not among them and cannot be — they are the graph's, released after the last draw that
-reads them — and their instance count is the alive count regardless.
-
-## File layout
-
-```
-src/shade/renderer/particles/
-  DESIGN.md
-  ParticleConstants.js               pool stride, reg count, workgroup sizes, limits
-  isa/ParticleVMISA.js               opcode table (single source of truth)
-  isa/ParticleProgram.js             Program value type + (de)serialization to u32
-  isa/ParticleAssembler.js           tiny assembler (build programs in tests/library)
-  isa/particle_link_global_fields.js global field import indices → section offsets, at placement
-  vm/ParticleVMReference.js          JS reference executor
-  vm/chunk_particle_vm.js            WGSL interpreter CodeChunk (parity target)
-  vm/chunk_particle_vm_registers_fast.js  register file in var<private> — the interpreter that runs
-  vm/chunk_particle_vm_registers_wide.js  register file in storage — the fallback
-  vm/chunk_particle_vm_wind_field.js  the VM's wind read, off the scene's published wind field
-  shaders/chunk_particle_simulate_step.js one particle's simulate, shared by both simulate shaders
-  shaders/chunk_particle_emit_step.js     one newborn's emit, shared by both emit shaders
-  graph/ParticleNodeDescription.js   node type base (ports + lowering)
-  graph/ParticleNodeRegistry.js      standard node library (a NodeRegistry)
-  graph/particle_graph_authoring.js  authoring sugar over core/model/node-graph
-  graph/compile_particle_graph.js    graph → Program (register alloc, const intern)
-  layout/ParticleLayout.js           particle field schema ↔ record word offsets
-  data/PARTICLE_EMITTER_STRUCT.js    the emitter row + flag/blend/projection encoding
-  data/particle_emitter_record.js    emitter + context -> one row of that struct
-  data/PARTICLE_EMITTER_STATE.js     the GPU-owned per-emitter state row (second table of the database)
-  data/PARTICLE_DATABASE_SPEC.js     the GPUDatabase schema, and the emitter table's descriptor
-  data/PARTICLE_FIELD_BINDING.js     a transform binding row (third table of the database) + channels
-  data/PARTICLE_COUNTERS.js          counter slot indices
-  data/particle_header.js            record header encoding (row + generation), JS + WGSL
-  coherence/particle_program_buckets.js  CPU reference for the simulation-order bucketing
-  coherence/shader_particle_bucket.js    reset / histogram / pad / scatter / fill
-  coherence/graph_particle_bucket.js     frame-graph wiring, around graph_prefix_scan_csdldf
-  runtime/ProgramHeap.js             the one packed [header][constants][code][fields] buffer, allocator-backed
-  runtime/ParticleGlobalFields.js    the global field layout: append-only, addressed from zero
-  runtime/ProgramPlacement.js        where one program sits in it — what an emitter record carries
-  runtime/ParticleEmitter.js         one emitter — authoring data for an effect, with no GPU in it
-  runtime/GPUParticleEmitterContext.js  what a registry assigns one: row, generation, placement, patch
-  runtime/EmitterRegistry.js         GPUDatabase(emitters) + the live emitters + their contexts + the program heap
-  runtime/create_particle_effect.js  layout + INIT/UPDATE graphs → compiled effect
-  shaders/shader_particle_spawn_commands.js  CPU bursts → pending spawns
-  shaders/shader_particle_emitter_tick.js    per-emitter spawn decision
-  shaders/shader_particle_emit.js            per-newborn INIT, sized by the scan
-  shaders/shader_particle_simulate.js        per-particle UPDATE + compaction + orphan kill
-  shaders/shader_particle_finalize.js        reset counters (+ budget) / build indirect args
-  shaders/shader_particle_field_bind.js      bound transforms → their fields, before the tick
-  shaders/chunk_particle_setup_context.js    VM builtins from the emitter's node, + the RNG seed
-  shaders/chunk_particle_emitter_age.js      the tick pass's running age, off the emitter_state table
-  shaders/chunk_particle_spawn_budget.js     take from the frame's spawn budget; both ticks spend it
-  warmup/warmup_schedule.js                  ticks and tick length for a batch of pre-warms
-  warmup/shader_particle_warmup.js           init / reset / tick over the host's queue / migrate
-  warmup/chunk_particle_warmup_step.js       one particle's advance: per-lane decode, jittered tick
-  warmup/shader_particle_warmup_advance.js   the advance over the fast file (+ _wide.js)
-  warmup/graph_particle_warmup.js            the loop, recorded on a frame that registered a pre-warm
-  shaders/chunk_particle_billboard_vertex.js the billboard vertex stage, shared by every draw
-  shaders/shader_particle_avboit_*.js        occupancy / splat / draw through AVBOIT
-  bounds/*                           the measured emitter box: accumulate, publish
-  graph_particles.js                 the simulation, to the draw args
-  graph_particles_avboit.js          the AVBOIT side channel: occupancy, splat, draw
-  GPUParticleSystem.js               the feature: owns the buffers, sweeps the scene, execute()
-  *.spec.js                          co-located tests (JS + emulator + software device)
-```
-
-## Testing
-
-- Pure JS: layout packing, assembler, register allocator, node compiler, heap/emitter/registry
-  bookkeeping (via `SoftwareGPUDevice`), the header encoding.
-- WGSL via emulator: VM opcode parity (JS vs WGSL), curve sampling, atlas+flipbook UV math,
-  billboard expansion, soft-depth fade, and every compute pass on small fixtures — the tick
-  (rate integration, generations, pending, budget, culling, page-group walk), emit (expansion over
-  the scan, node position, orphans), simulate, spawn commands, finalize, bucket. Each such spec
-  carries its own copy of the scaffolding: a real scene with a `GPUSceneContext` and a real registry,
-  laid out by `gpu_database_words` the way the GPU holds both databases, so the shaders read rows the
-  real writers wrote.
-- Multi-frame capstone (`particle_lifecycle.spec`): reset → commands → tick → (JS scan) → emit →
-  simulate across frames, with the GPU deciding to spawn, a CPU burst, the budget, and death.
-- Orchestration on `SoftwareGPUDevice`: `GPUParticleSystem.spec` (scene sweep, growth, uploads only
-  when needed, the ring, the `read_stats` decode), `graph_particles.spec` (pass sequence, indirect
-  sizing, the two lists, every persistent buffer imported exactly once), and the playground's
-  `particle_scene.spec` (the integration: geometry → hierarchy → particles → draw).
-- Cross-parity meta-tests: every ISA opcode implemented by both executors.
-
-Regression checks use the existing tools: seeded software-device buffer copies for list growth,
-recorded pass ordering for program edits, emulator math for blend/fade and unknown bounds, and real
-AssetManager/TextureAtlas bookkeeping with a stub image loader for asynchronous atlas lifetimes.
-No full software WebGPU implementation or cross-frame shader simulator is added. The emulator's
-`subgroupBroadcastFirst` is identity, so grouping correctness is checked at its input contract.
-
-End-to-end GPU is out of scope for node (no binary GPU dep); emulator + JS references give the
-coverage the brief asks for.
-
-### Emulator caveats discovered (all correct on real hardware)
-
-The in-repo WGSL emulator (unit-test tool, not GPU parity) has limitations the shaders are written
-around, documented in the memory note: `switch` case bodies are dropped (use if/else); repeated
-read-modify-write of one location across a loop is corrupted (RNG is verified in isolation, not
-through the interpreter loop); u32 multiply is imprecise for large operands (PCG can't be checked
-through it); `/` is FLOAT division, so integer division only truncates where the result is stored
-straight into a typed array — `(n + 63u) / 64u * 64u` reads as 66 there and 64 on a device, and a
-binary search's `mid` is a shift, not a divide; matrix column indexing (`m[0]`) is not evaluated,
-so an axis scale is read as `m * vec4(1,0,0,0)`. `array<atomic<u32>>` bindings are modeled as
-`{value}` objects in tests; a pass that binds the same buffer as plain `array<u32>` gets a
-`Uint32Array`. The scene context writes a row's `global` one publish behind (the hierarchy pass
-recomposes it on a device), so a node's matrix under the emulator is the one it had when its row
-was seeded.
-
-### Renderer integration
-
-Done: `Renderer.feature_particles_enabled` (off by default), `Renderer.particles(scene_ctx)` creating
-one system per scene context on first use, `simulate` recorded before the transparency pass and the
-system passed to the AVBOIT orchestrator as its side channel.
-
-### Lighting
-
-An emitter flagged `EMITTER_FLAG.LIGHTING` treats its colour as a diffuse albedo; an emitter without
-it is its own colour, which is what additive (emissive) emitters want and stay. The flag is read per
-fragment from the emitter record, so lit and unlit particles share one pipeline and one draw. All of
-it is evaluated per pixel (`chunk_particle_lighting`, the model in `chunk_particle_lighting_model`):
-a vertex need not be on screen, and one quad can span the frustum.
-
-- **Direct light comes from the froxel irradiance volume** (`volumetrics/chunk_volumetrics_irradiance_sh`),
-  which `shader_volumetrics_build_irradiance` writes: every directional, point and spot light at a
-  point jittered through the froxel every frame, shadowed, stored as luma SH2 + constant chroma (Metro's L1 YCoCg, 6 coefficients
-  in two `rgba16float` volumes, since `rg16float` is not a storage format without
-  `texture-formats-tier1`). The volume rides the orchestrator to side channels as
-  `volumetrics_irradiance`. Resolution is the fog's froxel grid — 16 px tiles and 64 slices — so light
-  and shadow edges inside a particle are soft. idTech 8 builds the same volume (Sousa, SIGGRAPH 2025,
-  p.29); Ghost of Tsushima lights particles from its haze grid the same way. idTech 8 builds it in the
-  pass that lights its fog, and this one did too until 2026-10-09, dimming each light by the medium
-  on its way in. That tied particle lighting to the fog's whole chain (media, sun cascades, sky LUTs),
-  so the fog could not be skipped in a scene without volumes. It now has its own pass with no medium
-  in it: a lit particle is lit as the surfaces beside it are, which the deferred and forward paths
-  never dimmed either, and the fog is composited over both. Chosen over per-pixel forward shading (UE's most expensive mode, and a
-  flat card lit that way goes black from behind), per-vertex/per-particle lighting (the light
-  clusters are screen-space: a point off screen has no light list, the artefact that moved idTech 8
-  off it) and a per-particle lighting atlas (DOOM 2016, CoD IW: best-looking, but it needs a
-  world-space light lookup this engine does not have).
-- **The SH is evaluated at the normal and the irradiance clamped at zero.** One light gives
-  `E max(0, 1/4 + cos/2)`. SH2 cannot keep two lights apart: a light's lobe is `-E/4` facing away
-  from it, so a light behind a particle subtracts from the ones in front before the clamp sees a
-  total. Measured on the bonfire before transmission, the moon behind the smoke brought the fire-lit
-  side down to about half (display red 10 against 21).
-- **Chroma has no direction**: two lights of different colours from opposite sides tint both sides
-  their mix. Measured on the bonfire, the blue moon moves the fire-lit underside of the smoke from
-  (22.9, 5.3, 1.5) to (15.9, 4.7, 2.6) in display values; a same-coloured moon only brightens it.
-- **Indirect light is in the same volume**, whatever the renderer's `indirect_lighting_mode`. The
-  froxel GI stage (`volumetrics/gi/`) starts the volume with one concrete module per mode — IBL,
-  Brick4, LPV — each asking its source what radiance arrives at the froxel's centre, as RGB SH2,
-  and `shader_volumetrics_build_irradiance` adds the lights to that. The particle knows no mode: a new
-  GI system is one more module. IBL's source is `GPULightCollection.environment_sh`, the
-  environment projected to radiance SH2 when it changes (`shader_project_environment_sh`); Brick4
-  interpolates its probes (SH3, truncated) with a zero normal, which weighs every probe of the
-  brick alike; LPV interpolates the tetrahedron the froxel falls in, and gives nothing outside the
-  mesh, as the deferred LPV pass does. Measured at 1898x926 (RTX 4090): the IBL module 5-6 us, the
-  Brick4 module 31 us over an empty map. Reading the environment per pixel instead, as the forward
-  mesh path does, had been 880 us of lighting's 1,090 us — the particle draw is all overdraw.
-- **Back-face transmission** (Persson, "Practical Particle Lighting", GDC 2012, pp.34-37): the same
-  light evaluated at `-normal`, passed on in proportion to `1 - alpha`. The dense core of a puff
-  holds light from behind back and its thin edges let it through — smoke backlit by the moon has an
-  edge instead of being black. It costs nothing measurable: the draw is bound by its texture reads.
-- **The normal** is the quad's own plane — the face of the basis its mode and orientation lay it
-  on — turned to the side the eye is on and bent out toward the corners
-  (`particle_billboard_normal`), so a sprite shades as a puff, and a turned one as it turns.
-- **The directional light skips the atmosphere's transmittance** the fog applies: meshes are lit by
-  `sun.color` as it stands, and a lit particle has to agree with the surface beside it.
-
-Cost, bonfire (~1,300 live, smoke and soot lit), RTX 4090, lit minus unlit p10 in one page: the
-draw +90..275 us at 1898x926 (of ~450) across runs, +0.8..1.2 ms at 3818x2006 (of ~2.1 ms). The fog pass does
-not get slower for the two extra stores — paired against the tree before it, it measured 77 vs 89 us
-and 280 vs 320 us, reason not established. The volume has no temporal filter of its own: with the
-simulation frozen, lit and unlit smoke change equally from frame to frame even with the screen TAA
-off (0.09 vs 0.09 mean display units). That scene has no shadow edge through the smoke, which is
-where a one-sample-per-froxel volume would show it first.
-
-Open: a particle does not shade the fog or other particles (the volume holds no particle density).