@woosh/meep-engine 3.47.0 → 3.49.0

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

@@ -0,0 +1,453 @@
+# Particle orientation — scope (2026-10-15, revision 2)
+
+Arbitrary rotation for GPU particles, with every projection mode kept, BILLBOARD included.
+
+**Revision 2** follows Alex's review of revision 1.
+
+- **Roll goes through the quaternion.** The scalar `rotation` channel is deleted rather than kept
+  beside the new one.
+- **The u32 quaternion is placed by measurement.** The codec is measured (below), and it belongs on
+  the render side, not in the particle record.
+- **The pre-pass is answered.** Writing back into the record is out. A per-view pass with an output of
+  its own is the right shape, and it is gated on a measurement.
+- **The stretch moves inside the quad's own axes.** That turns every projection mode into one
+  function that produces a world rotation.
+
+## Outcome (2026-10-16)
+
+Landed as revision 2 describes, in four commits: the frame fix, the channel, the library, and this
+document with DESIGN.md and the bonfire. The departures from the plan:
+
+- **`randomRotation` is `sampleRotation`**, named like the sphere samplers it sits beside.
+- **The demonstrator is the soot, not an `ash` behind `?ash`.**
+  - The README already described the soot as "dark tumbling flakes", and a roll in the camera plane
+    was its stand-in.
+  - It is now FACING_WORLD: a `sampleRotation` at birth, a `tumble` axis at the speed its roll used to
+    spin at, and `quatIntegrate` every frame.
+  - That adds no new effect, flag or entity.
+- **Group costs are measured**, as the graph compiler lowers them (instructions / registers):
+  `quatMultiply` 22/15, `quatIntegrate` 39/17, `sampleRotation` 29/7, `emitterRotation` 105/28. The
+  estimates below (~9, ~17) were the hand count of an optimised body. These are pinned in
+  `particle_group_library.spec.js`.
+
+**Device results.** RTX 4090, headless Chrome, `?debug` stepping, this branch against its base
+`59861de99`.
+
+- **The draw does not move.** p10 over 240 profiled frames per launch, ABBA:
+
+  | pass | base | branch |
+  |---|---|---|
+  | Particle AVBOIT Draw | 239.6, 214.0 µs | 221.2, 219.1 µs |
+  | Particle AVBOIT Splat | 22.5, 27.6 µs | 23.6, 21.5 µs |
+  | Particle Simulate | 218.1, 218.1 µs | 218.1, 218.1 µs |
+
+  The same-tree spread of the draw is wider than any base-to-branch difference.
+- **With the soot running.** The soot's longer INIT read Emit at 54.3 against 46.1 µs, from one launch
+  each. That is a single pair and not a finding.
+- **Flame, smoke and embers look as they did.** Spawn order is not deterministic, so the same tree
+  differs from itself run to run: the base against itself is a mean |d| of 3.70 (and 3.58 for the
+  branch against itself). The base against the branch is 3.62 and 3.36, inside that floor. The soot is
+  removed for this comparison.
+- **The soot reads as flakes.** Same camera on the plume: the base draws round camera-facing dots, the
+  branch ellipses, slivers edge-on, and flakes face-on.
+- **A pre-existing console error.** "Worker error: ErrorEvent" logs in both trees. Vite names it: the
+  page's image-decoder worker, `build/bundle-worker-image-decoder.js`, is a build artifact a fresh
+  tree does not have.
+- **The shaders compile on Tint.** Draw, splat and bounds-accumulate compile with no messages on
+  swiftshader, and a control with a broken call is reported.
+
+### Pre-pass gate (2026-10-16): not built
+
+**Verdict: the per-view pass does not pay.** The whole vertex stage is worth about 2 µs at 121k
+particles. The cheapest pass that could replace it costs 9 µs. So the u32 rotation has no render-side
+home either, and stays unused.
+
+**The setup.** RTX 4090, headless Chrome, the bonfire page with `?debug`.
+
+- **The load.** The four effects are removed, and in their place one spark emitter of tiny additive
+  BILLBOARD quads: size 0.005, about 1.5 px, uniform in a 4 × 2 × 4 m box, about one second of life.
+- **Two counts.** About 121k live particles, and about 1.3k (the bonfire's count).
+- **The order.** Arms ABBAAB per load. p10 over 240 profiled frames per launch, after 240 frames of
+  warm-up. The timestamp tick is about 1 µs.
+
+**The three arms:**
+
+- **A — the vertex chunk as built.** It decodes the emitter row, reads the channels through the
+  bindings, and builds `particle_basis`.
+- **B — a floor no real consumer reaches.**
+  - It does no storage read at all: the instance index hashes to a position in the same box.
+  - Size, colour, flags and the white texel's UV are constants.
+  - The quad sits on the camera's axes, with no basis.
+  - It draws the same cloud as A.
+  - A − B is therefore an upper bound on what any view pass could take off the vertex.
+- **C — a floor no real pass gets under.** A standalone compute pass, one thread per live particle,
+  timed with timestamp queries in the same page. It reads a record's header and 8 words at a shuffled
+  slot and writes 8 words. It does no emitter decode and builds no basis.
+
+**The numbers** (µs):
+
+| load | pass | A | B | A − B | C |
+|---|---|---|---|---|---|
+| 121k | draw | 201.7, 202.8, 202.8 | 200.7, 201.7, 201.7 | ≈ 1.0 | 9.2–10.2 |
+| 121k | splat | 68.6 ×3 | 67.6 ×3 | 1.0 | |
+| 1.3k | draw | 7.2, 7.2, 8.2 | 7.2 ×3 | ≈ 0.3 | 3.1 |
+| 1.3k | splat | 4.1 ×3 | 3.1 ×3 | 1.0 | |
+
+The rule was to build only if A − B clears C. At 121k it is about 2 µs against at least 9.2. At 1.3k
+it is about 1.3 µs against 3.1.
+
+**Where the draw's time does go.** The draw does scale with the particle count: 7 µs at 1.3k, 202 µs at
+121k, about 1.6 ns a particle. Two findings bound it:
+
+- **Not the vertex stage.** The table above shows that.
+- **Not the shading after the extinct test** (one launch). A B whose every fragment was discarded at
+  the empty-colour test read the same 200.7 / 67.6 µs. Its UV pointed at an empty texel by mistake, so
+  those fragments skipped the volumetrics, the contribution and all four accumulator writes.
+
+What remains is rasterising a quarter-million one-pixel triangles plus the fragment's first two
+samples (transmittance and atlas). That attribution is not measured.
+
+Bench, driver and arms: session scratchpad `gate/`; none of it is committed.
+
+## Where it stands
+
+- **One vertex chunk draws every particle.** `chunk_particle_billboard_vertex` reads a record through
+  the emitter's render bindings. Both AVBOIT passes call it: the splat and the draw.
+- **How a corner is placed.** `particle_billboard_offset` rolls the corner by the scalar `rotation`,
+  then lays it on two axes the projection mode picks. `particle_billboard_normal` picks the face in a
+  second, separate per-mode switch.
+- **The VM is view-independent.** There is no camera builtin. One simulation serves every view and
+  the warm-up, so "face the camera" cannot be a program. It has to stay something the renderer applies
+  per view.
+- **FACING_WORLD was meant for this.** Its comment says "oriented by the particle's own rotation
+  attribute in world space", but it only ever got a roll about world Z.
+- **Bounds are already orientation-free.** `particle_billboard_radius` is √2·size, times (1 + |v|)
+  under STRETCHED, and a rotation keeps every corner inside that sphere.
+- **The quaternion pieces exist on both sides.**
+  - Graph library: `quatFromAxisAngle`, `quatLookRotation` (maps +Z to `forward` and +Y to `up`) and
+    `quatRotate`, all x, y, z, w with w last.
+  - Shaders: `quat_rotate_v3`, `quat_from_m3`, and `quat_encode_u32` / `quat_decode_u32`, which have
+    JS twins held to the WGSL by `quat_encode_u32_parity.spec`.
+- **Room in the record.** Records are a fixed 32-word stride, and the bonfire's layouts use 16 of the
+  31 user words.
+
+### Found while scoping: three of five frames draw the mirror image (measured)
+
+Measured on the emulator with the real `particle_billboard_offset`, corners (1, 0) and (0, 1). The
+camera is at +Z looking −Z unless the row says otherwise.
+
+| mode | local +X lands | local +Y lands | front (x × y) |
+|---|---|---|---|
+| BILLBOARD | screen right | screen up | toward the eye |
+| FACING_WORLD | world +X | world +Y | world +Z |
+| STRETCHED, v = 0 | screen **left** | screen up | **away** |
+| STRETCHED, v along screen right | screen up | screen right (×3) | **away** |
+| VERTICAL | screen **left** | screen up | **away** |
+| HORIZONTAL, seen from above | screen right | screen **down** | **world −Y** |
+
+- **What it means.** STRETCHED, VERTICAL and HORIZONTAL (seen from above) draw the mirror image of
+  BILLBOARD, and roll turns the opposite way in them.
+- **Why nothing caught it.** The offset spec checks STRETCHED's cross axis with `Math.abs` and has no
+  VERTICAL case. `particle_billboard_normal` turns every face toward the eye afterwards, which hides
+  HORIZONTAL's.
+- **Why it blocks this work.** A rotation composed inside a mirrored frame turns the wrong way about
+  every axis.
+- **The three causes:**
+  - STRETCHED's `perp = (-dir.y, dir.x)` wants `(dir.y, -dir.x)`.
+  - VERTICAL's `cross(up, cam_forward)` wants `cross(cam_forward, up)`.
+  - HORIZONTAL's up `(0, 0, 1)` wants `(0, 0, -1)`.
+- **What changes on screen.** No effect in the tree uses VERTICAL or HORIZONTAL. The STRETCHED sparks
+  are round and bind no roll.
+
+## The design
+
+**The record says how a particle is turned. The projection mode says how a view sees it. One
+function composes the two.**
+
+    W      = F(mode, camera, velocity) · Q
+    offset = W · (corner.x · size, corner.y · size · k, 0)
+    normal = W · ẑ, turned toward the eye, bent toward the corner as now
+
+The parts:
+
+- **`Q`, the `orientation` channel**, the only rotation a particle has.
+  - A 4-component attribute holding a unit quaternion (x, y, z, w), in the mode's frame.
+  - Normalised at the draw; unbound reads as the identity.
+  - A zero quaternion is also the identity, with no branch: `q * inverseSqrt(max(dot(q,q), tiny))`
+    stays zero, and `quat_rotate_v3(0, v) == v`.
+  - A roll is `quatFromAxisAngle(+Z, θ)`, and nothing else.
+- **`F`, the mode's frame.** A proper rotation whose +Z is the side the mode shows (table below). It
+  is the mirror fix and the only thing a mode contributes besides `k`.
+- **`k`, STRETCHED's elongation**, `1 + |v_screen|`, and 1 in every other mode.
+  - It now stretches the sprite along **its own** +Y.
+  - With `Q` the identity, that is the same quad as today.
+  - With `Q` turned, the streak turns with the sprite rather than being sheared inside a
+    screen-aligned envelope. That fits better: the mode aims the sprite, and the elongation belongs to
+    the sprite.
+  - It also makes the normal exactly `W · ẑ`, with no inverse-transpose.
+- **`corner`, the canonical quad.** Local +X is the edge BILLBOARD draws on the right, +Y the edge it
+  draws at the top, +Z the side it shows the eye.
+
+| mode | F.x | F.y | F.z (front) |
+|---|---|---|---|
+| BILLBOARD | camera right | camera up | toward the eye |
+| STRETCHED | screen velocity turned −90° in the camera plane (camera right at rest) | screen velocity (camera up at rest) | toward the eye |
+| VERTICAL | `normalize(cam_forward × +Y)`, world +X looking straight down | world +Y | horizontal, toward the eye |
+| HORIZONTAL | world +X | world −Z | world +Y |
+| FACING_WORLD | world +X | world +Y | world +Z |
+
+**The modes are now one function**, `particle_view_rotation(mode, camera, velocity, q) → {W, k}`.
+The vertex calls it once, and neither offset nor normal has a switch of its own. That is the shape a
+pre-pass would host, and it does not change if one is built (see below).
+
+**What an orientation means in each mode:**
+
+- **FACING_WORLD + orientation is the feature**: a quad turned any way in the world.
+- **BILLBOARD + orientation is a rotation relative to the view.** A roll is the case every existing
+  effect uses. A tilt is a card that flips toward the eye. Unity's VFX Graph composes its element
+  matrix the same way, `[axisX|axisY|axisZ] · R(angles) · S`, with angleX/Y tilting relative to the
+  camera under FaceCameraPlane (`VFXCommon.hlsl`, `GetElementToVFXMatrix`).
+- **STRETCHED, VERTICAL and HORIZONTAL + orientation**: a rotation inside those frames. Nothing needs
+  a rule for them.
+
+**Bounds do not change.**
+
+    |W · (c.x·size, c.y·size·k, 0)| ≤ √2 · |size| · k
+
+That is `particle_billboard_radius` as it stands, because `k ≤ 1 + |v|`. The bounds pass never reads
+the channel.
+
+**The VM does not change.** No opcode, no builtin, no mode ([[particle-vm-isa-stays-primitive]]).
+
+**AVBOIT needs nothing new.** Turned quads run through depth across a voxel as HORIZONTAL and
+FACING_WORLD quads already do, and the draw has applied `avboit_footprint_bias` to them since
+ledger 26.
+
+### Why roll goes (Alex's point, and he is right)
+
+Revision 1 kept `rotation` beside `orientation` on a cost argument: one word and one MAD a frame
+where a quaternion is four words and a sine and a cosine. That cost is about four VM instructions per
+particle, next to effects that spend hundreds on noise.
+
+- **The program keeps its angle.** Spin stays a scalar state attribute (`spin += rate · dt`), and the
+  program writes `quatFromAxisAngle(+Z, spin)` to the channel.
+- **What it costs the bonfire.** Flame, smoke and soot go from 16 to 20 words of 31.
+- **What it buys.** Two rotation channels composed in a fixed order is two ways of saying one thing,
+  plus an ordering rule. One channel is one rotation.
+
+### The u32 quaternion: on the render side, not in the record (measured)
+
+The engine's codec is Bungie's smallest-three: a 2-bit index and three 10-bit components.
+
+**As a render format it is invisible.** Over 200,000 uniform random rotations, the round-trip error is
+median 0.085°, p99 0.150° and max 0.244°. At the corner of a 1 m quad, that is at most 3 mm.
+
+**As state a program integrates, it fails.** The test re-encodes every frame for 10 s with an exact
+axis-angle step, over 200 random starts and axes:
+
+| spin | fps | frames that did not move | turned / asked (median) | final error (median, p90) |
+|---|---|---|---|---|
+| 0.1 rad/s | 60 | 84.5 % | 0.001 | 57°, 57° |
+| 0.3 rad/s | 60 | 0 % | 0.963 | 22°, 33° |
+| 1 rad/s | 60 | 0 % | 1.000 | 7.5°, 12.7° |
+| 0.1 rad/s | 144 | 100 % | 0.000 | 57°, 57° |
+| 0.3 rad/s | 144 | 71.5 % | 0.294 | 124°, 172° |
+| 1 rad/s | 144 | 0 % | 0.974 | 30°, 52° |
+| 10 rad/s | 144 | 0 % | 1.000 | 5.9°, 10.3° |
+
+A falling leaf's tumble is exactly that slow range. It freezes, and how badly depends on the
+player's frame rate.
+
+**The VM also cannot carry the word.** Its registers are `f32` and it has no bit operations.
+
+- **Where a codec word goes wrong.** The identity rotation encodes to a word that reads as NaN as an
+  `f32`, and so does a 90° roll. About 0.46 % of uniform random rotations read as NaN or subnormal.
+- **Why that matters.** WGSL does not promise to preserve those bits through arithmetic or moves
+  (subnormals may be flushed). I have not measured a failure, but an f32 register is not a safe
+  carrier for them.
+- **What it would take.** An encode-at-store opcode: domain-specific, in the switch of the two passes
+  whose register pressure sets occupancy.
+- **What it would save.** Words of a fixed stride, so no memory: two words for a roll-only effect, and
+  for a tumbling one nothing, since it still needs its `f32` state.
+
+So the record carries `f32 × 4`, and the u32 lives wherever the world rotation is written down for a
+view, which is the next section.
+
+### The pre-pass
+
+Alex's suggestion: a pass that writes the quaternion under the camera-dependent modes and leaves it
+alone under the others, so the vertex only ever reads a quaternion. It splits in two.
+
+**Writing into the particle's own attribute: no.**
+
+- **The attribute is the program's state.** Next frame's UPDATE reads it back. A spin integrated on
+  top of the camera's rotation is garbage. The roll the program wrote is exactly what would be
+  overwritten, so roll could not go through the quaternion at all.
+- **Its owner would depend on the mode.** The renderer would own it under BILLBOARD and the program
+  under FACING_WORLD. That is a channel whose meaning depends on a flag, the same smell as a
+  parameter whose meaning depends on its type.
+- **One value cannot serve two views.** One view today. Not once shadows, reflections or a second
+  viewport draw particles.
+
+**A per-view pass with its own output: yes in shape, not yet in fact.**
+
+- **What it does.** One thread per alive particle per view, indirect over the alive count, calls
+  `particle_view_rotation`, encodes `W` with `quat_encode_u32` and writes it beside `k`. The vertex
+  then decodes and rotates.
+- **Why u32 belongs there.** The pass encodes once from the exact rotation, nothing integrates
+  through it, and the word never touches an `f32` register.
+- **Where the doubt is.** If it writes only the rotation, it removes about 30 ALU ops of frame math
+  per vertex. It still leaves the vertex decoding the emitter record and reading five channels through
+  the bindings. The price is a dispatch (5–8 µs floor on the 4090) and a write plus read per particle.
+- **Where it could earn its keep.** By resolving the whole draw input: position, size × k, rotation as
+  u32, colour, atlas rect for the current frame, and flags. Then the twelve vertex invocations a
+  particle costs each frame (six in the splat, six in the draw) read one compact record and never see
+  an emitter or a binding.
+- **What decides it.** The vertex stage's share of splat + draw at a vertex-heavy load, which nobody
+  has measured.
+
+**Decision:** land the channel with `particle_view_rotation` called from the vertex. Then measure:
+
+- **Load.** One page, paired, a vertex-heavy scene (about 200k small additive sparks).
+- **Arms.** Splat + draw as built, against a vertex whose record and emitter reads are replaced by
+  constants. That second arm is the floor of what any view pass can give the vertex.
+- **Plus.** A compute pass that touches alive × 8 words, which is the pass's own cost.
+- **Rule.** If the difference does not clear the pass's cost, the pass is not built.
+
+Nothing in the first step is thrown away either way. The record contract is the same, and the pass
+would move one call out of the vertex.
+
+### Library: graph groups, not opcodes
+
+The library already has `quatFromAxisAngle`, `quatLookRotation` and `quatRotate`, and gains four:
+
+- **`quatMultiply(a, b)`.** Turn by b, then by a, the same order as `Quaternion.multiplyQuaternions`.
+  About 9 instructions.
+- **`quatIntegrate(quat, omega, dt)`.** `quatFromAxisAngle(ω, |ω|·dt) ⊗ q`, renormalised, about 17
+  instructions, exact at any `dt`.
+  - **Rejected alternative:** first-order (`core/geom/3d/quaternion/quat3_integrate.js`, Catto),
+    which turns by `2·atan(|ω|dt/2)`.
+  - **Why it loses.** The warm-up's ticks reach 156 ms for a 5 s pre-warm (32 ticks at most), where
+    10 rad/s comes out 15 % short. DESIGN.md's warm-up rests on programs not caring what `DELTA_TIME`
+    they get.
+- **`randomRotation(uvw)`.** Uniform, after Shoemake (Graphics Gems III). It goes beside the sphere
+  samplers in `particle_graph_distributions.js`.
+- **`emitterRotation`.** It is `quatLookRotation(-EMITTER_DIRECTION, EMITTER_UP)`, and it carries the
+  sign. The builtin's direction is the node's −Z, so wiring it straight in shows the quad's back.
+
+Register peaks are pinned in `particle_group_library.spec.js`, all far under 48.
+
+**A tumbling flake:**
+
+- **INIT:** `orientation = randomRotation(random3)`, `spin = sampleSphereSurface(random2) · speed`.
+- **UPDATE:** `orientation = quatIntegrate(orientation, spin, dt)`.
+- **Cost:** seven words, about 17 instructions a frame.
+
+## Rejected
+
+- **A roll channel beside the quaternion** (revision 1). See "Why roll goes".
+- **u32 in the record, or a VM encode opcode.** See the measurements.
+- **The pre-pass writing into the record.** See "The pre-pass".
+- **Two vectors, facing + alignment** (Niagara sprites, PopcornFX PlaneAligned). Six words,
+  degenerate when parallel, and quad-only. `quatLookRotation` already builds the quaternion from that
+  pair.
+- **Euler angles** (Unity VFX). An order convention and gimbal lock.
+- **A rotation vector.** It saves one word of a fixed stride and costs trigonometry per vertex.
+- **Orientation honoured only in FACING_WORLD.** That is Godot's particle billboard, which keeps only a
+  roll. A channel's meaning would depend on the mode.
+- **A new ORIENTED mode.** FACING_WORLD with the identity is that mode.
+- **An emitter-local frame** (Shuriken "Local"). It needs the scene database in the draw.
+  `emitterRotation` does the same in INIT.
+
+Precedent, read from source: Niagara meshes, Niagara sprites, Unity VFX Graph and PopcornFX all
+compose the particle's rotation inside the facing frame. The mesh paths (Niagara `MeshOrientation`,
+PopcornFX `Orientation`, Houdini `orient`) store a quaternion.
+
+## Touch list
+
+Changes:
+
+- `shaders/chunk_particle_render_math.js`:
+  - New `particle_view_rotation`, with the three frame fixes.
+  - `particle_billboard_offset` / `_normal` reduce to `W · (corner ⊙ extent)` and `W · ẑ`.
+  - `particle_billboard_radius` is unchanged, and its comment gains the rotation argument.
+- `shaders/chunk_particle_billboard_vertex.js`: reads `render_orientation` (four words, identity when
+  absent) and drops `render_rotation`.
+- `data/PARTICLE_EMITTER_STRUCT.js`: `render_rotation` becomes `render_orientation`, and FACING_WORLD's
+  comment is updated. `data/particle_emitter_record.js` follows.
+- `runtime/ParticleEmitter.js` and `engine/graphics/ecs/particles/ParticleEffect.js`:
+  - In `EMITTER_RENDER_CHANNELS`, `rotation` (1) becomes `orientation` (4).
+  - The field, `bind_render`, `equals`, `hash`, `copy` and `from` follow.
+- `engine/graphics3/GPUParticleEmitterSystem.js`: the comparison in `apply_particle_effect`.
+- `ParticleEffectSerializationAdapter`:
+  - Goes to version 2, with `ParticleEffectSerializationUpgrader_1_2`.
+  - A v1 roll binding is dropped, because bytecode that writes an angle cannot be upgraded into
+    bytecode that writes a quaternion. A spinning v1 effect loads still, which is a hard break and
+    accepted ([[removing-deprecated-surface]]).
+- `playground/particle_ecs/effects/{flame,smoke,soot}.json` re-authored:
+  - A 4-word `orientation` attribute.
+  - `quatFromAxisAngle(+Z, spin)` written in INIT and UPDATE, bound to `orientation`.
+  - `bonfire.spec.js` pins the new binding.
+- `editor/particles/effect/ParticleReferenceSimulation.js`: `forEachParticle` stops reporting
+  `rotation`, which the preview never drew.
+- Graph groups, as listed under "Library", plus the editor palette's "rotation" row.
+- `DESIGN.md` §Rendering: the composition and the frame table.
+
+No change:
+
+- **The editor's emitter inspector.** It builds its pickers and width warnings from the channel lists.
+- **The bounds pass, occupancy, the VM, the ISA and the optimizer.**
+
+## Ledger
+
+Specs follow the house rules: plain `test()`, public API or what reaches the device, red first where
+the item is a fix.
+
+1. **Every mode shows the sprite as BILLBOARD does**: +X right, +Y up, front to the eye. Red today for
+   STRETCHED, VERTICAL, and HORIZONTAL seen from above.
+2. **An orientation of `quatFromAxisAngle(+Z, θ)` turns counter-clockwise, seen from the front, in
+   every mode.**
+3. **Unbound orientation draws today's quad** (after 1), in every mode.
+4. **Two placements check the composition:**
+   - FACING_WORLD with a quarter turn about +X lays the quad in world XZ.
+   - BILLBOARD with one fixed orientation gives the same screen picture from three cameras.
+5. **STRETCHED with a turn elongates along the sprite's own +Y.**
+6. **Edge quaternions:** zero draws the identity, and 2q draws what q draws.
+7. **The normal is W·ẑ turned to the eye**, the plane normal of the drawn corners in every mode.
+8. **The bounds sweep gains random orientations.** A pin, expected green with no change.
+9. **The groups match CPU references:**
+   - `quatMultiply` matches `Quaternion.multiplyQuaternions`.
+   - `quatIntegrate` matches the closed form at dt 1/60 and 0.5, and stays unit after 10,000 steps.
+   - `randomRotation` gives E[qᵢ²] = ¼ and E[qᵢqⱼ] = 0.
+10. **Plumbing:** the channel lists, struct, record writer, emitter and component, and system apply;
+    serialization round trip; a v1 save loads with its roll binding dropped.
+11. **The bonfire's three effects bind `orientation`**, and still fit the fast register file.
+
+## Device check
+
+A one-off from the scratchpad on the headless driver. A few hundred frames.
+
+- **The bonfire.** It looks as it did, with flame, smoke and soot spinning through the quaternion. A
+  side-by-side against master says whether the spin direction matches. It should: none of the three
+  is a mirrored mode.
+- **`ash`.** Tumbling, lit FACING_WORLD flakes behind `?ash`. The flakes catching the fire as they turn
+  are the normal path working.
+- **Timings.** A paired A/B of the draw against master. The predicted difference is nothing
+  measurable, until a run says otherwise.
+- **The pre-pass gate.** The measurement described under "The pre-pass".
+
+## Order of landing
+
+1. **The frame fix** as `particle_view_rotation`, with `rotation` still the input. Ledger 1, and 2 in
+   its roll form.
+2. **The `orientation` channel replaces `rotation`** end to end: struct to serialization, plus the
+   bonfire re-authored. Ledger 3–8, 10, 11.
+3. **The library groups**, ledger 9.
+4. **DESIGN.md, `ash`, the device check, the pre-pass gate.**
+
+## Out of scope
+
+- **Mesh particles.** The channel is the one they would read.
+- **Non-square sprites.** `size` stays a scalar; `k` is the mode's.
+- **Per-particle locked-axis billboards.**
+- **The per-view pass itself**, until the gate says build it.

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

