@woosh/meep-engine 3.60.4 → 3.60.6

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

@@ -1,280 +0,0 @@
-# Particle, emitter and global fields — scope (2026-10-29, revision 4)
-
-**Status: landed.** `DESIGN.md` (*Vocabulary: fields*, *Emitter fields*, *Global fields*, *Transform
-bindings*) describes what was built. This is the scope as proposed. The **Outcome** section at the
-end lists where the build departs from it, and the measurements.
-
-**The model.** The program is the class and the emitter is an instance.
-- The class declares the fields every instance carries, and the global fields it reads.
-- The instance holds the values.
-- The class's own data — code, the constant pool, its bucket — is never touched by an instance.
-
-**Rejected alternatives:**
-- fixed 32-word emitter rows, in favour of general allocation;
-- GPU-integrated emitter state: values are static or set by gameplay, which the GPU cannot see;
-- a copy of the class for every set of instance values.
-
-## Vocabulary
-
-| scope | term | engine's own members | read by |
-|---|---|---|---|
-| particle | `particle_field` (was "attribute") | none (by design) | `LOAD_PARTICLE_FIELD` / `STORE_PARTICLE_FIELD` |
-| emitter | `emitter_field` | `EMITTER_POSITION`, `_DIRECTION`, `_UP`, `EMITTER_AGE` | `LOAD_BUILTIN` |
-| system | `global_field` | `TIME`, `DELTA_TIME` | `LOAD_BUILTIN` |
-
-**What the rename covers.**
-- **Renamed:** `ParticleLayout`'s entries, the `ParticleEffect` / `ParticleEmitter` API, the editor,
-  the graph node types (`particleField` / `setParticleField`), and the documentation.
-- **What keeps loading:** the graph JSON keys node types by name, and those names are wire format,
-  so `attribute` and `setAttribute` still load as aliases.
-- **Unchanged:** the binary effect format writes a layout's field names, widths and tags, and no
-  vocabulary words, so it does not change.
-- **The mnemonics** become `LOAD_PARTICLE_FIELD` / `STORE_PARTICLE_FIELD`, on the opcode numbers they
-  already have. `LOAD_ATTR` / `STORE_ATTR` text still parses, the precedent being legacy `SWIZZLE`
-  text.
-
-## Format
-
-- **The class declares its `emitter_field`s as a `ParticleLayout`**: name, width, an optional `type`
-  tag, and a default each. It sits on `ParticleProgram` beside the particle layout.
-  - Declaration order is wire format, the same rule as for particle fields.
-- **The class declares the `global_field`s it imports**: a name and a width each.
-- **The system's global layout is the union of what it holds.**
-  - It is append-only, and capacity only rises.
-  - Game code may declare names up front.
-  - A global field nobody has set reads 0.
-
-## Storage: a third region of `ProgramHeap`'s buffer
-
-**`ProgramHeap` already is this.**
-- Its sections are `ProgramRegion`s over flat word arrays, each managed by an `OffsetAllocator`.
-- It packs them into one buffer, `[header][constants][code]`, which every pass running the VM already
-  binds.
-- It repacks when a section has no run long enough, and capacities only rise.
-- A repack moves `placement_version`, and that restages every emitter row.
-
-The fields are a third region:
-
-```
-[header][fields: global (reserved) | emitter blocks][constants][code]
-```
-
-- **Global fields are always addressed from 0.** They take the region's top, reserved at 16 KiB
-  (4,096 words), so they never move.
-- **Each instance's `emitter_field` block is one allocation**, sized to its class's layout.
-  - The emitter record carries `field_offset`, the block's start within the region. The record writer
-    fills it from the instance's context, beside the program placement.
-  - An instance whose class declares no emitter fields allocates nothing.
-- **The header gains a word for the field base**, beside the code base it already holds.
-- **No storage binding is added.**
-  - Emit and simulate stay at eight, and their wide twins at nine, inside the device floor of ten.
-  - A buffer of its own would put the wide twins at ten, the floor itself.
-  - This was the deciding cost.
-- **Upload goes by span.**
-  - Today a placement re-uploads the whole buffer, which is right for code, because code changes
-    rarely.
-  - Field values change with gameplay, so the fields region uploads its changed spans through the
-    engine's existing small-write upload path (small writes batched in blocks, mapped from 32 KiB up).
-  - A repack or growth still rebuilds the whole buffer, as today.
-- **Authority.** The VM reads the buffer and never writes it. The CPU writes values. The binding pass
-  (below) writes the words that are bound.
-
-## Reading
-
-- **`LOAD_BUILTIN` gets two convention ranges above the engine's ids:**
-  - `VM_BUILTIN_EMITTER_FIELD_BASE + word offset`;
-  - `VM_BUILTIN_GLOBAL_FIELD_BASE + import index`.
-  The component count rides in `s1`, as `LOAD_PARTICLE_FIELD` carries it, and lanes past it read 0.
-- **`vm_load_builtin`'s default case calls two host functions.** They follow the external-symbol
-  pattern `particle_vm_sample_wind` already uses: `particle_vm_load_emitter_field` and
-  `particle_vm_load_global_field`. Every host defines them: emit, simulate, their wide twins, and the
-  warm-up advance.
-- **An `emitter_field` is read per lane.**
-  - The emitter row comes from the record header, then `field_offset` from the row, then the words.
-  - Nothing new is held across the interpreter loop, so `vm_ctx` does not grow.
-  - A field read is two dependent reads. Whether to hold `field_offset` in `vm_ctx` instead is decided
-    by the measurement below, not by argument.
-- **A `global_field`'s address is the same in every lane**, so it is a scalar read.
-- **Buckets, the constant pool and wave-uniform decode are untouched.**
-
-### Linking global fields
-
-- Programs are durable content, compiled with no scene present, so a global field's offset cannot be
-  baked in.
-- The operand is an index into the program's import table.
-- `ProgramHeap` rewrites it to the global field's offset when it copies the code into place, which
-  it already does.
-- The heap stays keyed on the unpatched bytecode.
-- Appending a global field moves nothing.
-
-## Transform bindings
-
-- **What they are.** A binding names a `transforms` row, a field and a channel. The GPU writes that
-  row's composed `global` into the field every frame.
-- **What that gives.** A beam's far end, a homing target, a second bone: any transform can drive a
-  field with nothing copied through the CPU. That is what the emitter's own `node` already does for
-  `EMITTER_POSITION`, and it works for a row only the GPU composes, such as an animated joint.
-
-**Storage: a `field_bindings` table** in the particle database. It is CPU-staged and low-churn, which
-is what `GPUDatabase` is for.
-- `source` is a link to the scene's `transforms` table, non-owning, exactly like the emitter record's
-  `node` (`PARTICLE_DATABASE_SPEC.add_link`).
-- `target` is a word address in the fields region. It may be a global field or a word of an emitter
-  block, which is one rule for both scopes.
-- `channel` says what is written:
-
-  | channel | width | from `global` |
-  |---|---|---|
-  | `POSITION` | 3 | the origin, as `EMITTER_POSITION` |
-  | `DIRECTION` | 3 | normalised −Z, as `EMITTER_DIRECTION` |
-  | `UP` | 3 | normalised +Y, as `EMITTER_UP` |
-  | `ORIENTATION` | 4 | a quaternion, as the `orientation` channel takes it |
-
-  The channel width must equal the field's width, and the system refuses the binding otherwise.
-- Targets are restaged when `placement_version` moves, the rule every row already follows.
-
-**The pass: `shader_particle_field_bind`.**
-- One thread per binding row, walked with the table's page iterator, as the tick walks emitters.
-- It reads `scene_read_node(source).global`, the same read `chunk_particle_setup_context` makes, and
-  writes the channel's words into the fields region. The program buffer is bound read-write here and
-  only here.
-- It runs once a frame, after the hierarchy pass has composed the rows and before the tick.
-- The host skips the dispatch while the table is empty.
-
-**Authority.** A bound word is recomputed from scratch every frame.
-- That is the argument that lets the scene's `transforms` table mix CPU fields with a GPU-written
-  `global` (DESIGN.md, *The emitter state*), and it holds here.
-- The CPU's value for a bound field is its default until the first bind.
-- A span upload or a buffer rebuild that lands on a bound word is overwritten before any VM pass
-  reads it.
-
-**ECS.**
-- `ParticleEffect.bindings`: `[{ field, entity, channel }]`, an entity reference, never a row. The
-  system resolves it with `row_of_entity` and holds the row through the scene context's rows, as it
-  does for the emitter's own placement.
-- `GPUParticleSystem.global_fields.bind(name, entity, channel)` does the same for global fields.
-
-## Everything else it touches
-
-- **Optimizers.** `LOAD_BUILTIN` is already a pure read. Width inference has to take a field's width
-  from `s1` rather than from `VM_BUILTIN_COMPONENTS`, and the fuzzer must generate both ranges.
-- **Reference VM.** The host passes `emitter_field` and `global_field` words as it passes the builtins
-  today.
-- **Graph.** New node types, appended at the end of `ParticleNodeRegistry.js`:
-  - `emitterField` (name, type, default);
-  - `globalField` (name, type).
-  Widths are validated per name.
-- **ECS values.**
-  - `ParticleEffect.emitter_fields`: values by name, as `Uint32` bit patterns. Compare-to-last covers
-    them, and a change marks the span dirty. It is not a restage, since a block does not move.
-  - `GPUParticleSystem.global_fields.set(name, value)` does the same for global fields.
-- **Serialization.** The emitter-field layout and the imports ride in the program; values and bindings
-  ride on the effect. `ParticleEffect` goes to v3, with an upgrader that gives old saves none.
-
-## Cost
-
-- **A static value:** written once, when the block is allocated. Nothing per frame.
-- **A changed value:** one span upload. No restage, no rebucket, no program change.
-- **A binding:** one thread a frame, plus one dispatch (a tiny pass measures 5–8 µs here)
-  while any binding exists.
-- **On the GPU:**
-  - an `emitter_field` read is a header reload, a row read and up to four loads;
-  - a `global_field` read is one scalar read;
-  - an effect that reads neither pays nothing that executes.
-
-## What gets measured
-
-- **The interpreter's register footprint.** Simulate and emit compiled through Dawn, before and after,
-  on RDNA2 offline. The default case grows the static code. The gate is no VGPR change.
-- **The cost of an `emitter_field` read.** At 200k alive, on the 4090 and the iGPU, paired in one
-  page:
-  - the effect reading one field per particle, against the same effect reading a constant;
-  - the same pair with `field_offset` held in `vm_ctx`.
-  The cheaper of the two read paths is kept.
-- **The bind pass**, at 1 and 1,000 bindings.
-
-## Stages
-
-Each stage lands red-then-green.
-
-| stage | what lands | pinned by |
-|---|---|---|
-| V0 | the vocabulary rename; old graph node names and mnemonics load as aliases | every existing graph and assembly spec green, plus a saved graph using `attribute` loading |
-| E1 | fields region, `field_offset`, emitter-field layout, `LOAD_BUILTIN` emitter range in both executors, graph node, `ParticleEffect.emitter_fields`, span upload, v3 | two bonfires differing only in flame tint: one program, one bucket, two blocks; a value change uploads one span and moves no program id |
-| G1 | global reservation, imports, link at placement, global range, `global_fields.set` | a global field changes a running effect without restaging an emitter row |
-| B1 | `field_bindings`, the bind pass, the ECS and global bind API | a beam whose far end follows an animated joint the CPU never sees |
-
-## Outcome (2026-10-29)
-
-Landed as revision 4 describes, in four commits — V0 `b8d14148e`, E1 `66031919d`, G1 `f93d1d2e0` and
-B1 `3dd4b7ce7` — and the adversarial review's fixes, `a14459252`, with these departures:
-
-- **Emitter fields are declared by the effect's document, as particle fields are**, and the
-  `emitterField` node reads one by name; the node does not declare. The same for global imports.
-  The emitter layout sits on the effect and the emitter (`emitter_layout`), not on `ParticleProgram`.
-  Values are `Uint32` words in layout order (`emitter_fields`), not a map by name.
-- **The fields are the buffer's fourth section**, `[header][constants][code][fields]`, not a region
-  between the header and the constants.
-- **The VM reads fields inline** in `LOAD_BUILTIN`'s field branch. There are no host functions
-  `particle_vm_load_emitter_field` / `particle_vm_load_global_field`.
-- **Global bindings go through the registry and the ECS system**: `EmitterRegistry.bind_global_field`
-  and `GPUParticleEmitterSystem.bind_global_field`. There is no `GPUParticleSystem.global_fields.bind`.
-- **The bind pass runs after the counter reset**, before the spawn commands and the tick.
-- **A field read takes the instruction's width in words**, as `LOAD_CONST` does, rather than a
-  component count in `s1`: the compiler emits a field at its own width, and `LOAD_BUILTIN`'s operand
-  list — and so every saved assembly text — stays as it was.
-- **`field_offset` is held in `vm_ctx`**, beside `emitter_position`, rather than re-read from the
-  emitter row inside the opcode. The re-read form was not built: the measured cost below is the
-  address being per-lane, and a row found through the particle's own header is per-lane too.
-- **A value change restages the emitter's row** as well as writing its span — the registry's existing
-  path — rather than the span alone.
-- **v3 of `ParticleEffect` carries the program's global imports**, written in E1 so the format bumped
-  once.
-- **Transform bindings on the component are runtime data and not saved**: nothing in the engine's
-  saves carries an entity reference across a load.
-
-**Measured (2026-10-29, at `a14459252`'s code).** Headless Chrome, one device per run. The two arms are two
-particle systems in one page, frames interleaved and the order alternating. Times are GPU timestamps,
-p10, over 1,200 frames on the 4090 and 300 on the iGPU. The emitter tick is the control and reads the
-same in both arms throughout.
-
-- **An `emitter_field` read at 200k alive.** The effect is `position += drift * dt`: six
-  instructions, where `drift` is a 3-wide emitter field in one arm and a 3-wide constant in the
-  other. Simulate:
-
-  | | constant | field | field / constant |
-  |---|---|---|---|
-  | RTX 4090, 2 runs | 132–134 µs | 135–137 µs | 1.008, 1.039 |
-  | Radeon iGPU (RDNA2), 7 runs | 1,893–1,952 µs | 2,111–2,204 µs | 1.111–1.131 |
-
-  On the iGPU that is about 1.1 ns per particle per read: an eighth of a program this short. **The
-  cause is that the address is per-lane.** Simulate's waves are one program, not one emitter, so
-  `vm_ctx.emitter_field_offset` reaches the read per-lane while the constant pool's base arrives
-  wave-uniform. Two experiments show it:
-  - broadcasting the offset from the first lane, valid only in this one-emitter page, brings the ratio
-    to 0.996 and 0.997;
-  - hoisting the header word out of the loop changes nothing (1.117, 1.096).
-- **A guarded broadcast was measured and not kept.** It reads at the first lane's offset when
-  `subgroupAll` says every lane agrees, and per-lane otherwise. Field-reading programs ran 0.985–0.996
-  of the constant arm. But every program without a field read slowed by 2.6–3.6%: 2,001–2,021 µs
-  against 1,949–1,952 µs, in three HEAD/fix pairs run back to back. The cost is there even though such
-  a program never takes the branch. Most effects read no field, so the common case would pay.
-- **The bind pass**, POSITION bindings:
-
-  | | 1 binding | 1,000 bindings |
-  |---|---|---|
-  | RTX 4090, 2 runs | 2.05 µs | 2.05 µs |
-  | Radeon iGPU, 2 runs | 2.20–2.24 µs | 5.44 µs |
-
-  On the 4090 both arms read the same as the emitter-tick control. On the iGPU, 999 more bindings add
-  3.2 µs.
-
-**Not measured:** the interpreter's register footprint. amdspv and spirv-as are not installed on this
-machine. Every VM pass and the bind pass compile and build pipelines under Tint on both GPUs.
-
-## Sources
-
-- Niagara Emitter and System parameter namespaces (with User values beside them) and Parameter Collections (globals bound by name).
-- [Niagara key concepts (namespace read/write table)](https://dev.epicgames.com/documentation/unreal-engine/key-concepts-in-niagara-effects-for-unreal-engine)
-- [VFX Graph instancing](https://docs.unity3d.com/Packages/com.unity.visualeffectgraph@17.2/manual/Instancing.html)
-  — instances share code and load their properties per instance.