@@ -67,7 +67,11 @@ export const EMITTER_BLEND: Readonly<{
     ADDITIVE: 1;
     PREMULTIPLIED: 2;
 }>;
-/** Projection / orientation modes (stored in flag bits [6,9)). */
+/**
+ * Projection modes (stored in flag bits [6,9)): the frame a particle's quad is laid in. The
+ * particle's own `orientation` turns it inside that frame, so a mode is how a view sees the
+ * particle and the orientation is how the particle is turned.
+ */
 export const EMITTER_PROJECTION: Readonly<{
     BILLBOARD: 0;
     STRETCHED: 1;

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

@@ -1 +1 @@
-{"version":3,"file":"PARTICLE_EMITTER_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/PARTICLE_EMITTER_STRUCT.js"],"names":[],"mappings":"AAmIA;;;;;;;;;GASG;AACH;IAP6B,QAAQ,GAA1B,OAAO;IACW,UAAU,GAA5B,OAAO;IACW,IAAI,GAAtB,OAAO;IACU,KAAK,GAAtB,MAAM;IACW,UAAU,GAA3B,MAAM;IACJ,MAAM,CAUlB;AAED,6DAA6D;AAC7D,2CADY,MAAM,GAAkB,MAAM,CAGzC;AAED,kEAAkE;AAClE,gDADY,MAAM,GAAkB,MAAM,CAGzC;AA5JD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,sCAFU,YAAY,CA+DO;AAE7B,uDAAuD;AACvD,kDAAmD;AAEnD;;;;;;GAMG;AACH;;;;GAIG;AAEH,kGAAkG;AAClG;;;;GAIG;AAKH,kEAAkE;AAClE;;;;;;GAMG;AAmCH,uEAAuE;AACvE;;;;;GAEG;6BAnK0B,mCAAmC"}
+{"version":3,"file":"PARTICLE_EMITTER_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/PARTICLE_EMITTER_STRUCT.js"],"names":[],"mappings":"AA2IA;;;;;;;;;GASG;AACH;IAP6B,QAAQ,GAA1B,OAAO;IACW,UAAU,GAA5B,OAAO;IACW,IAAI,GAAtB,OAAO;IACU,KAAK,GAAtB,MAAM;IACW,UAAU,GAA3B,MAAM;IACJ,MAAM,CAUlB;AAED,6DAA6D;AAC7D,2CADY,MAAM,GAAkB,MAAM,CAGzC;AAED,kEAAkE;AAClE,gDADY,MAAM,GAAkB,MAAM,CAGzC;AApKD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,sCAFU,YAAY,CAmEO;AAE7B,uDAAuD;AACvD,kDAAmD;AAEnD;;;;;;GAMG;AACH;;;;GAIG;AAEH,kGAAkG;AAClG;;;;GAIG;AAKH;;;;GAIG;AACH;;;;;;GAMG;AAmCH,uEAAuE;AACvE;;;;;GAEG;6BA3K0B,mCAAmC"}

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

@@ -66,8 +66,12 @@ export const PARTICLE_EMITTER_STRUCT = WebGPUStruct.from({
     render_size: u32,
     /** attribute word offset of rgba colour */
     render_color: u32,
-    /** attribute word offset of roll angle, radians */
-    render_rotation: u32,
+    /**
+     * attribute word offset of the orientation: a quaternion (x, y, z, w) turning the sprite inside
+     * its projection mode's frame — in the world under FACING_WORLD, relative to the view under
+     * BILLBOARD, where a turn about +Z is a roll
+     */
+    render_orientation: u32,
     /** attribute word offset of flipbook frame index */
     render_frame: u32,
     /** attribute word offset of velocity (STRETCHED projection) */
@@ -117,13 +121,17 @@ export const EMITTER_BLEND = Object.freeze({
 const BLEND_SHIFT = 4;
 const BLEND_MASK = 0b11 << BLEND_SHIFT;
 
-/** Projection / orientation modes (stored in flag bits [6,9)). */
+/**
+ * Projection modes (stored in flag bits [6,9)): the frame a particle's quad is laid in. The
+ * particle's own `orientation` turns it inside that frame, so a mode is how a view sees the
+ * particle and the orientation is how the particle is turned.
+ */
 export const EMITTER_PROJECTION = Object.freeze({
     BILLBOARD: 0,          // face the camera
     STRETCHED: 1,          // billboard stretched along velocity
-    HORIZONTAL: 2,         // lie flat on the ground plane (XZ)
+    HORIZONTAL: 2,         // lie flat on the ground plane (XZ), facing up
     VERTICAL: 3,           // axis-locked to world up, yaw toward camera
-    FACING_WORLD: 4,       // oriented by the particle's own rotation attribute in world space
+    FACING_WORLD: 4,       // the world's own axes: the orientation is the particle's rotation in the world
 });
 
 const PROJECTION_SHIFT = 6;

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

@@ -59,7 +59,7 @@ export function write_emitter_record(record, emitter, context) {
     record.render_position = emitter.render_position;
     record.render_size = emitter.render_size;
     record.render_color = emitter.render_color;
-    record.render_rotation = emitter.render_rotation;
+    record.render_orientation = emitter.render_orientation;
     record.render_frame = emitter.render_frame;
     record.render_velocity = emitter.render_velocity;
 
@@ -93,7 +93,7 @@ export function create_emitter_record() {
         render_position: 0,
         render_size: 0,
         render_color: 0,
-        render_rotation: 0,
+        render_orientation: 0,
         render_frame: 0,
         render_velocity: 0,
 

package/src/shade/renderer/particles/graph/groups/particle_builtin_groups.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"particle_builtin_groups.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/particles/graph/groups/particle_builtin_groups.js"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;;GAQG;AACH,sCAFU,OAAO,yBAAyB,EAAE,iBAAiB,EAAE,CAyB7D"}
+{"version":3,"file":"particle_builtin_groups.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/particles/graph/groups/particle_builtin_groups.js"],"names":[],"mappings":"AA+BA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;;GAQG;AACH,sCAFU,OAAO,yBAAyB,EAAE,iBAAiB,EAAE,CAiC7D"}

package/src/shade/renderer/particles/graph/groups/particle_builtin_groups.js

@@ -1,9 +1,13 @@
 import { register_particle_group } from "../particle_group_library.js";
 import {
     PARTICLE_GROUP_ANGLE_BETWEEN,
+    PARTICLE_GROUP_EMITTER_ROTATION,
     PARTICLE_GROUP_QUAT_FROM_AXIS_ANGLE,
+    PARTICLE_GROUP_QUAT_INTEGRATE,
     PARTICLE_GROUP_QUAT_LOOK_ROTATION,
+    PARTICLE_GROUP_QUAT_MULTIPLY,
     PARTICLE_GROUP_QUAT_ROTATE,
+    PARTICLE_GROUP_SAMPLE_ROTATION,
     PARTICLE_GROUP_SAMPLE_SPHERE_SURFACE,
     PARTICLE_GROUP_SAMPLE_SPHERE_VOLUME,
 } from "./particle_groups_geometry.js";
@@ -74,6 +78,14 @@ export const PARTICLE_BUILTIN_GROUPS = [
     PARTICLE_GROUP_PSRDNOISE_3,
     PARTICLE_GROUP_CURL_3,
     PARTICLE_GROUP_CURL_4,
+
+    // rotations for the orientation channel — appended rather than filed with the rotations above,
+    // because a group's description id is allocated in registration order and filing them there
+    // would renumber every group after them
+    PARTICLE_GROUP_QUAT_MULTIPLY,
+    PARTICLE_GROUP_QUAT_INTEGRATE,
+    PARTICLE_GROUP_SAMPLE_ROTATION,
+    PARTICLE_GROUP_EMITTER_ROTATION,
 ];
 
 for (const group of PARTICLE_BUILTIN_GROUPS) {

package/src/shade/renderer/particles/graph/groups/particle_groups_geometry.d.ts

@@ -80,4 +80,64 @@ export const PARTICLE_GROUP_QUAT_ROTATE: import("../ParticleNodeGroup.js").Parti
  * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
  */
 export const PARTICLE_GROUP_QUAT_LOOK_ROTATION: import("../ParticleNodeGroup.js").ParticleNodeGroup;
+/**
+ * Two rotations, one after the other: the turn by `b`, then the turn by `a`.
+ *
+ * The Hamilton product, `(a.w b.xyz + b.w a.xyz + a.xyz × b.xyz, a.w b.w - a.xyz · b.xyz)`, in the
+ * order the engine's `Quaternion.multiplyQuaternions(a, b)` writes it — so turning a vector by the
+ * result is turning it by `b` and then by `a`. Not commutative: swapping the inputs turns about the
+ * other frame.
+ *
+ * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
+ */
+export const PARTICLE_GROUP_QUAT_MULTIPLY: import("../ParticleNodeGroup.js").ParticleNodeGroup;
+/**
+ * An orientation advanced by an angular velocity over a step: `quat` turned by `omega`, in radians
+ * per second about the axis it points along, for `dt` seconds.
+ *
+ * Exact for a constant `omega` at any `dt` — the step is the rotation itself,
+ * `quatFromAxisAngle(omega, |omega| dt)`, composed in front — rather than the first-order
+ * `q + dt/2 (omega, 0) q` a rigid-body solver takes. That one turns by `2 atan(|omega| dt / 2)` instead
+ * of `|omega| dt`, which a solver stepping at a fixed 1/60 never notices, and a particle does: the
+ * warm-up stretches its ticks to cover a whole pre-warm in at most
+ * {@link ../../ParticleConstants.js PARTICLE_WARMUP_MAX_TICKS} of them, 156 ms each for five seconds,
+ * where a 10 rad/s tumble would come out 15% slow. A program does not get to care what `dt` it is
+ * handed.
+ *
+ * `omega` turns in the frame the orientation is in — the world, for a FACING_WORLD emitter — which is
+ * why the step goes in front. The result is renormalised, so a tumble integrated for a minute is
+ * still a unit quaternion and `quatRotate` does not start scaling what it turns. A zero `omega` is
+ * no turn.
+ *
+ * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
+ */
+export const PARTICLE_GROUP_QUAT_INTEGRATE: import("../ParticleNodeGroup.js").ParticleNodeGroup;
+/**
+ * A rotation drawn uniformly from all of them, from three numbers in `[0, 1)`.
+ *
+ * Shoemake's construction ("Uniform random rotations", Graphics Gems III): with `u` the first number,
+ * the quaternion is `(sqrt(1-u) sin 2πv, sqrt(1-u) cos 2πv, sqrt(u) sin 2πw, sqrt(u) cos 2πw)`. It
+ * lands on the unit sphere in four dimensions uniformly, which is what a uniform rotation is. Drawing
+ * three Euler angles uniformly is the tempting wrong one, and clusters the turns.
+ *
+ * Feed it a three-lane `random` and it is a tumbling flake's starting orientation.
+ *
+ * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
+ */
+export const PARTICLE_GROUP_SAMPLE_ROTATION: import("../ParticleNodeGroup.js").ParticleNodeGroup;
+/**
+ * The emitter's own rotation: the turn that takes the world's axes to its node's.
+ *
+ * The VM hands an effect the node's axes rather than its rotation — `EMITTER_DIRECTION`, which is the
+ * node's forward and so its **-Z**, and `EMITTER_UP`, its +Y — and a look rotation maps **+Z** to the
+ * forward it is given. Wiring the two straight together therefore turns a sprite half a turn and
+ * shows its back. This is that wiring with the sign put right, which is the whole reason it is a
+ * group.
+ *
+ * Write it into a FACING_WORLD particle's orientation at birth and the sprite starts out lying in
+ * its emitter's XY plane, facing the emitter's +Z.
+ *
+ * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
+ */
+export const PARTICLE_GROUP_EMITTER_ROTATION: import("../ParticleNodeGroup.js").ParticleNodeGroup;
 //# sourceMappingURL=particle_groups_geometry.d.ts.map

package/src/shade/renderer/particles/graph/groups/particle_groups_geometry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"particle_groups_geometry.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/particles/graph/groups/particle_groups_geometry.js"],"names":[],"mappings":"AAqCA;;;;;;;;;;;GAWG;AACH,mDAFU,OAAO,yBAAyB,EAAE,iBAAiB,CAsBxD;AAEL;;;;;;;;;GASG;AACH,kDAFU,OAAO,yBAAyB,EAAE,iBAAiB,CAmBxD;AAEL;;;;;;;;;;;;GAYG;AACH,2CAFU,OAAO,yBAAyB,EAAE,iBAAiB,EAAE,CAiB5D;AAEH;;;;;;;;GAQG;AACH,kDAFU,OAAO,yBAAyB,EAAE,iBAAiB,CAsBxD;AAEL;;;;;;;;;;;GAWG;AACH,yCAFU,OAAO,yBAAyB,EAAE,iBAAiB,CAuBxD;AAEL;;;;;;;;;;;;;;;;;;;GAmBG;AACH,gDAFU,OAAO,yBAAyB,EAAE,iBAAiB,CA+ExD"}
+{"version":3,"file":"particle_groups_geometry.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/particles/graph/groups/particle_groups_geometry.js"],"names":[],"mappings":"AAsCA;;;;;;;;;;;GAWG;AACH,mDAFU,OAAO,yBAAyB,EAAE,iBAAiB,CAsBxD;AAEL;;;;;;;;;GASG;AACH,kDAFU,OAAO,yBAAyB,EAAE,iBAAiB,CAmBxD;AAEL;;;;;;;;;;;;GAYG;AACH,2CAFU,OAAO,yBAAyB,EAAE,iBAAiB,EAAE,CAiB5D;AAEH;;;;;;;;GAQG;AACH,kDAFU,OAAO,yBAAyB,EAAE,iBAAiB,CAsBxD;AAEL;;;;;;;;;;;GAWG;AACH,yCAFU,OAAO,yBAAyB,EAAE,iBAAiB,CAuBxD;AAEL;;;;;;;;;;;;;;;;;;;GAmBG;AACH,gDAFU,OAAO,yBAAyB,EAAE,iBAAiB,CA+ExD;AAEL;;;;;;;;;GASG;AACH,2CAFU,OAAO,yBAAyB,EAAE,iBAAiB,CA0BxD;AAEL;;;;;;;;;;;;;;;;;;;GAmBG;AACH,4CAFU,OAAO,yBAAyB,EAAE,iBAAiB,CA0BxD;AAEL;;;;;;;;;;;GAWG;AACH,6CAFU,OAAO,yBAAyB,EAAE,iBAAiB,CA6BxD;AAEL;;;;;;;;;;;;;GAaG;AACH,8CAFU,OAAO,yBAAyB,EAAE,iBAAiB,CAkBxD"}